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) }

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"

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)

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.