Too Many MCP Tools? Tool Search and Code Execution
On this page
Learning Objective
Understand why agents degrade as the number of tools grows, and apply the techniques that fix it: filtering tools per task, deferred loading with tool search, and letting the agent call tools from code so intermediate data never enters the context.
Concept Explanation
Connecting more MCP servers seems like pure gain, but it has two costs. The first is tokens. Every tool definition is sent with every request, and enterprise servers can have dozens of tools with long descriptions and schemas. Five servers can easily add tens of thousands of tokens before the user has typed a word. The second is accuracy. With many similar tools, models pick the wrong one more often, especially when names and descriptions overlap across servers. Both problems grow with every server you add.
The simplest fix is filtering. Hosts can enable only the servers a task needs, and many servers let you enable subsets of their tools, such as GitHub's toolsets for issues, pull requests or actions. Routing (Day 6) generalizes this: a classifier picks the relevant servers for each request before the agent runs.
When the set of potentially relevant tools is genuinely large, deferred loading helps. Instead of sending every definition, the host sends a small tool search tool plus a lightweight index. The model searches for what it needs, for example "create a calendar event", and only the matching tool definitions are loaded into the context. The Claude API supports this directly: you include a tool search tool, regex or BM25 based, and mark other tools with defer_loading so they are discoverable but not sent in full. Anthropic reported that this cut tool-definition tokens dramatically for large tool libraries and improved tool selection accuracy on its internal evaluations.
The second large cost is intermediate results. In a normal loop every tool result passes through the context: to copy a two-hour meeting transcript from a document into a CRM record, the model reads the whole transcript as a tool result and then writes it again as an argument. Code execution changes that. Tools are presented to the agent as functions in a code environment, and the agent writes a short program that calls them, filters and transforms the data, and returns only the final answer. Anthropic's November 2025 post on code execution with MCP described an example in which this reduced token usage from about 150,000 to about 2,000 tokens, a 98.7 percent reduction, and noted that data can also stay out of the model's context entirely, which helps privacy.
Code execution needs a secure sandbox with resource limits, because the agent is running code it wrote. It is worth it for data-heavy workflows: large lists, joins across systems, loops over many items. For simple single calls, direct tool use remains simpler and faster.
| Technique | Fixes | Cost |
|---|---|---|
| Enable only needed servers or toolsets | Tokens and confusion | Needs per-task configuration |
| Routing to server subsets | Tokens and confusion | An extra classification step |
| Tool search with deferred loading | Tokens for large tool libraries | One search call before use |
| Code execution with tools as functions | Intermediate data in context | Needs a secure sandbox |
| Distinct names and descriptions | Wrong tool selection | Design effort (Day 4) |
Worked Example: Deferred Loading with Claude's Tool Search
Only the search tool and two core tools are sent in full. The other tools, here converted from several MCP servers, are marked defer_loading and are loaded only when the model's search matches them.
import anthropic
client = anthropic.Anthropic()
def defer(tool: dict) -> dict:
return {**tool, "defer_loading": True}
core_tools = [SHOP_RUN_QUERY, NOTES_SEARCH] # always loaded, used constantly
long_tail = CRM_TOOLS + CALENDAR_TOOLS + JIRA_TOOLS + GITHUB_TOOLS # e.g. 120 MCP tools
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=16000,
tools=[
{"type": "tool_search_tool_bm25_20251119", "name": "tool_search_tool_bm25"},
*core_tools,
*[defer(t) for t in long_tail],
],
messages=[{"role": "user", "content": "Book a 30 minute review with Priya for the PLAT-12 ticket."}],
)
# The model first calls tool_search_tool_bm25 with a query such as "calendar create event";
# the API returns references to matching deferred tools, which are then loaded and callable.
for block in response.content:
print(block.type, getattr(block, "name", ""))At least one tool must stay non-deferred, and the search tool itself must never be deferred. The prompt cache also benefits: the stable core of the tool list stays identical between requests.
Real-World Examples
- Anthropic's November 2025 engineering post "Code execution with MCP" described presenting MCP servers as code APIs so agents load only the tool definitions they need and process data in the execution environment, reporting a drop from about 150,000 to about 2,000 tokens in one workflow.
- GitHub's MCP server lets users enable specific toolsets, such as issues, pull requests or code security, rather than the full list, explicitly to reduce context usage and tool confusion.
Review Questions & Answers
Token cost, because every tool definition is sent with every request, and lower accuracy, because the model must choose among more, often overlapping, tools.
Most tools are marked defer_loading so they are not sent in full. The model calls the search tool with a description of what it needs, and only the matching tool definitions are loaded and become callable.
The agent writes code that calls tools and processes their results inside the execution environment, returning only the final answer. Large intermediate results such as documents or long lists never pass through the model's context.
For simple tasks with one or a few small tool calls, where writing and running code adds latency and complexity, and where a secure sandbox is not otherwise needed.