class RubyLLM::Tool

Keeps this tool’s definition out of the model’s context until the provider’s tool search loads it. Pass +defer: false+ to Chat#with_tools to offer it up front in one chat. See Chat#deferred_tools.

class DeepResearch < RubyLLM::Tool
  description "Runs a multi-step web investigation"
  defer
end

Sets the description the model sees for this tool, or returns the current description when called without an argument.

class Weather < RubyLLM::Tool
  description "Gets current weather for a location"
end

Sets how long a run of this tool may take before a persisted chat treats it as crashed, overriding Configuration#max_run_time. Another process that resumes the chat after that time runs the call again. Without an argument, returns the declared value, or nil.

class GenerateReport < RubyLLM::Tool
  max_run_time 2.hours
end

Declares a parameter for the tool. options accepts type: (defaults to 'string'), description:, and required: (defaults to true).

class Distance < RubyLLM::Tool
  description "Calculates distance between two cities"
  parameter :origin, description: "Origin city name"
  parameter :destination, description: "Destination city name"
  parameter :units, type: :string, description: "metric or imperial", required: false
end

Sets the JSON Schema for the tool’s arguments. Accepts a schema hash, a Schematist::Schema class or instance, or a block written in the schematist DSL. Returns self.

class Scheduler < RubyLLM::Tool
  description "Books a meeting"

  parameters do
    object :window, description: "Time window to reserve" do
      string :start, description: "ISO8601 start time"
      string :finish, description: "ISO8601 end time"
    end
    array :participants, of: :string
  end
end

Raises ArgumentError when called without a schema or a block.

Sets provider-specific metadata, such as Anthropic’s cache_control hints, merged verbatim into the tool payload sent to the provider. Without an argument, returns the current options.

provider_options cache_control: { type: "ephemeral" }

Raises ArgumentError if options is nil.

Declares that this tool must be approved before it executes. The conversation loop pauses the tool call until a decision is recorded with Chat#approve or Chat#deny, so Chat#complete returns cleanly and can be called again once the decision exists. In Rails the decision persists on the tool call record and survives process restarts.

class IssueRefund < RubyLLM::Tool
  requires_approval

  def execute(order_id:)
    Refunds.issue!(order_id)
  end
end

Pass a block to resolve the decision yourself instead of using the recorded one. The block receives the ToolCall and returns true to execute, false to deny, or nil while the decision is pending.

The block never runs at class definition. The loop consults it whenever it needs the decision, which can be several times while the call is pending, including after a crashed job resumes, so write it as an idempotent read. If it also creates the approval request, make that a find-or-create.

requires_approval { |tool_call| Approvals.status(tool_call.id) }

Sets how many characters this tool’s results may have before a chat with files saves them as a file and sends the model their start and the file’s path, overriding the chat’s own limit (see Chat#with_file_store). false always sends them whole, for tools that already return what they find in pages. Without an argument, returns the declared value, or nil.

class ExportOrders < RubyLLM::Tool
  spill_to_file 50_000
end

Returns the name the model calls this tool by, derived from the class name: underscored, reduced to ASCII, with a trailing “_tool” removed. Override this method to choose a different name.

WeatherLookup.tool_name  # => "weather_lookup"

Asks the user something while execute runs, and returns their InputRequest::Answer. In a chat, the call pauses until Chat#answer or Chat#decline settles the question (see Chat#pending_inputs), then runs again from the start, and this ask returns the answer. Code before it runs again too, so do work after asking. Pass the fields to ask for as JSON Schema properties, with required: true on the ones the user must fill, or url: to ask them to visit a page.

def execute(question:)
  answer = ask(question, answer: { type: "string", title: "Answer" })
  answer.accepted? ? { answer: answer[:answer] } : { error: "Nobody answered." }
end

Each call may ask several questions, one after another. Outside a chat, an unanswered question raises InputRequiredError. url: is reserved for the page, so name a form field for a URL something else.

Runs the tool with keyword arguments, validating them against the execute signature before invoking it. RubyLLM supplies tool_call: when the call comes from a chat; pass it yourself only when you need the ToolCall in a direct invocation.

Weather.new.call(latitude: 52.52, longitude: 13.405)

Keeps this tool, and no other of its class, out of the model’s context until tool search loads it, as ::defer does for the class. Returns self. Chat#with_tools and Chat#with_mcp take defer: to decide for every tool they register instead.

chat.with_tools(CurrentTime.new, *connector_tools.map(&:defer))

Returns whether this tool waits to be found by tool search: whether it was deferred with defer, or its class with ::defer.

Returns the tool description declared on the class with ::description.

Runs the tool with the arguments chosen by the model. Subclasses must implement this method; the base implementation raises NotImplementedError. The return value is sent back to the model. Return a Hash like { error: "..." } to report a recoverable failure.

Declare an optional tool_call: keyword to receive the ToolCall being executed. The keyword is reserved: it never appears in the tool’s argument schema and is filled in by RubyLLM, not by the model.

def execute(query:, tool_call: nil)
  AuditLog.create!(tool_call_id: tool_call&.id)
  Search.run(query)
end

Returns the run time declared on the class with ::max_run_time, or nil to use Configuration#max_run_time.

Returns the name the model calls this tool by, delegating to ::tool_name. Override either one to choose a different name.

WeatherLookup.new.name  # => "weather_lookup"

Returns the JSON Schema for the tool’s arguments, whether declared explicitly or inferred from the execute signature.

Reports what the tool is doing while execute runs, so an application can show it before the result arrives. Chat#after_tool_progress callbacks receive it as a Progress. Pass value: and total: when you can count the work. Outside a chat, the report goes nowhere.

def execute(url:)
  progress "Downloading #{File.basename(url)}"
  pages = Scanner.pages(url)
  pages.each_with_index.map do |page, index|
    progress "Reading page #{index + 1} of #{pages.size}", value: index + 1, total: pages.size
    page.text
  end.join("\n")
end

Returns the provider-specific tool metadata declared on the class.

Returns whether tool_call must be approved before it runs: whether this tool was declared with ::requires_approval. A subclass may override it to decide from the call’s arguments.

Carries on a call that paused on task, the Task execute returned, with the call’s arguments. Each Chat#complete calls it once for every paused call of the round. Return the call’s result to finish it, or a Task, task itself or a new one, to keep it paused. Tools that return a Task must implement this method; the base implementation raises NotImplementedError.

def resume(task, **)
  run = SubAgentRun.find(task.data["run_id"]).continue
  run.finished? ? run.answer : task
end

Returns the limit declared on the class with ::spill_to_file: a number of characters, false, or nil to use the chat’s.

Returns the Task that tool_call paused on, from state, the Hash Task#to_h returned. Override it to return a Task subclass.

def task(state, tool_call: nil)
  SubAgentTask.load(state, tool_call:)
end