Building a tool-search workflow

The problem this exists to solve

A request with a large tool surface — dozens of internal functions, several MCP-connected systems — pays a real cost for declaring every single one up front on every request, whether or not the current task needs more than a handful of them. Tool search flips that: instead of sending every schema every time, it lets Claude search for and load the specific tool definitions a given task actually needs, on demand, and leaves the rest undeclared until they're relevant.

Deciding what belongs directly declared versus deferred

The decision that actually matters here isn't whether to use tool search at all — it's which tools go in which bucket. Tools used on nearly every request, or that are cheap and simple enough that the overhead of declaring them directly is negligible, belong declared directly: paying a discovery round trip for something you're about to call anyway on almost every turn defeats the purpose. Tools that are genuinely used occasionally — a long tail of specialised functions, most of which any given task will never touch — are exactly what deferring to search was built for. Deferring everything, including your most-used tools, produces a workflow that's slower on the common case for no real benefit; see every tool was deferred to tool search, with none directly callable for what that looks like when it goes wrong.

How Claude actually finds a deferred tool

When a task needs a capability that isn't among the directly-declared tools, Claude uses the search mechanism to look for a matching tool among the deferred set, based on the tool's own name and description — which means, once again, tool descriptions are doing real work here, not just documentation. A deferred tool with an ambiguous or generic description is harder for the search step to correctly match against a task that needs it, in exactly the same way a poorly described directly-declared tool gets called incorrectly. Write descriptions for deferred tools with search discoverability specifically in mind, not just clarity for a human reading them later.

Measuring whether the split is actually working

A tool-search setup that's badly split doesn't necessarily fail outright — it can just be slower or less reliable than it should be, without an obvious error pointing at the cause. Track how often a task ends up needing a search round trip for a tool that, in hindsight, gets used often enough that it should have been declared directly — that pattern, seen repeatedly, is the signal to move a tool from the deferred set into the directly-declared one. Treat the split as something to revisit as usage patterns become clear, not a one-time decision made before you had real data on which tools actually get reached for.

Latency budget matters as much as the split itself

A search-then-call round trip adds real latency compared to a directly declared tool that's ready to call immediately, and that added latency is invisible until a task hits a deferred tool on the critical path of something latency-sensitive. If part of your workflow has a hard response-time requirement, audit which deferred tools that specific path can reach for, and consider promoting anything on that path to directly declared even if it's used less often overall than your other directly-declared tools — the latency cost of a wrong choice there is disproportionate to how often it's actually triggered.

When your tool surface doesn't need this at all

If your entire tool list is small enough that declaring everything directly carries negligible overhead, tool search adds a layer of indirection without a real problem to solve. This is a scaling mechanism for a genuinely large and sparse tool surface, not a default worth reaching for on every tool-use integration regardless of size.