The fundamentals · 06
Tools
Tools are callable functions that agents can invoke to interact with external systems, fetch data, or perform actions.
When to Use Tools
Use tools when your agent needs to fetch external data, call APIs, query databases, or perform side effects. If the agent only needs to generate text from its training data, you do not need tools.
Defining a Tool
Create a tool by subclassing Riffer::Tool:
class WeatherTool < Riffer::Tool
description "Gets the current weather for a city"
params do
required :city, :string, description: "The city name"
optional :units, :string, default: "celsius", enum: ["celsius", "fahrenheit"]
end
def call(context:, city:, units: nil)
weather = WeatherAPI.fetch(city, units: units || "celsius")
text("The weather in #{city} is #{weather.temperature} #{units}.")
end
end
Configuration Methods
description
Sets a description that helps the LLM understand when to use the tool:
class SearchTool < Riffer::Tool
description "Searches the knowledge base for relevant information"
end
identifier / name
Sets a custom identifier (defaults to snake_case class name):
class SearchTool < Riffer::Tool
identifier 'kb_search'
end
SearchTool.identifier # => "kb_search"
SearchTool.name # => "kb_search" (alias)
params
Defines the tool’s parameters using a DSL:
class CreateOrderTool < Riffer::Tool
params do
required :product_id, :integer, description: "The product ID"
required :quantity, :integer, description: "Number of items"
optional :notes, :string, description: "Order notes"
optional :priority, :string, default: "normal", enum: ["low", "normal", "high"]
end
end
Parameter DSL
required
Defines a required parameter:
params do
required :name, :string, description: "The user's name"
required :age, :integer, description: "The user's age"
end
Options:
description- Human-readable description for the LLMenum- Array of allowed values (for the innermost items of an:arraywithof:)format- String format such as"date"or"email"(for the innermost:stringitems of an:array; see Formats)
optional
Defines an optional parameter:
params do
optional :limit, :integer, default: 10, description: "Max results"
optional :format, :string, enum: ["json", "xml"], description: "Output format"
end
Options:
description- Human-readable descriptiondefault- Default value when not providedenum- Array of allowed values (for the innermost items of an:arraywithof:)format- String format such as"date"or"email"(for the innermost:stringitems of an:array; see Formats)
Supported Types
| Type | JSON Schema type | Validated value | Deprecated class |
|---|---|---|---|
:string |
string |
String |
String |
:integer |
integer |
Integer |
Integer |
:number |
number |
Float |
Float |
:boolean |
boolean |
true or false |
Riffer::Params::Boolean, TrueClass, FalseClass |
:array |
array |
Array |
Array |
:object |
object |
Hash with symbol keys |
Hash |
:any_of |
anyOf of objects or primitives |
The value of the matching variant | Riffer::Params::AnyOf |
required, optional, of: and variant still accept the deprecated Ruby classes, and each line that uses one reports a deprecation. They won’t be removed before 1 December 2026.
A :number param accepts a whole number too, since JSON Schema’s number covers integers — a model returning 120 for a :number is valid, and the validated value is coerced to 120.0. :integer stays strict: 1.0 is rejected, matching JSON Schema’s integer.
Nested Parameters
Tool params support the same nested DSL as structured output — nested objects (:object with block), typed arrays (:array, of:), arrays of arrays (:array, of: [:integer]), arrays of objects (:array with block), and either/or shapes (:any_of with variants). See the structured output section in Agents for full syntax.
class CreateOrderTool < Riffer::Tool
description "Creates an order"
params do
required :items, :array, description: "Line items" do
required :product_id, :integer
required :quantity, :integer
optional :notes, :string
end
required :shipping, :object, description: "Shipping address" do
required :street, :string
required :city, :string
optional :zip, :string
end
end
def call(context:, items:, shipping:)
# items is an Array of Hashes with symbolized keys
# shipping is a Hash with symbolized keys
end
end
Looking Up Tools
Look up a tool by identifier with Riffer::Tool.find, or list every tool with Riffer::Tool.all:
Riffer::Tool.find('kb_search') # => SearchTool
Riffer::Tool.find(:kb_search) # symbols work too
Riffer::Tool.find('missing') # => nil
Riffer::Tool.all # => [SearchTool, ...]
Only named direct subclasses are found implicitly:
- Grandchildren are not visible to a grandparent’s
findorall. If your app defines an intermediate base class (class ApplicationTool < Riffer::Tool), callfind/allon the intermediate class to look up its subclasses. - Anonymous classes (
Class.new(Riffer::Tool)) are never findable implicitly, even when they set an explicitidentifier— see Registering a tool explicitly. - Two subclasses sharing an identifier raise
Riffer::DuplicateIdentifierErrorat the first lookup. - A subclass whose constant no longer points at it — after a Zeitwerk reload or an RSpec
stub_const— drops out offindandall. The check runs when the registry is rebuilt, which defining, registering, or unregistering a subclass triggers; removing or restoring a constant on its own does not, so lookups keep returning the old class until the next rebuild.
Registering a tool explicitly
Testing a tool that gets resolved by identifier? Use Riffer::Testing — stub_tool builds and registers a throwaway tool and cleans it up for you. The API below is the manual alternative, for production wiring and anything outside the stub lifecycle.
register adds a tool to its parent’s registry by hand and unregister removes it:
Riffer::Tool.register(tool) # findable until unregistered
Riffer::Tool.unregister(tool) # no-op if it was never registered
Explicit registration differs from implicit in a few ways:
- Anonymous classes are allowed, as long as they declare an
identifier. A blank identifier raisesRiffer::ArgumentError. - The class must be a direct subclass of the receiver, mirroring implicit registration.
Riffer::Tool.register(SomeAppTool)raisesRiffer::ArgumentErrorwhenSomeAppTooldescends from an intermediate base — callregisteron that base instead. - Taking an identifier already held by another tool, implicit or explicit, raises
Riffer::DuplicateIdentifierError. Re-registering the same class raises too; there is no idempotent path. - The registration survives until you remove it — it is never dropped for a stale constant.
Registration is not synchronized. Register during boot or from a single-threaded test, before concurrent lookups begin.
The call Method
Every tool must implement the call method and return a Riffer::Tools::Response:
def call(context:, **kwargs)
# context - The context passed to agent.generate()
# kwargs - Validated parameters
#
# Must return a Riffer::Tools::Response
end
Accessing Context
The context argument is a Riffer::Agent::Context — a typed value object wrapping the Hash passed as context: to Agent.new. Caller-provided keys are read with context[:key] or context&.dig(:key):
class UserOrdersTool < Riffer::Tool
description "Gets the current user's orders"
def call(context:)
user_id = context&.dig(:user_id)
unless user_id
return error("No user ID provided")
end
orders = Order.where(user_id: user_id)
text(orders.map(&:to_s).join("\n"))
end
end
# Usage
MyAgent.new(context: {user_id: 123}).generate("Show my orders")
Three keys are framework-managed and exposed as typed accessors:
context.skills— the resolvedRiffer::Skills::Contextwhen the agent has skills configured, otherwisenil.context.token_usage— the cumulativeRiffer::Providers::TokenUsageacross every run on the agent, ornilbefore the first response.context.deferred_tools— the agent’s deferred tools, loaded or not ([]when it has none).
Passing your own :deferred_tools key in context: is deprecated: it still works, and context[:deferred_tools] returns your value, but it prints a deprecation warning, and a future breaking release reserves the key. Rename it.
Response Objects
All tools must return a Riffer::Tools::Response object from their call method. Riffer::Tool provides shorthand methods for creating responses.
Success Responses
Use text for string responses and json for structured data:
def call(context:, query:)
results = Database.search(query)
if results.empty?
text("No results found for '#{query}'")
else
text(results.map { |r| "- #{r.title}: #{r.summary}" }.join("\n"))
end
end
text
Converts the result to a string via to_s:
text("Hello, world!")
# => content: "Hello, world!"
text(42)
# => content: "42"
json
Converts the result to JSON via to_json:
json({name: "Alice", age: 30})
# => content: '{"name":"Alice","age":30}'
json([1, 2, 3])
# => content: '[1,2,3]'
Error Responses
Use error(message, type:) for errors:
def call(context:, user_id:)
user = User.find_by(id: user_id)
unless user
return error("User not found", type: :not_found)
end
text("User: #{user.name}")
end
The error type is any symbol that describes the error category:
error("Invalid input", type: :validation_error)
error("Service unavailable", type: :service_error)
error("Rate limit exceeded", type: :rate_limit)
If no type is specified, it defaults to :execution_error. Riffer reserves :unhandled_error for unrescued exceptions, and :invalid_tool_load and :tool_not_loaded for deferred tools — don’t set them yourself.
Using Riffer::Tools::Response Directly
The shorthand methods delegate to Riffer::Tools::Response. You can also use the class directly if preferred:
Riffer::Tools::Response.text("Hello")
Riffer::Tools::Response.json({data: [1, 2, 3]})
Riffer::Tools::Response.error("Failed", type: :custom_error)
Riffer::Tools::Response.load_tools([ListEvents])
Response Methods
response = text("result")
response.content # => "result"
response.success? # => true
response.error? # => false
response.error_message # => nil
response.error_type # => nil
error_response = error("failed", type: :not_found)
error_response.content # => "failed"
error_response.success? # => false
error_response.error? # => true
error_response.error_message # => "failed"
error_response.error_type # => :not_found
error_response.exception # => nil
exception holds the rescued exception on the :unhandled_error responses Riffer builds. It never appears in serialized output, so it is not visible to the LLM.
Loading deferred tools (experimental)
An agent can hold tools back with deferred_tools. Any of its own tools loads them by returning load_tools(tools), and context.deferred_tools lists the tools it can choose from. A search tool, a browse tool or a “connect your calendar” tool is an ordinary tool:
class FindTools < Riffer::Tool
description "Find more tools for a task. Describe what you need to do in a few words."
params { required :query, :string }
def call(context:, query:)
words = query.downcase.split
matches = context.deferred_tools.select { |tool| words.any? { |w| tool.description.downcase.include?(w) } }
load_tools(matches.first(5))
end
end
class ConnectCalendar < Riffer::Tool
description "Connect the user's calendar. Calendar tools become available afterwards."
def call(context:)
Calendars.connect!(context[:user])
load_tools([ListEvents, CreateEvent])
end
end
How a load reaches the model depends on the agent’s strategy. By default Anthropic, OpenAI and Azure OpenAI load deferred tools natively; with strategy: :gateway, any provider goes through the gateway.
A load takes effect from the model’s next turn. The model made every call in a turn before it saw any of that turn’s results, so a call to a tool loaded in the same turn is refused like any other unloaded call; the model calls it again once it has seen the load.
- A load can’t carry text as well, because Anthropic rejects a tool result that mixes loaded tools with text.
load_toolstakes no text, and the response’scontentis"". load_tools([])is a successful load of nothing.- Loading a tool that isn’t one of the agent’s deferred tools, including one in
uses_tools, returns an:invalid_tool_loaderror to the model instead, and nothing in that load is loaded. - Loading a tool that’s already loaded succeeds and changes nothing: the tool is loaded once, and stays loaded for the rest of the conversation. Tools can’t be unloaded.
- A call to a deferred tool that hasn’t been loaded isn’t run. The model gets an error result of type
:tool_not_loaded(Tool 'list_events' has not been loaded). Riffer checks this itself, before the tool runtime sees the call, so a custom runtime can’t run an unloaded tool by mistake. That includes a call forced by a provider’s owntool_choicepassed throughmodel_options, and an unloaded call already in a restored history.
response.loaded_tools returns the tools a response loads, and is [] on every other response. Riffer records the loaded tools’ names on the tool message as loaded_tools.
Loading puts the loaded tools’ full schemas into the conversation, and every load is an extra round trip to the model, so load a handful of tools at a time rather than dozens.
The gateway strategy
With deferred_tools [...], strategy: :gateway, riffer doesn’t use the provider’s native loading, so it works on every provider, custom ones included. Adding a loaded tool to the request’s tools partway through a conversation would break the prompt cache on every load, so riffer keeps the tool list fixed and sends one extra tool instead, Riffer::Providers::DeferredToolGateway::Tool, the gateway, named riffer_gateway:
- Every request with deferred tools carries the gateway after the agent’s other tools, before any load and after it. Its name, description and schema never change, and the deferred tools themselves are never in the tool list, so the tool list is the same for the whole conversation.
- The gateway takes two required string parameters and nothing else:
name, the loaded tool’s name, andarguments, the loaded tool’s arguments as a JSON-encoded object ("{\"query\":\"red shoes\",\"limit\":5}"). Strings rather than a free-form object keep the schema valid for providers that send tools in strict mode, such as OpenRouter. Riffer still validates the arguments against the real tool’sparamswhen the tool runs. - A tool result that loads tools is sent to the model with an instruction to call them through the gateway, by its wire name, appended to its content, followed by the loaded tools as one JSON array of
name,descriptionandparameters. The text is the same every time it is sent, so the earlier conversation doesn’t change and the cache holds. Only the request carries it: the tool message in the session keeps its own content. A load that names a tool the agent no longer defers, for example in a restored history, describes nothing for that tool. - The model’s call to the gateway comes back as a call to the real tool, named by
namewithargumentsas its arguments, before the provider returns. The session,on_messagecallbacks, the tool runtime, the:tool_not_loadedcheck and traces all see the real tool. A streamed gateway call yields only itsToolCallDone, under the real tool’s name: itsToolCallDeltaevents carry pieces of the gateway’s own arguments, so riffer drops them. - On later requests, a call to a deferred tool in the history is sent back as a gateway call, and its result under the gateway’s name, keeping its
tool_call_id, so the provider never sees a call to a tool missing from the tool list. - A gateway call riffer can’t read, because its arguments aren’t a JSON object with a string
nameand a stringargumentsor itsnameisn’t one of the agent’s deferred tools, stays a call to the gateway, which no agent has as a tool, so the model gets an:unknown_toolerror result and can try again.
An agent with the gateway strategy can’t have a tool of its own with the gateway’s name, in uses_tools or deferred_tools: building it raises Riffer::ArgumentError. Like the rest of deferred tools, the gateway is experimental, and its name, description and the text it adds to a load can change in any minor release.