More agent tools, less context with defer_loading
Loading every tool definition upfront wrecks tool recall once an agent has more than a handful of tools. Anthropic's defer_loading keeps tools discoverable without bloating context, here's when it's worth using.
Give an agent 50 tools and something predictable happens: tool recall gets worse. Not because the model got dumber, but because every one of those tool definitions, name, description, full parameter schema, sits in context on every single turn, whether the agent needs it or not. Past a certain count, the agent starts picking the wrong tool, missing the right one, or just burning tokens re-reading definitions it won’t use this turn.
There’s a second, less obvious cost: if the set of tools loaded into context changes between requests, say, you swap out a subset depending on some runtime condition, you can break prompt caching patterns that depend on a stable prefix. A cache that was supposed to save you money and latency starts missing instead.
What Anthropic’s Tool Search + defer_loading actually does
Anthropic’s advanced tool use
research addresses
this with two pieces that work together. Tool Search lets the model query
for relevant tools by description instead of having every tool’s full
definition sitting in context upfront, it can discover what’s available
without paying the token cost of loading all of it. defer_loading is
the flag that keeps a tool’s full definition out of the initial context
entirely; it stays discoverable through Tool Search but doesn’t cost anything
until the model actually decides it needs it.
The practical pattern: keep the 3-5 tools your agent uses on nearly every turn loaded normally, and mark everything else, the long tail of occasionally-needed, rarely-needed, or situationally-needed tools, as deferred. The agent still has access to all of it. It just isn’t paying rent on tools it’s not using this turn.
The numbers, and who they’re from
Anthropic’s own reported internal evaluation numbers: an 85% reduction in token usage in their example scenario, Claude Opus 4’s tool-selection accuracy moving from 49% to 74%, and Opus 4.5 moving from 79.5% to 88.1%. These are Anthropic’s internal evaluation results on their own benchmark scenario, not an independent or universal benchmark, worth keeping in mind before assuming your own setup will see identical gains. The direction of the effect (fewer tokens, better selection) is the generalizable part; the exact percentages are specific to their test conditions.
When it’s actually worth doing
This isn’t a default you should flip for every agent. It’s worth reaching for when:
- You have 10 or more tools defined for a single agent. Below that, the context cost of loading everything upfront is usually small enough that the complexity of managing deferred vs. loaded tools isn’t worth it.
- Your tool definitions are collectively eating more than roughly 10K tokens of context on every turn. That’s real money and real latency on every single request, whether or not those tools get used.
- You have a long tail of rarely-used tools sitting alongside a small core set that gets used constantly. Deferred loading is exactly the mechanism for that shape of tool library, it doesn’t help if every tool gets used roughly as often as every other one.
The trade-off
Tool Search isn’t free. Looking up a deferred tool adds a round-trip the model has to make before it can call that tool, which is latency you don’t pay when everything’s loaded upfront. For a tool the agent uses on nearly every turn, that latency cost isn’t worth paying, which is exactly why the 3-5 “always loaded” core tools matter: they’re the ones where upfront loading is still the right call. Deferred loading is for the tools where the context savings outweigh an occasional extra lookup, not a blanket replacement for loading tools normally.