Support Tool Search and Programmatic Tool Use betas for reduced token consumption

For the love of God, PLEASE!

pls anthropic

tool search with RAG sounds promising, but tf-idf still works. just implemented a search-inspect-query pattern to deal with 100+ tools/query endpoints.. tf-idf is lightweight!

https://github.com/gyorilab/indra_cogex/pull/249

My most frequently-used MCP server has ~20-30 tools that consume 73.9k tokens of context. 53k of that is consumed by 3 tools that I never use. The authors are working on a fix, but the ability to configure defer_loading or even completely disable them (right now, disabling tools doesn't prevent them from being loaded into context) myself without waiting for the authors would be a lifesaver!

If you want to filter unused tools inside your mcp server, there's always something like https://github.com/TBXark/mcp-proxy that works pretty well

I am implementing this feature using MCP. https://github.com/pleaseai/mcp-gateway

Also, if someone is interested in saving tokens: https://docs.docker.com/ai/mcp-catalog-and-toolkit/toolkit/#how-the-mcp-toolkit-works

@mpiroc may I know tool search tool and programatic tool calling enabled in which Claude Code version? 2.0.36 work?

I'm really looking forward to it. I hope it will be supported in the Claude Code CLI as well.

Hi everyone! We are testing a more token efficient way for users to connect MCP servers to Claude Code:

Overview MCP-CLI is an experimental approach to MCP tool calling that dramatically reduces token consumption in Claude Code. This means you can work with more tools and larger contexts without hitting limits, improving productivity across your development teams. The Problem We're Solving Many power users rely heavily on MCP servers in their daily workflow. However, popular MCP servers often consume substantial tokens by loading complete tool definitions into the system prompt. This leads to: - Reduced effective context length - More frequent context compactions - Limitations on how many MCP servers you can run simultaneously How MCP-CLI Works Instead of loading full tool definitions into the system prompt, MCP-CLI provides Claude with minimal metadata about each server and its tools. When Claude needs detailed information about a specific tool, it can request it on-demand through a separate set of commands. It then executes tool calls using MCP-CLI commands in the Bash tool. Key advantages: - On-demand tool information: Only consume tokens for tools actually relevant to each session - Programmatic output processing: Claude can pipe large outputs (like JSON responses) directly to files or process them with tools like jq, keeping bulky data out of context - Scale to more tools – Load more MCP servers without sacrificing context space How to use: ENABLE_EXPERIMENTAL_MCP_CLI=true env var controls whether MCP-CLI is switched on for a current session. If you run into any limitations, you can always switch off the env var as desired.

Please test this out and share your feedback in this thread!

@catherinewu WOW! Zero context for 21 tools!?!?!?!? Where can I send the Christmas gift???

Works great on bash easily. For Windows users, it works great in WSL, or add $env:ENABLE_EXPERIMENTAL_MCP_CLI = "true" to your PowerShell profile!

@catherinewu may I know which Claude Code version enabled this setting? ENABLE_EXPERIMENTAL_MCP_CLI=true

@ysong2123 Claude Code version 2.0.56 and later have support for this env var. That said, we strongly recommend using the latest version 2.0.62 since that includes many bug fixes from the last few weeks.

Real-World Use Case: MCP-Heavy Workflow Automation

I'm building SalesBriefAI, a B2B SaaS platform that orchestrates complex workflows across multiple systems. My Claude Desktop setup includes:

• n8n-MCP server (~17 tools for workflow automation)
• Supabase-MCP server (~15 tools for database operations)
• Google Drive integration (2 tools for documentation)
• Standard tools (web search, computer use, memory)

Total: ~43 tools consuming an estimated 38-46K tokens before any conversation starts.

Why Tool Search Tool Would Be Transformative

In practice, most conversations use only 3-5 tools:

• Workflow maintenance → get_node, n8n_update_partial_workflow, n8n_get_workflow
• Database work → execute_sql, list_tables, apply_migration
• Documentation → google_drive_fetch, view

But I pay the full 40K+ token cost on every session, even when I'm just asking Claude to help me debug a single n8n expression.

Candidates for defer_loading: true in my setup:

• Template tools (search_templates, get_template, n8n_deploy_template) — used maybe 5% of sessions
• Branch management tools (create_branch, merge_branch, rebase_branch) — used rarely
• Bulk operations (n8n_delete_workflow, n8n_workflow_versions) — situational
• Diagnostics (get_logs, get_advisors) — on-demand only

An 85% token reduction would recover ~35K tokens for actual work—that's the difference between hitting context limits mid-task and completing complex multi-workflow operations.

Programmatic Tool Calling Use Case

I frequently need to audit patterns across 18+ n8n workflows:

• "Find all workflows missing error handling on HTTP Request nodes"
• "Check which workflows are using deprecated node versions"
• "Audit email template usage across the system"

Currently, these tasks either exhaust my context window or require delegation to external tools. PTC would let Claude orchestrate n8n_list_workflows → n8n_get_workflow (×18) → analysis without intermediate JSON bloating context.

What I Built as a Workaround

To handle large-context analysis tasks, I've built a custom [Agent] Workflow Auditor—an n8n workflow that uses Gemini 2.5 Flash as an AI agent with 8 specialized helper workflows as tools:

| Tool | Purpose |
|------|---------|
| Fetch Workflow | Get complete workflow JSON by ID |
| List Workflows | Enumerate all 79 n8n workflows |
| Execute SQL | Run read-only database queries |
| Get App Config | Retrieve JSONB configuration |
| Check RPC Function | Verify database functions exist |
| List Supabase Tables | Enumerate schema (27 tables) |
| List Email Templates | List all 9 email templates |
| Get Node Version | Check node type versions |

Claude calls this agent via webhook when context exhaustion is imminent. Gemini handles the bulk analysis with its larger context window, then returns a synthesized report.

This works, but it's a significant engineering investment to solve what these native features would handle automatically. Native Tool Search Tool and PTC support would eliminate the need for this custom infrastructure entirely.

Request: Claude Desktop Support

I notice this issue focuses on Claude Code, but Claude Desktop with MCP servers is where I experience this pain most acutely. The same features would be equally valuable there:

1. Tool Search Tool — Let MCP server configs specify defer_loading per tool
2. Programmatic Tool Calling — Enable code-based orchestration for batch MCP operations

The architectural pattern is identical; it's just a different client surface.

Would love to see these features land in both Claude Code and Claude Desktop. Happy to provide more detailed telemetry or test beta implementations if helpful.

---

Stack details for context:

• 27 n8n workflows (18 core + 1 agent + 8 helpers)
• Supabase PostgreSQL with RPC functions and JSONB configuration
• Token-optimized documentation system with 8 Agent Skills
• Custom Workflow Auditor using Gemini for large-context delegation (workaround for native feature gap)

@catherinewu It seems similar to the MCP+CLI method I implemented, but more convenient. Thank you.

> What mcp tools do i have available? 

⏺ Bash(mcp-cli tools)
  ⎿  Error: Exit code 127
     (eval):1: command not found: mcp-cli

I didn't see an install command or package anywhere - am i missing something?

Tip for Linux/Unix users: Check your actual shell!

If you've set ENABLE_EXPERIMENTAL_MCP_CLI=true but /context still shows high MCP token usage, you
might be configuring the wrong shell.

The problem: Your terminal emulator (Konsole, iTerm, etc.) might use a different shell than you
think. For example, I had configured ~/.zshrc but my Konsole profile was set to use fish - so the
variable was never exported to Claude.

Quick diagnosis:

# Find what shell is actually running Claude
ps -o ppid= -p $(pgrep -n claude) | xargs ps -o comm= -p

If it says fish but you configured zsh (or vice versa), that's your problem.

Setup per shell:

# Fish (~/.config/fish/config.fish)
set -gx ENABLE_EXPERIMENTAL_MCP_CLI true

# Bash (~/.bashrc) or Zsh (~/.zshrc)
export ENABLE_EXPERIMENTAL_MCP_CLI=true

Verify it's actually set before launching:

# In your terminal, before running claude:
echo $ENABLE_EXPERIMENTAL_MCP_CLI
# Should output: true

Or test without config changes:

ENABLE_EXPERIMENTAL_MCP_CLI=true claude

Hope this saves someone the debugging time!

@catherinewu I enabled this fantastic feature in my local. Thanks! One quick question -- ENABLE_EXPERIMENTAL_MCP_CLI was built on top of tool search tool & programmatic tool calling or a brand new feature? Any official instruction for it?

Does ENABLE_EXPERIMENTAL_MCP_CLI work with the agent sdk as well?

@ShawnSack I verified, in my local, and I can see:
"AssistantMessage(content=[ToolUseBlock(id='toolu_vrtx_01Ly3z5Q3WveqVCafc4uaJBT', name='Bash', input={'command': 'mcp-cli tools', 'description': 'List all available MCP tools'})], model='claude-haiku-4-5-20251001', parent_tool_use_id=None, error=None)
"

mcp-cli tools has been invoked for sure!
[I already set up ENABLE_EXPERIMENTAL_MCP_CLI in ~/.zshrc]

it seems the timeout option doesnt work on windows native version(with git for windows)
after i connected to codex-cli mcp (calling codex cli to assist claude code) and send long code snippets(so the reponse should take time for a while), it says 'the socket connection was disconnected unexpectedly..' ,
i checked if it's from the mcp server itself but found it's from mcp-cli iteslf.
so, i tried to use timeout flag but it's not working, the same error shows up again.

and on other terminal i don't use the ENABLE_EXPERIMENTAL_MCP_CLI flag and login to claude code then it shows all the mcp servers(including disabled ones globally) connected.

Previously, the Atlassian, GitHub and Sentry MCPs I use take up a whopping 64.6k tokens. I then added export ENABLE_EXPERIMENTAL_MCP_CLI=true to my .bashrc and restarted Claude Code. The /context command now shows no token usage for MCPs at all.

Discovery and usage of a couple MCP tools worked flawlessly. mcp-cli servers correctly listed my available servers. Claude was able to deduce the correct tools on its first try when all I did was give it a couple of URLs corresponding to each of the services and told it to fetch the details. mcp-cli info worked nicely to check the correct schema, then mcp-cli call used them correctly and delivered the result back to me. Consumed context after all this was 16.2k tokens in messages - a lot less then what the MCPs initially used!

@catherinewu found a bug with mcp-cli. Doesn't look to work when resuming existing sessions -

(new session)

> mcp-cli servers

⏺ Bash(mcp-cli servers)
  ⎿  (No content)

This creates .endpoint file with the current session ID - 644e1fb9-0791-48a0-bd24-4c73345a22a5.endpoint

When resuming with the same session ID above -

> mcp-cli servers

⏺ Bash(mcp-cli servers 2>&1)
  ⎿  Error: Exit code 1
     Error: Connection refused - is the MCP endpoint running?

This creates a new .endpoint file with a different ID - 37afe846-8e5e-46a6-b84c-f1e034fc7f58.endpoint. Assuming there is a bug where mcp-cli is not reusing the correct endpoint file.

Hi all - we added support for tool search behind an env var. To try it, please set ENABLE_TOOL_SEARCH=true and make sure that ENABLE_EXPERIMENTAL_MCP_CLI=false. Please let us know if you run into any issues!

Hi all - we added support for tool search behind an env var. To try it, please set ENABLE_TOOL_SEARCH=true and make sure that ENABLE_EXPERIMENTAL_MCP_CLI=false. Please let us know if you run into any issues!

Hi @catherinewu, thanks! Tried out as of v2.0.70. Couple of things so far:

1. It's using advanced-tool-use-2025-11-20 by default which is only Claude API / foundry compat: https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool
2. Using claude code with vertex, so tried forcibly switching the header to tool-search-tool-2025-10-19 underneath the hood, but that just results in the MCPSearch calls failing with 400 API errors like

API Error: 400 
    {"type":"error","error":{"type":"invalid_request_error","message":"Tool 
    reference 'mcp__slack__conversations_history' not found in available 
    tools"},"request_id":"req_vrtx_011CW9SWe7ZN1Rc9PMBEBzfT"}

The tool is definitely available

Is this not meant to be used with vertex / bedrock yet? Will stick to ENABLE_EXPERIMENTAL_MCP_CLI for now, ty

Hi all - we added support for tool search behind an env var. To try it, please set ENABLE_TOOL_SEARCH=true and make sure that ENABLE_EXPERIMENTAL_MCP_CLI=false. Please let us know if you run into any issues!

From my understanding, both mcp cli and tool search tool are similar with defer loading. the Only difference is ENABLE_EXPERIMENTAL_MCP_CLI will proactively discover related tools from mcp servers and ENABLE_TOOL_SEARCH only can set and paired with defer_loading=true? If not, what's the difference?

Thanks for reporting! We're looking into the Bedrock/Vertex issues 🙏

Thanks @catherinewu, MCP CLI is the feature I've been waiting for! I do have a bug report: I've been getting this error when trying to /compact since enabling the MCP CLI beta. I don't think it happens in every conversation, just some of them:

  Error: Error during compaction: Error: API Error: 400 {"type":"error","error":{"type":"invalid_request_error","message":"tools: Tool names must be unique."},"request_id":"req_011CWBJErmCaM1TfeL1sJ4b9"}

No compacting issues with latest version (2.0.71) and export ENABLE_EXPERIMENTAL_MCP_CLI=true.

Warning: Both ENABLE_TOOL_SEARCH and ENABLE_EXPERIMENTAL_MCP_CLI are set to true.
These are mutually exclusive. Using Tool Search mode.

can someone please explain which key does what and how we should use them, i´m a bit confused after all that postings here 🙈 thanks 😏

ENABLE_EXPERIMENTAL_MCP_CLI is working great. Huge reduction in context utilization on startup and significantly faster responses (due to smaller context utilization).

Warning: Both ENABLE_TOOL_SEARCH and ENABLE_EXPERIMENTAL_MCP_CLI are set to true. These are mutually exclusive. Using Tool Search mode. can someone please explain which key does what and how we should use them, i´m a bit confused after all that postings here 🙈 thanks 😏

Hey @michabbb - thanks for the opportunity to clarify 😬 basically, MCP-CLI (ENABLE_EXPERIMENTAL_MCP_CLI=true) and MCP with Tool Search (ENABLE_TOOL_SEARCH=true) are two different approaches we're auditioning for MCP context efficiency - feature-wise they're meant to do the same thing (i.e., support existing MCP use cases without needing the tools to be predeclared in context). The message just notes when you happen to have them both set to true, and that CC will use TS in that case.

TS is newer, so we're definitely interested in all/any feedback! But note per comments upthread, there are a couple outstanding issues:

• the /compact problem (should be fixed in v2.0.72)
• the Bedrock/Vertex issue (still troubleshooting, will update here)

Looks like ENABLE_EXPERIMENTAL_MCP_CLI is not honoring MCP_TOOL_TIMEOUT. Getting timeouts if the underlying MCP takes longer than 30 seconds.

Looks like ENABLE_EXPERIMENTAL_MCP_CLI is not honoring MCP_TOOL_TIMEOUT. Getting timeouts if the underlying MCP takes longer than 30 seconds.

@prpatel05 ah, we had an issue of this kind that's been fixed, but you may be running into a variation. Can you tell me what version you're running?

> Looks like ENABLE_EXPERIMENTAL_MCP_CLI is not honoring MCP_TOOL_TIMEOUT. Getting timeouts if the underlying MCP takes longer than 30 seconds. @prpatel05 ah, we had an issue of this kind that's been fixed, but you may be running into a variation. Can you tell me what version you're running?

2.0.69, let me know if it was fixed and I can try to repro on a later version.

> > Looks like ENABLE_EXPERIMENTAL_MCP_CLI is not honoring MCP_TOOL_TIMEOUT. Getting timeouts if the underlying MCP takes longer than 30 seconds. > > > @prpatel05 ah, we had an issue of this kind that's been fixed, but you may be running into a variation. Can you tell me what version you're running? 2.0.69, let me know if it was fixed and I can try to repro on a later version.

Yeah please try the latest (2.0.72) - if not fixed, any info you could give me to repro would be great.

Seeing this on Version: 2.0.73 with export ENABLE_TOOL_SEARCH=true

`⏺ Now let me consult the best practice MCP for relevant patterns.

⏺ MCPSearch(Search MCP tools: "select:mcp__best-practice-mcp__bestpractice_angular_layout_page_layout")
⎿  Found 1 tool

⏺ MCPSearch(Search MCP tools: "select:mcp__best-practice-mcp__bestpractice_angular_lists___collections_filter")
⎿  Found 1 tool

⏺ MCPSearch(Search MCP tools: "select:mcp__best-practice-mcp__bestpractice_angular_lists___collections_table")
⎿  Found 1 tool

⏺ MCPSearch(Search MCP tools: "select:mcp__best-practice-mcp__bestpractice_angular_layout_card")
⎿  Found 1 tool
⎿  API Error: 400 {"type":"error","error":{"type":"invalid_request_error","message":"messages.20.content.1.tool_result.content.0.tool_reference.tool_name: String should have at most 64 characters"},"request_id":"req_011CWFgNqFU7aMVFZpgTaPy5"}`

I assume its because the tool names end up being too long, but seems like a unnecessary limit to apply.

UPDATE: This is a our own MCP, so removing the long prefix on the tool names fixed the issue for now.

> > > Looks like ENABLE_EXPERIMENTAL_MCP_CLI is not honoring MCP_TOOL_TIMEOUT. Getting timeouts if the underlying MCP takes longer than 30 seconds. > > > > > > @prpatel05 ah, we had an issue of this kind that's been fixed, but you may be running into a variation. Can you tell me what version you're running? > > > 2.0.69, let me know if it was fixed and I can try to repro on a later version. Yeah please try the latest (2.0.72) - if not fixed, any info you could give me to repro would be great.

Not working as of 2.0.73.

Repro steps -

1. Create test MCP that sleeps for 60 seconds -

prpatel05@Mac testing % cat sleep-mcp/index.js
#!/usr/bin/env node
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = new McpServer({
  name: "sleep-mcp",
  version: "1.0.0",
});

server.tool("sleep_and_greet", "Sleeps for 60 seconds then says hi", {}, async () => {
  await new Promise((resolve) => setTimeout(resolve, 60000));
  return {
    content: [{ type: "text", text: "hi" }],
  };
});

const transport = new StdioServerTransport();
await server.connect(transport);

export ENABLE_EXPERIMENTAL_MCP_CLI=true
export MCP_TIMEOUT=600000
export MCP_TOOL_TIMEOUT=600000
export BASH_DEFAULT_TIMEOUT_MS=600000
export CLAUDE_CODE_STREAM_CLOSE_TIMEOUT=600000

1. Execute MCP -

> call sleep-mcp

⏺ I'll first check the schema for the sleep-mcp tool before calling it.

⏺ Bash(mcp-cli info sleep-mcp/sleep_and_greet)
  ⎿  Tool: sleep-mcp/sleep_and_greet
     Server: sleep-mcp
     Description: Sleeps for 60 seconds then says hi
     … +7 lines (ctrl+o to expand)

⏺ Now I'll call the tool. It sleeps for 60 seconds then returns a greeting.

⏺ Bash(mcp-cli call sleep-mcp/sleep_and_greet '{}')
  ⎿  Error: Exit code 1
     Error calling tool: Error: Network error: The socket connection was closed unexpectedly. For more information, pass `verbose: true` in the second argument to fetch()

⏺ The call failed with a network error. The socket connection was closed unexpectedly, likely because the tool's 60-second sleep caused a timeout or disconnection with the MCP server.

  Would you like me to try again, or is there something specific you're testing with this tool?

PLEASE CLAUDE I NEED THI

The search tool combined with backgrounded subagents being able to use mcps will be really cool (once it's fixed)

^ Looks like it was fixed in 2.0.74!

Hey @michabbb - thanks for the opportunity to clarify 😬 basically, MCP-CLI (ENABLE_EXPERIMENTAL_MCP_CLI=true) and MCP with Tool Search (ENABLE_TOOL_SEARCH=true) are two different approaches we're auditioning for MCP context efficiency - feature-wise they're meant to do the same thing (i.e., support existing MCP use cases without needing the tools to be predeclared in context). The message just notes when you happen to have them both set to true, and that CC will use TS in that case. TS is newer, so we're definitely interested in all/any feedback! But note per comments upthread, there are a couple outstanding issues:

MCP_CLI also allows programmatic tool use though, based on what @catherinewu said? Whereas Tool Search only defers loading of the MCPs.

ENABLE_EXPERIMENTAL_MCP_CLI=true seems to save 11-12k tokens. I added use-case descriptions for 4 MCPs worth 350 tokens to my root CLAUDE.MD for MAXential Thinking, Tavily Search, Multi-Fetch and Chrome DevTools. Getting a lot more mileage out of my sessions before running /handoff then /clear. Thanks for this!

> > > > Looks like ENABLE_EXPERIMENTAL_MCP_CLI is not honoring MCP_TOOL_TIMEOUT. Getting timeouts if the underlying MCP takes longer than 30 seconds. > > > > > > > > > @prpatel05 ah, we had an issue of this kind that's been fixed, but you may be running into a variation. Can you tell me what version you're running? > > > > > > 2.0.69, let me know if it was fixed and I can try to repro on a later version. > > > Yeah please try the latest (2.0.72) - if not fixed, any info you could give me to repro would be great. Not working as of 2.0.73. Repro steps - 1. Create test MCP that sleeps for 60 seconds - `` prpatel05@Mac testing % cat sleep-mcp/index.js #!/usr/bin/env node import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"; import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"; const server = new McpServer({ name: "sleep-mcp", version: "1.0.0", }); server.tool("sleep_and_greet", "Sleeps for 60 seconds then says hi", {}, async () => { await new Promise((resolve) => setTimeout(resolve, 60000)); return { content: [{ type: "text", text: "hi" }], }; }); const transport = new StdioServerTransport(); await server.connect(transport); ` ` export ENABLE_EXPERIMENTAL_MCP_CLI=true export MCP_TIMEOUT=600000 export MCP_TOOL_TIMEOUT=600000 export BASH_DEFAULT_TIMEOUT_MS=600000 export CLAUDE_CODE_STREAM_CLOSE_TIMEOUT=600000 ` 3. Execute MCP - ` > call sleep-mcp ⏺ I'll first check the schema for the sleep-mcp tool before calling it. ⏺ Bash(mcp-cli info sleep-mcp/sleep_and_greet) ⎿  Tool: sleep-mcp/sleep_and_greet Server: sleep-mcp Description: Sleeps for 60 seconds then says hi … +7 lines (ctrl+o to expand) ⏺ Now I'll call the tool. It sleeps for 60 seconds then returns a greeting. ⏺ Bash(mcp-cli call sleep-mcp/sleep_and_greet '{}') ⎿  Error: Exit code 1 Error calling tool: Error: Network error: The socket connection was closed unexpectedly. For more information, pass verbose: true in the second argument to fetch() ⏺ The call failed with a network error. The socket connection was closed unexpectedly, likely because the tool's 60-second sleep caused a timeout or disconnection with the MCP server. Would you like me to try again, or is there something specific you're testing with this tool? ``

@bhosmer-ant were you able to repro this?

No one has really explained what these two options do differently. If I understand right, the EXPERIMENTAL one is potentially better since you can pipe into other tools like jq? One thing I noticed with the experimental version is that you can't configure MCP tool permissions with the /agents command since technically there are no MCP tools registered. This means I have to give my agents Bash tool permission which is overkill for mcp-cli.

I've got mixed feelings on which I should use.

@rcdailey

No one has really explained

I would say: @bhosmer-ant isn't "Noone"

https://github.com/anthropics/claude-code/issues/12836#issuecomment-3667047439

No one has really explained what these two options do differently. If I understand right, the EXPERIMENTAL one is potentially better since you can pipe into other tools like jq? One thing I noticed with the experimental version is that you can't configure MCP tool permissions with the /agents command since technically there are no MCP tools registered. This means I have to give my agents Bash tool permission which is overkill for mcp-cli. I've got mixed feelings on which I should use.

I initially used the experimental MCP CLI one because of that ability you mention of being able to use it programmatically, but recently just switched to the tool search for the more "first party" feel. Planning o just waiting for the other Advanced Tool Use stuff to come out, especially Programatic Tool Use.

I would say: @bhosmer-ant isn't "Noone" #12836 (comment)

First of all, I already saw that comment. Secondly, the comment doesn't explain what those two do differently, as I originally asserted. He states that they're both meant to solve the same problem and that they're both different approaches. Not sure what the purpose of your comment is.

I initially used the experimental MCP CLI one because of that ability you mention of being able to use it programmatically, but recently just switched to the tool search for the more "first party" feel. Planning o just waiting for the other Advanced Tool Use stuff to come out, especially Programatic Tool Use.

Thanks for this; it was a good read. I think I'll wait too, because the two solutions discussed in this issue don't seem to work well with custom agents. I was able to trial and error a bit to eventually get them working, but it's all based on undocumented stuff and feels very hacky, especially when it comes to tool permissions.

Positive feedback to share: I've been using ENABLE_TOOL_SEARCH for several days now, and it's good enough that I'm considering auto-setting this in my zsh init!

Is mcp-cli the intended future for programmatic tool calling or is there another solution in the works?

Feedback on ENABLE_TOOL_SEARCH with custom agents:

To assign specific MCP tools to an agent, you must also include MCPSearch in the tools list:

tools: MCPSearch, mcp__octocode__githubSearchCode, mcp__octocode__githubGetFileContent

This is undocumented (discovered via trial and error). The agent works, but inefficiently: it calls MCPSearch first to fetch tool docs before using them.

Suggested behavior:

1. Specify tools without MCPSearch (e.g. tools: mcp__octocode__githubSearchCode)
2. Automatically load tool definitions into the agent context for each listed tool
3. Agent uses tools directly without the MCPSearch lookup step

This would be more performant and hide the MCP optimization implementation detail from agent configuration. Tools not listed would continue to be optimized away as usual (not consuming tokens).

How to persist ENABLE_TOOL_SEARCH

For those who discovered this env var works - here's how to make it permanent across sessions:

Windows (PowerShell)

# Add to $PROFILE
$env:ENABLE_TOOL_SEARCH = "true"

macOS / Linux / WSL

# Add to ~/.zshrc or ~/.bashrc
export ENABLE_TOOL_SEARCH=true

Important: After adding, open a new terminal and start Claude Code from there. Verify with /context - you should see "loaded on-demand" next to MCP tools.

<img width="693" height="427" alt="Image" src="https://github.com/user-attachments/assets/61cc80f1-fb70-424e-b0fd-7a961fce54ca" />

@shostako just add it to your .claude/settings.json

{
  "env" : {
     "ENABLE_TOOL_SEARCH": "true"
  }
}

We’ve been measuring a persistent state substrate that ends up cheaper than RAG-by-default under equivalent workloads, while also materially reducing frontend and tool-loading overhead.

We’re still validating results and not publishing details yet, but it’s changing how we think about where inference cost actually accrues—especially in long-running or agentic setups where retrieval and compaction start behaving like cost multipliers.

We’ve been measuring a persistent state substrate that ends up cheaper than RAG-by-default under equivalent workloads, while also materially reducing frontend and tool-loading overhead. We’re still validating results and not publishing details yet, but it’s changing how we think about where inference cost actually accrues—especially in long-running or agentic setups where retrieval and compaction start behaving like cost multipliers.

Interesting. Would love to see the details

Based on my tests, the feature is not production-ready. CC no longer proactively uses certain MCPs.

Based on my tests, the feature is not production-ready. CC no longer proactively uses certain MCPs.

Depending on how the search is already being done, I wonder if this could be largely remedied by the search query (and handling) be what the model "wants to do" rather than a search for specific tools and their definitions. I believe Rube/Composio does something similar, and it allows for a smarter search. Just have a cheap model equipped with more context of the enabled tools handle the query and return whatever's relevant.

Appreciate the interest.

We’re still in the middle of longer-horizon runs and cross-checking results under a few different baseline assumptions, so we’re intentionally not sharing implementation details yet.

What’s been most surprising so far isn’t any single optimization, but where the cost ends up accruing once sessions persist and tool/search behavior compounds over time. Some of the early ratios only stabilize after hours-long runs, which makes short benchmarks pretty misleading.

In a few workloads, marginal token overhead appears to compress by multiples rather than percentages once state persists—but the exact range is baseline-dependent, so we’re finishing validation before publishing ratios.

We’ll share more once the data is locked and reproducible under independent assumptions—but for now we’re focused on finishing validation rather than expanding scope.

mark

Appreciate the interest — we’ve completed an initial concrete pass on the data, so sharing a small, bounded snapshot for context.

In one representative tool-heavy workload from our validation set, comparing identical calls under pinned conditions, we observe an order-of-magnitude reduction in input-token overhead between two runs, alongside a meaningful latency improvement, while holding run settings constant.

Importantly, this is a single-point snapshot, not a stabilized long-horizon ratio. The behavior we care about is marginal cost over longer horizons, which only stabilizes after extended runs and varies materially by baseline and workload shape. That’s why we’re being cautious about publishing generalized ratios until the validation window is fully locked and reproducible.

Happy to share more detail once that process is complete.

@catherinewu I reported a bug related to ENABLE_EXPERIMENTAL_MCP_CLI here.

48h Long-Horizon A/B Validation Offer — Tool-Heavy Agent Metrics

Hi all — building on discussions here about efficient tool usage and MCP workflows, I’m offering a 48-hour A/B validation sprint on a tool-heavy, long-horizon workload of your choice.

Short benchmarks can be misleading in multi-step workflows. I can run pinned baselines, a stabilization window, and report ratios (tokens/interactions, p95 latency, tool call overhead) with a reproducibility checklist.

Implementation specifics remain private until a mutual eval agreement — only methodology and results will be shared publicly afterward.

If you’re interested in a 20-min sync + a 48-h sprint, reply here or DM.

— Caleb

Back in December, I started using this. I used to get "mcp-cli: command not found" fairly regularly even though it might have worked earlier in the thread. I'm back and have been running cc with mcp-cli, and no problems until end of today, I saw one happen. Just fyi, sure you guys are still swotting bugs. v2.1.6

Does anyone upgrade the official 2.1.9 and Found MCPSearch tools will failed to request the next Real Tools use ？

As I back to 2.1.2 stable version and disabled both Tool Search and MCP CLI in $env

ENABLE_TOOL_SEARCH=false
ENABLE_EXPERIMENTAL_MCP_CLI=false

Claude Code call Tools works again

We've been using this with ENABLE_EXPERIMENTAL_MCP_CLI=true and it's working really well for us!
A couple of use cases where it's been especially helpful:
Config processing: We deal with pretty large config files, and being able to filter and load just the parts we need is great. The ability to download, edit, and update configs without cluttering up the context has been a huge win.
DevOps debugging: We have a debugging bot that usually needs to post-process/filter data before analysis. Using MCP tools lets us pipe and clean up the output efficiently before Claude Code even sees it, which makes everything run much smoother.
Overall, it's been a solid addition to our workflow!

@vengad-arrowhead Thanks for sharing your experience! This is really helpful feedback.

I'm curious about your setup - could you share more details about:

1. How did you configure your MCP setup for the config processing use case? Any specific server or tools you're using?
2. For the debugging bot, how is it set up? Is it running as a separate MCP server, or integrated differently?

Would love to learn more about your workflow!

Request: Extend Tool Search to Built-in System Tools

The ENABLE_EXPERIMENTAL_MCP_CLI feature is a great step forward for MCP tools, but built-in system tools still consume significant context:

| Tool Category | Tokens |
|---------------|--------|
| Built-in system tools | ~16.7k |
| System prompt | ~3.0k |
| Total fixed overhead | ~20k |

Use Case

For focused tasks (e.g., code review, documentation), many built-in tools are unnecessary:

• Code review: Only needs Read, Glob, Grep - doesn't need Write, Edit, Bash, NotebookEdit, etc.
• Research/exploration: Only needs Read, Grep, WebFetch - doesn't need Edit, Write, TodoWrite

Proposed Solution

1. Selective tool activation - Load tool definitions on-demand similar to MCP-CLI approach
2. Tool profiles - Presets like readonly, minimal, full that load relevant subsets
3. Config option - "builtinTools": ["Read", "Glob", "Grep"] to specify which tools to load

Current Limitation

Using permissions.deny prevents tool use but still loads the full definition into context, consuming tokens regardless.

Impact

Reducing built-in tool overhead from 16.7k to ~5k for common workflows would:

• Extend effective context by ~12k tokens
• Reduce compaction frequency
• Lower costs for high-volume usage

Would love to see the on-demand loading pattern extended beyond MCP tools to the core toolset.

The progress in this thread is real - MCP-CLI and Tool Search both address which tools consume context. But @aledlie's comment at the end raises the next question: what about the ~16.7k tokens from built-in system tools that every session pays regardless?

I audited that 16.7k. The issue isn't that there are too many built-in tools - it's that the tool definitions themselves are stuffed with behavioral instructions that aren't schema material:

| Tool | Schema | Behavioral | Behavioral % |
|----------------|--------|------------|--------------|
| Task | 1,800 | 4,550 | 72% |
| Bash | 1,200 | 3,850 | 76% |
| TodoWrite | 600 | 2,400 | 80% |
| EnterPlanMode | 300 | 2,100 | 88% |
| ExitPlanMode | 400 | 1,530 | 79% |
| All others | 5,200 | 7,330 | 58% |

~70% of the built-in tool payload is behavioral prose - the Bash tool's git commit protocol, TodoWrite's 9 dialogue examples, PlanMode's overlapping "when to use" guidance. This content would work identically in the system prompt, where similar instructions already live.

@aledlie's proposal for selective tool activation and tool profiles would help, but even a "minimal" profile loading Read + Glob + Grep would still carry whatever behavioral bloat those tools contain. The two approaches are complementary:

• Tool Search / selective activation reduces which tools are loaded
• Schema cleanup (#26158) reduces how much each loaded tool costs

The cleanup requires no new features, env vars, or user configuration. It's reorganizing existing content on Anthropic's side.

@bhosmer-ant - with MCP-CLI and Tool Search both addressing external tool overhead, is there any parallel effort on the built-in side? The behavioral content in tool definitions feels like it predates the current focus on context efficiency and may not have been revisited since.

@aledlie - your 16.7k measurement lines up with what I found. Did you look inside the definitions, or measure the aggregate? The breakdown above suggests that selective activation alone would still leave a lot of recoverable space on the table, even in a "minimal" profile.

While waiting for native Tool Search support, another angle on reducing token consumption is cleaning the session itself. Sessions accumulate massive amounts of redundant data (duplicate file reads, progress ticks, stale outputs) that all count toward context. Cozempic prunes this dead weight — typically 40-70% reduction — which delays compaction and means fewer tokens wasted on summarizing noise.

There's an env var you can set in your Claude Code settings that switches MCP tools to on-demand discovery instead of upfront loading -- it can cut token usage by up to 85%. You can find the full verified solution at https://cacheoverflow.dev/blog/8Ji3Cypq

Any update?

Worth noting there's a complementary angle to this problem: even after tool definitions are optimized (via deferred loading, search, etc.), the tool output from each call still consumes significant context. A single git log --stat can easily be 5,000 tokens of raw CLI text that the agent has to digest.

I built Pare to address this — it's a set of MCP servers (28 packages, 240 tools) that wrap common dev CLIs (git, npm, docker, test runners, cargo, go, etc.) and return schema-validated JSON via structuredContent. Measured reductions are typically 40–95% fewer tokens depending on the tool, with the biggest savings on verbose commands like builds, installs, and test output.

So tool search + structured output together would attack both sides of the MCP token problem — definitions and results.

I think there is a regression in version 2.1.71; Claude's code is ignoring the flag ENABLE_TOOL_SEARCH
when defined globally as an env var.

Anyone else experiencing this?

Edit1: version 2.1.72 seems to fix this regression, now tools load as expected on demand

This has shipped and is now the default for all Claude Code sessions.

The ToolSearch tool defers all tool definitions (built-in + MCP) and loads them on demand. Only the tool names are sent upfront; the model calls ToolSearch to fetch full schemas when it needs them. This is the defer_loading + tool-search API pattern you linked, wired into Claude Code's tool loading.

No configuration required — it's on by default. You can control the behavior via:

• ENABLE_TOOL_SEARCH=false → disable entirely (all tools loaded upfront, old behavior)
• ENABLE_TOOL_SEARCH=auto:N → only defer when tool definitions exceed N% of context
• ENABLE_TOOL_SEARCH=true (or unset) → always defer (current default)

Closing as shipped.

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.