This article is part of The MCP Guide, our plain-English reference on the Model Context Protocol.
Tool search and code mode are two answers to the same problem: AI agents with access to many MCP tools waste context and pick tools badly. Tool search hides tool definitions until the model searches for them. Code mode goes further and lets the model write a short program that calls tools, so large intermediate data never passes through the model.
Tool search is a setting or API feature you can turn on today. Code mode is an architecture choice that needs a sandbox. This guide explains both, with the details Anthropic and Cloudflare have published, checked on 2 November 2026.
Key Takeaways
- Tool search marks tools as deferred, so only a search tool and a few common tools load at the start.
- Anthropic's API offers two tool search variants, regex and BM25, and returns up to 5 matching tools per search by default.
- Claude Code turns tool search on by default and supports a threshold mode with
ENABLE_TOOL_SEARCH=auto. - Code mode turns MCP tools into a code API and has the model write code that calls it, a pattern Cloudflare named in September 2025.
- Anthropic reported one code execution example that cut token use from 150,000 to 2,000.
- Code mode needs a secure sandbox; tool search does not.
The problem both solve
Each MCP tool comes with a name, description and input schema that most clients show to the model. Our explainer on MCP and the context window covers the cost. In short, Anthropic's tool search tool docs say a five-server setup "can consume ~55k tokens in definitions before Claude does any work," and that tool selection "degrades once you exceed 30–50 available tools."
How tool search works
Tool search changes when tool definitions enter the context window.
According to Anthropic's docs, you send every tool definition with the request but set defer_loading: true on the tools that should not load up front. The model starts with only the tool search tool and any non-deferred tools. When it needs something, it searches. The API returns matching tools as tool_reference blocks and expands them into full definitions.
Key details from the docs:
| Item | What the docs say |
|---|---|
| Variants | tool_search_tool_regex_20251119 (Python regex) and tool_search_tool_bm25_20251119 (natural language) |
| Fields searched | Tool names, descriptions, argument names and argument descriptions |
| Results per search | Up to 5 by default; the model can set a limit |
| Deferred tools per request | Up to 10,000 |
| Prompt caching | Deferred tools are kept out of the cached prefix, so caching is preserved |
| Status | Marked stable on the Claude API |
The docs suggest keeping your "3–5 most frequently used tools non-deferred." They also recommend tool search when you have 10 or more tools, definitions over 10,000 tokens, or "multiple MCP servers (200+ tools)."
For MCP specifically, the docs say you set defer_loading once on the mcp_toolset entry's default_config when tools come through Anthropic's MCP connector, rather than on each tool.
Measured results
In its advanced tool use post, Anthropic reported that context use fell from about 77,000 tokens to about 8,700, "an 85% reduction." It also reported higher accuracy with tool search enabled: "Opus 4 improved from 49% to 74%, and Opus 4.5 improved from 79.5% to 88.1%." These are Anthropic's internal results, not independent tests.
Tool search in Claude Code
The Claude Code MCP docs say "Tool search is enabled by default: MCP tools are deferred and discovered on demand." Only tool names and server instructions load at session start. The docs add that Claude Code "doesn't impose a fixed per-server tool cap; the practical limit is your context window budget."
You control it with the ENABLE_TOOL_SEARCH environment variable:
| Value | Behavior, per the docs |
|---|---|
unset or true | MCP tools deferred and loaded on demand |
auto | Tools load up front until they total 10% of the context window, then search turns on |
auto:N | Same, with a custom percentage, for example auto:5 |
false | All MCP tools loaded up front |
There are exceptions. The docs say tool search is not supported on Microsoft Foundry deployments hosted on Azure, and it is off in sessions with Anthropic's HIPAA configuration. Server authors can ask for a tool to load up front by setting "anthropic/alwaysLoad": true in that tool's _meta.
How code mode works
Code mode changes how the model calls tools, not just when it sees them.
Cloudflare described it on 26 September 2025 in a post titled Code Mode: the better way to use MCP. The approach: "Convert the MCP tools into a TypeScript API, and then ask an LLM to write code that calls that API." The model gets one tool that runs code. That code calls the MCP tools and prints only what the model needs.
Cloudflare's reasoning is that models have seen far more real code than tool-call examples. Its post says "LLMs have seen a lot of code. They have not seen a lot of 'tool calls'." Chaining calls in code also avoids copying each result back through the model.
Anthropic made a similar case in Code execution with MCP (4 November 2025). It describes presenting tools as files the agent reads only when needed, or adding a search_tools tool. Its worked example "reduces the token usage from 150,000 tokens to 2,000 tokens." It also notes a privacy benefit: intermediate results "stay in the execution environment by default."
Programmatic tool calling on the Claude API
Anthropic also ships a related API feature. The advanced tool use post describes Programmatic Tool Calling, where Claude writes code in the code execution tool to call your tools. Anthropic reported "Average usage dropped from 43,588 to 27,297 tokens, a 37% reduction on complex research tasks."
The catch: you need a sandbox
Code mode runs code the model wrote. Anthropic's post says "Running agent-generated code requires a secure execution environment" with sandboxing, resource limits and monitoring. Cloudflare's version runs each snippet in a fresh V8 isolate with no general internet access; its only route out is the bindings to connected MCP servers, and API keys stay with the supervisor. See our guide to sandboxing local MCP servers for the general risks.
Tool search vs code mode
| Tool search | Code mode | |
|---|---|---|
| What it saves | Tool definition tokens | Definition and intermediate result tokens |
| Setup | API flag or client setting | Sandbox plus code-generation harness |
| Best for | Many tools, simple calls | Multi-step workflows over large data |
| Main risk | A tool is not found if descriptions are vague | Running model-written code |
| Who it suits | Anyone using Claude Code or the Claude API | Engineering teams building agents |
They combine well. Tool search keeps the catalog small. Code mode keeps big data out of the conversation.
What server authors should change
Both approaches reward well-described tools. With tool search, the model only finds your tool if its name and description contain the words a user would search for. Claude Code's docs say to "put the words Claude would search for near the start." Use consistent prefixes, such as crm_ or billing_, so one search finds a whole group. Our lesson on designing tools an AI uses well covers the basics.
For code mode, an outputSchema helps. The MCP tools specification says output schemas provide "type information for better integration with programming languages," which is exactly what a generated code API needs.
Next step
If you use Claude Code, check /context to see whether your MCP tools show as deferred. If you are building an agent with many tools, our MCP development team can help you decide between tool search, code execution and fewer, better tools. For the cost side, read how to reduce MCP token costs.
More in the MCP Guide
Latest research: State of MCP: October 2026
Frequently asked questions
Is tool search part of the MCP specification?
No. Tool search is a client and API feature. The MCP spec defines how servers list and describe tools; clients like Claude Code and APIs like Anthropic's decide when to show those definitions to the model.
Does tool search cost extra on the Claude API?
Anthropic's docs say tool search "isn't metered as a separate server tool." The definitions it loads into context count as normal input tokens.
Is code mode the same as Claude Skills?
No. Code mode is about calling tools from code. Skills are folders of instructions and scripts that teach a workflow. Anthropic's code execution post links the two, since agents can save working code as reusable skills. See MCP vs Claude Skills.
Can I build my own tool search?
Yes. Anthropic's docs say you can return tool_reference blocks from your own search tool, for example one that uses embeddings, and the API expands them the same way.
