Catalog My learning Blog
Build AI Agents with MCP: 30-Day Course · Phase 5 · Lesson 25 · 5 min read

Too Many MCP Tools? Tool Search and Code Execution

On this page
  1. Learning Objective
  2. Concept Explanation
  3. Worked Example: Deferred Loading with Claude's Tool Search
  4. Real-World Examples
  5. Review Questions & Answers

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.

TechniqueFixesCost
Enable only needed servers or toolsetsTokens and confusionNeeds per-task configuration
Routing to server subsetsTokens and confusionAn extra classification step
Tool search with deferred loadingTokens for large tool librariesOne search call before use
Code execution with tools as functionsIntermediate data in contextNeeds a secure sandbox
Distinct names and descriptionsWrong tool selectionDesign 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.

Code
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.

Illustrative tokens per request for a large tool library. Sending every definition costs the most; filtering servers helps; deferring most tools behind a tool search keeps only a small core loaded until the model searches.
Illustrative tokens per request for a large tool library. Sending every definition costs the most; filtering servers helps; deferring most tools behind a tool search keeps only a small core loaded until the model searches.

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.
Key TakeawaysEvery connected MCP tool costs tokens on every request, because its description travels in the context, and more tools make choosing harder. Enable only what a task needs, route requests to server subsets, defer rarely used tools behind a tool search, and let data-heavy workflows run as code that calls tools in a sandbox so intermediate results never enter the context. Distinct names and descriptions remain the cheapest fix for wrong tool choices.

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.