Many Tools: Tool Search
Every tool’s name, description and schema is sent to the model on every step. With a few tools that is nothing; with hundreds it fills the context and the model chooses worse. Turn on tool search and the model is sent one tool,tools_retriever, instead of your catalog. It describes what it needs, and the
matching tools are offered from the next step.
The output below is what the code printed when it was run. The model’s query
and wording will differ on your run.
Thirty-three tools, one question
How it works
- At the start of each run, the runtime builds a catalog of every tool the agent has: your local tools, MCP tools, and the harness’s own.
- Some stay visible without a search:
tools_retrieveritself, the workspace tools (ls,read_file,write_file,edit_file,insert_file,delete_file,move_file,clear_files,glob,grep), the artifact tools (read_artifact,tail_artifact,search_artifact,list_artifacts),read_skill_file,run_skill_script,spawn_subagents, and eachdelegate_<name>tool for a sub-agent. - Everything else is hidden until found: your tools, MCP tools, code mode’s
run_code, and the sandbox’sexecute. tools_retriever(query)ranks the hidden tools by BM25 over each tool’s name, description and parameter schema, and returns up to five that match at least one word of the query.snake_caseandcamelCasenames are split into words, soconvert_currencymatches “currency”.- The tools it returned are offered from the next model step, for the rest of the run. A call in the same batch as the search cannot use them.
Options
That is the only setting. The rest of the agent’s settings are in the
agent settings reference.
Write tools that can be found
- Put the words a model would search for in the description: “Convert an amount of money from one currency to another” is found by “currency”, “convert” and “money”.
- Name tools by what they do (
convert_currency), not by a system’s internal code (fx_v2_proc). - Keep it on only when the catalog is large. With a handful of tools, the extra search step costs a model turn and gains nothing.
When things go wrong
The model says it cannot do something a tool could
The model says it cannot do something a tool could
The search found nothing. It returns only tools that share a word with the
query, and the model is told to try a more specific query when nothing
relevant comes back. Put the words users and models actually say into the
tool’s description.
Next
Local tools
Your functions as tools: schemas, results, errors.
MCP tools
Bring in a server’s tools; they are searchable too.
Code mode
Many calls in one step, from a short Python program.
Read the trajectory
Every search, and every call it led to, is on the record.