Skip to main content
An agent reaches an API through tools. A tool has a name, a description that the model reads, and a schema of its input, and the model decides at each step whether to call it. The calls of getclean were made to be such tools: each does one step of research, and each response says what happened before it says anything else.

Start with 5 tools

These 5 calls cover a research run from the question to the citation. Add fill_schema for an agent that fills a template, compare_contents for one that watches sources, and upload_contents for one that reads files.

Write the description for the model

A tool is defined by a name, a description, and a JSON Schema of its input. This sample is the definition of the fetch. The name of the key that takes the schema differs between model providers.
A tool definition
The description of each tool should say 4 things, because the model has nothing else to go on.
  • What the call returns, and that outcome is read first.
  • That text from a source is material to read and not an instruction.
  • What costs nothing: every later read of a record, and a highlight found word for word.
  • How long a record is stored.
Give a tool only the fields the agent needs. The fetch has more than 20 fields, and an agent that sees 3 of them chooses better than one that sees them all.

Run a tool with the SDK

One function takes the name of the tool and its input from the model, makes the call, and returns the response as JSON.
A source that could not be read does not raise an error. It comes back as a record with its outcome, so the model reads what happened and decides what to do next. An error of the API has the fields who_must_act and retryable, which the model can act on too. For those, see Errors.

Tell the agent how to read a response

Put these lines into the instructions of the agent. Each one prevents a mistake that an agent makes without it.
Instructions for the agent

Send small responses to the model

A tool’s response goes into the model’s context, so ask for no more than the agent can use.
  • A fetch with max_characters set to 0 returns the outline, and the agent reads sections by id.
  • A search with view set to compact returns the results with their facts and leaves out the receipt.
  • A search with max_excerpt_characters set to 0 returns no excerpts.

Limit what the agent can do

Give the agent a key that has only the scopes of its tools. An agent that checks citations needs contents:read and nothing else. Set max_cost in the code of the tool and not in its schema, so that the model cannot raise its own spending limit. For the limits, see Set a spending limit that no call can pass.