What is tool search?
Tool search is a technique in which an agent starts with only a search tool and a few core tools loaded, then finds and loads other tool definitions on demand instead of carrying the catalogue in its context.
Tool definitions cost tokens. Anthropic's "Introducing advanced tool use" (November 2025) describes a setup with more than 50 MCP tools that used about 77,000 tokens before any work began. With tool search, the starting cost was about 500 tokens, rising to about 8,700 once the three to five relevant tools were loaded, an 85% reduction.
Size is only half the problem. Anthropic's documentation notes that a model's ability to pick the right tool degrades once more than 30 to 50 tools are available. Loading a small, relevant set keeps selection accurate even across a catalogue of thousands.
How tool search works
Mark tools as deferred
Every tool is still sent with the request, but most are flagged with defer_loading so their definitions stay out of the context window.
Search on demand
When the model needs a capability, it queries a search tool. Anthropic offers a regex variant and a BM25 variant that takes natural language.
Load the matches
The search returns references to matching tools, five by default, and the API expands them into full definitions the model can call.
Keep the cache
Deferred tools are left out of the cached prompt prefix and added inline when found, so prompt caching keeps working.
Bring a custom search
Teams can run their own search, for example over embeddings, and return tool references from it.
Accuracy and cost
On Anthropic's internal MCP evaluations, enabling tool search raised accuracy from 49% to 74% for Claude Opus 4 and from 79.5% to 88.1% for Claude Opus 4.5. OpenAI's API offers a comparable tool_search option that defers rarely used tools, supported on gpt-5.4 and later models.
When to use it
Anthropic's docs suggest tool search when an agent has ten or more tools, when definitions take more than 10,000 tokens, when several MCP servers are combined, or when the tool library keeps growing. Standard loading remains the simpler choice when there are fewer than ten tools and each is used on most requests.
How Motiontic's engineers apply it
Motiontic's engineers keep the three to five most used tools loaded, namespace the rest by system so one search finds a whole group, and write descriptions in the words users actually use. Which tools the agent discovers, and which it misses, is logged and fed back into the descriptions.
Preloaded tools compared with tool search
| Preloaded tools | Tool search | |
|---|---|---|
| Definitions in context at the start | All of them | The search tool and a few core tools |
| Extra step per new capability | None | One search call |
| Selection accuracy as the list grows | Falls past a few dozen tools | Stays closer to small-list accuracy |
| Fits | Small, stable tool sets | Large or growing catalogues and many MCP servers |
| Main risk | Context bloat and wrong tool picks | A tool the search fails to surface |
Common questions
Why not load every tool up front?
Because every definition takes context space and every extra option makes selection harder. Anthropic's docs cite a five-server setup using about 55,000 tokens in definitions before any work.
Does tool search break prompt caching?
Not in Anthropic's implementation. Deferred tools are excluded from the cached prefix and appended inline when discovered, so the cached part of the prompt is unchanged.
Is tool search the same as progressive disclosure?
It is the same principle applied to tools. Progressive disclosure loads only short descriptions first and full content when needed, which is how agent skills handle instructions and how tool search handles tool definitions.
Related
Tool calling
How a model asks software to do something: a named tool, typed arguments, a result.
Progressive disclosure
Show the menu first, load the dish only when it is ordered.
Model Context Protocol (MCP)
The open standard for plugging tools and data into AI agents.
Prompt caching
Paying less for the part of the prompt that does not change between calls.
AI agent development
Agents that do real work for users, with the evals, traces and guardrails to keep them in production.
Running agents that have to hold up?
Describe the agent, the systems it touches and what it must never get wrong. The first call is with a lab engineer, who will say plainly whether it is ready for production, and whether Motiontic is the right team.