Scaling the tool surface

What to do when there are too many tools to put in context.

4 min read · Lesson 6 of 10 in this domain

There is a real ceiling on how many tools an agent can choose between accurately, and past it selection degrades no matter how good the descriptions are. When a library genuinely needs to be large, the answer is not to write better prose for fifty tools or to merge them into one monolith — it is to stop putting all fifty in context at once. Tool search loads only the handful relevant to the current turn. It has the pleasant side effect of preserving the prompt cache, because discovered schemas are appended rather than swapping out the tool list that sits at the very front of the prefix.

• A large tool surface degrades selection accuracy. Keeping the set focused is standard guidance.
• When a large library is genuinely needed, use dynamic discovery (the tool-search pattern) so only the handful of relevant schemas enter context per turn.
• Constraint: the search tool itself must not be deferred, and at least one tool must remain non-deferred. Deferring everything is rejected — the model would have no entry point.
• Tool search appends schemas rather than swapping them, which preserves the prompt cache. Changing the top-level tool list does not.
• Rewriting 50 descriptions helps at the margin but does not fix the systemic overload. Merging 50 connectors into one monolith destroys composability and moves the ambiguity into parameters.

Source: Claude Docs — Tool search tool · Independent study aid, not affiliated with or endorsed by Anthropic.