Tool search vs. loading every tool definition up front

1.What a monolithic toolset costs

The simplest way to give an agent capabilities is to put every tool definition in the request and let all of them load into context. Call this the monolithic strategy. It works for a handful of tools. As the library grows, the tool search documentation describes two separate ways it breaks down.

The first is context bloat. Definitions use up tokens before Claude has done anything. The documentation's example is a typical multiserver setup with GitHub, Slack, Sentry, Grafana and Splunk, which can consume ~55k tokens in definitions alone. The Agent SDK documentation gives a smaller-scale version: 50 tools can use 10–20K tokens, which leaves less room for the work itself.

The second is tool selection accuracy. Beyond 30–50 available tools, Claude gets worse at choosing the right one. The extra definitions add noise as well as cost.

Progressive discovery addresses both. Tool search typically reduces definition tokens by over 85 percent and loads only the 3–5 tools a given request needs. Because Claude only ever sees a small, relevant set, selection accuracy stays high even across a catalog of thousands of tools. The SDK documentation gives the ceiling as 10,000 tools per catalog.

Sources12

2.How tool search works: defer_loading and tool_reference

On the Claude API, progressive discovery is built into the tool search tool. It runs on the server and comes in two variants. With tool_search_tool_regex_20251119, Claude writes regex patterns. With tool_search_tool_bm25_20251119, Claude writes natural-language queries. Both search tool names, descriptions, argument names and argument descriptions. Claude Opus 4.1 and earlier don't support it.

You add the search tool to your tools array and mark the tools that shouldn't load up front with defer_loading: true. The flag is easy to misread. It controls what goes into the context window, not what goes into the request. You still send every full definition on every request, deferred ones included, because the API needs them on the server to run the search and to expand the results.

This is not all-or-nothing. At least one tool has to stay non-deferred, normally the search tool itself, and you must never defer the search tool. The documentation also recommends keeping your 3–5 most frequently used tools non-deferred so Claude can call them without searching first. In practice, then, progressive discovery is a hybrid: a small core that is always loaded, with a searchable catalog behind it.

{
  "type": "tool_search_tool_regex_20251119",
  "name": "tool_search_tool_regex"
}

{
  "name": "get_weather",
  "description": "Get current weather for a location",
  "input_schema": {
    "type": "object",
    "properties": {
      "location": { "type": "string" },
      "unit": { "type": "string", "enum": ["celsius", "fahrenheit"] }
    },
    "required": ["location"]
  },
  " ? ": true
}

At runtime, Claude's context initially holds only the search tool and any non-deferred tools. When Claude needs something else, it calls the search tool. The API returns matches as tool_reference blocks (five by default) and expands them into full definitions itself; you never do this expansion. Claude then calls the discovered tool as a normal tool_use, and you return a tool_result as usual. The search call is a server_tool_use with a srvtoolu_... ID, and you never return a tool_result for it.

Two details remove the usual objections to dynamic tool sets. Deferred tools are kept out of the system-prompt prefix, and discovered tools are appended inline in the conversation, so prompt caching is preserved. Expanded references also persist across the conversation history, so Claude can reuse a tool in later turns without searching again.

Sources1

3.Choosing between progressive discovery and a fixed toolset

Progressive discovery isn't free. The manage-tool-context guide describes the trade plainly: one extra turn to look up a tool, in exchange for a large cut in baseline context use. So the real question is whether your toolset is large enough, and used unevenly enough, that the cut is worth the extra turn.

The guide's comparison answers this. Tool search fits large toolsets of 20+ tools where most tools aren't needed on every turn. Prompt caching is the better fit when the toolset is large but fixed. Caching doesn't reduce the number of tokens in context, but it reduces what you pay for them on later requests. A monolithic toolset that stays stable and is cached is therefore a legitimate design. What it doesn't fix is the selection-accuracy problem past 30–50 tools, because every definition is still in front of Claude.

The two strategies also combine. The recommended starting point for a high-volume agent is to enable prompt caching on tool definitions from day one, then add tool search once the toolset grows past roughly 20 tools or baseline context use becomes noticeable.

Sources3

Exam traps

Each one states something that sounds right. Open it to see what is actually true.

1. 1.Setting defer_loading: true means you can leave that tool's definition out of later requests.Why is that wrong?

   defer_loading only controls what enters the context window. Every full definition must still be sent on every request so the API can run the search and expand tool_reference blocks.

   Covered in How tool search works: defer_loading and tool_reference

2. 2.For maximum savings, defer every tool, including the search tool and the ones you use most.Why is that wrong?

   The search tool must never be deferred, and the guidance is to keep your 3–5 most frequently used tools loaded so Claude doesn't spend a search turn on them.

   Covered in How tool search works: defer_loading and tool_reference

3. 3.Prompt caching solves the same problem as tool search, so a cached monolithic toolset is just as lean in context.Why is that wrong?

   Caching lowers the price of repeated definitions but leaves the token count in context unchanged. Only tool search removes definitions from context.

   Covered in Choosing between progressive discovery and a fixed toolset