Adding more than approximately 30 tools to an AI agent degrades performance because excessive tool definitions consume critical context window tokens and increase decision-making errors. This "cliff" effect causes models to invent plausible-sounding tool names that do not exist, known as tool hallucination. Solutions include enabling server-side search layers or using code execution modes to bypass direct tool calling limits. These methods significantly reduce token overhead while preserving or improving selection accuracy.
The hard part of building AI agents used to be connections. Since the Model Context Protocol launched in November 2024 and became the industry default, that work is mostly done. Anthropic now says developers routinely build agents with access to hundreds or thousands of tools across dozens of MCP servers. The open problem is what happens after the connections exist.
Over the past year, vendors and researchers have begun publishing measurements of agents facing large tool catalogs. The numbers converge on one finding: past a modest threshold, adding tools makes agents worse at everything, and the fixes that work are already shipped.

The arithmetic of an overstuffed toolbox
MCP clients typically load every tool definition (name, description, full JSON schema) into the context window before the first user message arrives. Those definitions then stay resident for the whole session, billed again and again.
Anthropic's engineering team published a concrete five-server setup: GitHub with 35 tools at about 26,000 tokens, Slack with 11 tools at about 21,000, plus Sentry, Grafana and Splunk, totaling 58 tools and roughly 55,000 tokens before the conversation starts. Add Jira, which consumes about 17,000 tokens on its own, and the overhead approaches 100,000. Anthropic says its own internal tool definitions once reached 134,000 tokens before optimization.
Lunar.dev estimates a single tool definition costs 200 to 500 tokens and puts a common five-server, thirty-tools-each configuration at 30,000 to 60,000 tokens of pure metadata, a quarter to a third of a 200,000-token window spent describing things the model may never call.
The accuracy cliff
Token cost is the visible half. The other half is decision quality, and the evidence says it fails as a cliff, not a slope.
Speakeasy ran controlled experiments with a small model (qwen3-1.7b) on a pet-store API that fetched dog breed images against varying tool counts:
- With 10 tools: correct tool selection, no errors.
- With 20 tools: 19 of 20 calls right, one hallucinated tool.
- With 107 tools: both small and large models struggled, inventing plausible-sounding tool names that did not exist.
The same 20 tools split across two focused servers of 10 produced zero errors. What mattered was not the token total but the size of the menu at each selection step. Speakeasy's tool design guide draws the line at 30 to 40 tools, beyond which models display tool hallucination and irrelevant selections. Anthropic's documentation says Claude's selection accuracy degrades past 30 to 50 available tools. OpenAI's function calling guide advises fewer than 20 functions available at the start of a turn, while calling it a soft suggestion. Three vendors, three numbers, same shape.
Anthropic names the most common failure mode precisely: wrong tool selection between similarly named tools, its example being notification-send-user versus notification-send-channel.
Academic work points the same way. MCP-Bench, a benchmark posted to arXiv in August 2025, attaches 10 distractor servers to each task, injecting more than 100 additional superficially plausible tools per instance. Even top models (gpt-5, o3, gemini-2.5-pro) hold tool appropriateness and parameter accuracy only around 0.70, while weaker models plateau between 0.30 and 0.50.
The second tax: results in transit
Definition bloat is only half the cost model. With direct tool calling, every intermediate result must pass through the model to reach the next call. In Anthropic's worked example, attaching a two-hour meeting transcript from Google Drive to a Salesforce lead, the full transcript flows through the context window twice, an extra 50,000 tokens just to move bytes. Larger documents break the workflow entirely when they exceed context limits.
Fix one: put a search layer in front of the call
Anthropic shipped a server-side Tool Search Tool in November 2025. Clients declare the whole catalog with defer_loading on everything that is not hot; the model searches a keyword index (regex or BM25 variants) and the API injects only the three to five definitions a request needs. In Anthropic's published example, context consumption for a library of 50-plus MCP tools fell from about 77,000 tokens to about 8,700, an 85 percent reduction, preserving 191,300 tokens of context versus 122,800 under the load-everything approach.
The accuracy numbers moved too: internal MCP evaluations improved from 49 percent to 74 percent on Opus 4 and from 79.5 percent to 88.1 percent on Opus 4.5 with tool search enabled. Those are vendor numbers on a vendor benchmark, not reproducible by outsiders, but the direction matches Speakeasy: shrink the menu, raise the hit rate.

The published limits matter for planning. Up to 10,000 tools can be deferred per request; searches return five matches by default; Anthropic recommends keeping the three to five most-used tools non-deferred so common calls skip the search step. The catch is that retrieval quality is entirely hostage to tool names and descriptions, which is why the docs push consistent service prefixes (github, slack) and keyword-rich descriptions. A sloppy catalog means BM25 hands the agent the wrong tool with full confidence.
Fix two: make the agent write code instead of calling tools
Cloudflare's Code Mode, published the same month, goes further. Its premise is that LLMs have read millions of real repositories but almost no natural tool-call traces, so they write TypeScript against a typed API better than they manage structured function calls. Convert each MCP server into a typed interface in a sandbox and let the agent write the orchestration: loops, conditionals and error handling run without model round trips, and intermediate results never enter the context.
Anthropic's version of the example numbers are extreme: the Google Drive to Salesforce transcript task went from 150,000 tokens with direct tool calls to about 2,000 when the agent read two tool files from a generated file tree and wrote the glue code, a claimed 98.7 percent reduction. The same post describes filtering a 10,000-row spreadsheet down to the five relevant rows inside the execution environment, keeping sensitive intermediates out of the model entirely, and persisting working code as reusable scripts, which is close to how the Skills format now packages agent capabilities.
Both companies state the caveat plainly: this requires a sandboxed execution environment with resource limits and monitoring. Code execution adds an operational surface that direct tool calls do not. Cloudflare argues bindings are actually safer, because the generated code never sees API keys it could leak. Whether the trade is worth it depends on your tool count and data sizes, which is exactly what the numbers above let you estimate.
Fix three: design fewer tools
The least glamorous result is Speakeasy's server-split experiment: zero errors with the same tools carved into two focused servers. Tool design guidance from Speakeasy, Anthropic and practitioners converges on outcome-shaped tools rather than endpoint-shaped ones, one tool per user goal instead of one per REST route, and roughly 5 to 15 tools per server. Speakeasy adds a finding that cuts against instinct: optimizing names and descriptions moved quality more than switching to a larger model.
What it adds up to
The constraint on late-2026 agent systems is rarely model capability. It is attention budget and menu design. A defensible playbook, in order of cost: count tools before buying servers, since tools, not servers, are the unit that degrades; write descriptions as if a search index will read them, because one now does; enable tool search once the catalog exceeds a dozen tools; consider code execution when workflows shuttle large documents between systems; and treat the tool count as a product decision, not an integration checkbox.
Sources
- Anthropic, "Introducing advanced tool use on the Claude Developer Platform" - https://www.anthropic.com/engineering/advanced-tool-use
- Anthropic, "Code execution with MCP: Building more efficient agents" - https://www.anthropic.com/engineering/code-execution-with-mcp
- Anthropic docs, "Tool search tool" - https://docs.anthropic.com/en/docs/agents-and-tools/tool-use/tool-search-tool
- Cloudflare, "Code Mode: the better way to use MCP" - https://blog.cloudflare.com/code-mode/
- Speakeasy, "Why less is more for MCP" - https://www.speakeasy.com/mcp/tool-design/less-is-more
- Speakeasy, "Design MCP tools" - https://www.speakeasy.com/mcp/tool-design
- Lunar.dev, "How to Prevent MCP Tool Overload and Build Faster, Safer AI Agents" - https://www.lunar.dev/post/why-is-there-mcp-tool-overload-and-how-to-solve-it-for-your-ai-agents
- OpenAI, "Function calling" guide - https://platform.openai.com/docs/guides/function-calling
- MCP-Bench: Benchmarking Tool-Using LLM Agents with Complex Real-World Tasks via MCP Servers - https://arxiv.org/abs/2508.20453
Frequently asked questions
What is the optimal number of tools per server to avoid hallucinations?
Industry guidance suggests keeping between 5 and 15 tools per server. Speakeasy, Anthropic, and practitioners converge on this range, noting that accuracy degrades past 30 to 40 available tools.
How much does Tool Search reduce context consumption?
Anthropic's Tool Search reduced context consumption for 50+ MCP tools from about 77,000 tokens to approximately 8,700 tokens, an 85% reduction.
Does code execution improve agent efficiency compared to direct tool calls?
Yes. In a Google Drive to Salesforce example, Cloudflare's Code Mode reduced token usage from 150,000 to about 2,000 tokens, a 98.7% reduction, by keeping intermediate results out of the model's context.
What are the common failure modes when tool counts exceed thresholds?
The most common failure is wrong tool selection between similarly named tools, such as confusing 'notification-send-user' with 'notification-send-channel'. Models may also invent plausible-sounding tool names that do not exist.
