AP12 · Tool overload
Family: Tools and agent-computer interface
Strong evidence
Original names: tool overload, context confusion, tool-space interference
Every tool definition is loaded on every turn, overlapping ones included.
Definition
The model is shown every available tool definition, from the first turn and on every call, with no selection and no namespaces. Some overlap or share the same name.
Observable symptoms
- More than 20 tools exposed on the first turn, and tens of thousands of tokens of definitions before the first message.
- The model calls the wrong tool, or tools unrelated to the request.
- Two MCP servers offer a tool with the same name (`search`, for instance).
Why it hurts
Descriptions overlap and the model mixes the tools up; the context is used up before the task even starts. If an engineer cannot say for sure which tool to use, an agent cannot be expected to do better.
A defensible choice when…
- Fifteen or so distinct, well-described tools: overlap hurts as much as sheer numbers.
Figures
- Showing only the relevant tools, retrieved for the request, lifts selection accuracy from 13.6% to 43.1% and cuts the prompt by more than half (preprint).
- Five MCP servers and 58 tools weigh about 55,000 tokens of definitions; with a tool-search tool, correct selection rises from 49% to 74% for Opus 4 (the vendor’s own measurements).
- Across 1,470 MCP servers, 775 tools share a name with a tool from another server; `search` appears in 32 servers.
Remedies from the catalogue
- D4 · Skills (progressive disclosure) — A domain’s tools load on demand, when the task needs them, instead of all being there from the start.
- B2 · Routing — A router sends the request to a subset of tools, or to an agent specialised by domain.
- A2 · Tools and agent-computer interface (ACI) — Few tools, merged when they overlap, named with a domain prefix (`github_search`, `jira_search`) and described without ambiguity.
Measures outside the catalogue
- A tool-search tool, which loads only the definitions relevant to the request.
Misused patterns
Related anti-patterns
Sources
- RAG-MCP — Gan et Sun, arXiv, 2025-05-06
- Introducing advanced tool use on the Claude Developer Platform — Anthropic (B. Wu et al.), 2025-11-24
- Tool-space interference in the MCP era — Microsoft Research (A. Fourney et al.), 2025-09-11
- Effective context engineering for AI agents — Anthropic, 2025-09-29
- A practical guide to building agents — OpenAI, 2025
- Function calling — OpenAI (documentation)
Content reviewed on 2026-10-05