Your MCP Agent Is Burning Tokens Before It Even Starts

A practical breakdown of Programmatic Tool Calling and Progressive Tool Discovery – two patterns that slash token overhead by up to 98% and make MCP-connected agents actually scale. 

The Invisible Tax on Every Agent Request

Imagine you hire a contractor to fix one leaky tap. But before they touch a single pipe, they unpack every tool from every truck, drills, welders, excavators and lay it all out in your kitchen. That’s exactly what a naive MCP agent does every single time it receives a user message. 

Here’s what loading a typical 5-server MCP setup looks like before a single line of user content is processed: 

Anthropic’s own systems hit 134,000 tokens in tool definitions alone before optimization. At that point your model isn’t reasoning, it’s drowning. 

And token cost isn’t even the only problem. The most common agent failures are wrong tool selection and incorrect parameters, especially when tools have similar names like notification-send-user vs. notification-send-channel. More tools in context = more confusion. 

Two Patterns That Fix This

Anthropic released three new beta features in November 2025 to address this: Tool Search Tool, Programmatic Tool Calling and Tool Use Examples. Together, they represent a fundamentally different way of thinking about how agents interact with tools.

Pattern 1: Progressive Tool Discovery (Tool Search Tool) 

The core idea

Instead of loading all tool definitions upfront, tools are marked with defer_loading: true. They become discoverable without consuming tokens until actually needed. Claude only sees the Tool Search Tool itself (~500 tokens) at the start of each request.  

How it works step by step 

Step 1 – User sends a message, Only the Tool Search Tool (~500 tokens) is loaded in context. Nothing else. 

Step 2 – Agent searches for relevant tools, Claude queries the search interface. Searching “github” returns only createPullRequest and listIssues – not the other 33 GitHub tools, and certainly not your Slack, Jira, or Google Drive tools. 

Step 3 – Only matched tools expand into full definitions, 3–5 relevant tools (~3K tokens) are added to context. The rest stay dormant. 

Step 4 – Task executes with laser focus, Total context overhead: ~8,700 tokens vs. ~77,000 tokens. 95% of context window preserved. 

Implementation

{
  "tools": [
    {
      "type": "tool_search_tool_regex_20251119",
      "name": "tool_search_tool_regex"
    },
    {
      "name": "github.createPullRequest",
      "description": "Create a pull request",
      "input_schema": {},
      "defer_loading": true
    }
  ]
}

For MCP servers, you can defer entire servers while keeping your highest-priority tools always loaded: 

{
  "type": "mcp_toolset",
  "mcp_server_name": "google-drive",
  "default_config": { "defer_loading": true },
  "configs": {
    "search_files": { "defer_loading": false }
  }
}

The accuracy win

Beyond tokens, the accuracy improvement is striking. On internal MCP evaluations: 

• Claude Opus 4: 49% → 74% accuracy 
• Claude Opus 4.5: 79.5% → 88.1% accuracy 

Less noise in context = better tool selection. The model stops confusing similarly-named tools when it only ever sees the 3-5 tools it actually needs. 

Prompt caching stays intact

Deferred tools are excluded from the initial prompt entirely. They’re only added to context after Claude searches for them, so your system prompt and core tool definitions remain cacheable. No cache invalidation penalty.  

Pattern 2: Programmatic Tool Calling

The problem with traditional tool calling  

Traditional tool calling is like texting a friend one question at a time and waiting for each reply. Every single tool invocation requires: 

1. A full model inference pass 
2. The raw result dumped into context (whether useful or not) 
3. Claude “eyeballing” the data to extract relevant information 

A 5-tool workflow means 5 inference passes plus Claude parsing each result in natural language. A 20-employee budget check means 20 round-trips, with thousands of expense rows flooding context. 

What if you need to analyze a 10MB log file?

The entire file enters the context window – even though you only need a summary of error frequencies.

The solution: code as the orchestration layer

Programmatic Tool Calling enables Claude to write Python code that runs in a managed sandbox, calling multiple tools in a loop, filtering the output, and only returning a clean summary to the model context. 

Instead of: 

Claude → call tool → get result → Claude → call tool → get result → Claude...

You get: 

Claude writes code → code runs in sandbox → filtered output → Claude

A real example: budget compliance check

Traditional approach – 20 round-trips, thousands of rows in context:  

Check employee 1 expenses → result in context
Check employee 2 expenses → result in context
... × 20
Claude manually compares all results

Programmatic approach – one code block, only violators in context:  

Benchmark results 

On Browse Comp and Deep Search QA (multi-step web research benchmarks): 

• 11% accuracy improvement 
• 24% fewer input tokens 

On typical API traffic with 10–49 tool definitions: 20–40% token savings. 

How to opt in 

Tools opt into programmatic calling by specifying allowed_callers in their definition: 

{
  "name": "get_expenses",
  "description": "Fetch employee expense data",
  "allowed_callers": ["code_execution_20250825"],
  "input_schema": { ... }
}

Pattern 3: Tool Use Examples

JSON schemas define what’s structurally valid. They can’t express: 

• When to include optional parameters 
• Which combinations make sense 
• What conventions your API actually expects 
• How to handle edge cases 

Tool Use Examples solve this by letting you attach concrete demonstrations directly to tool definitions. Think of it as the difference between reading a function signature vs. reading the unit tests. 

"name": "search_files",
"description": "Search for files in a directory",
"examples": [
  {
    "input": {
      "query": "quarterly report",
      "file_type": "pdf"
    },
    "output": {
      "files": [
        "Q3_2025_Report.pdf",
        "Q4_2025_Report.pdf"
      ]
    }
  }
]

What to Consider When Connecting Your Custom Agent to MCP

Getting MCP hooked up is only the first mile. Here’s what separates agents that run in demos from agents that survive production. 

1. Tool taxonomy and naming 

The most common failure mode is wrong tool selection when tools have similar names. Namespace your tools clearly and consistently: 

• ✅ github.createPullRequest 
• ✅ slack.sendChannelMessage 
• ✅ jira.createIssue 
• ❌ create (which create?) 
• ❌ send (send what, where?) 

Treat your tool naming like a public API. It’s the contract between your agent and the model’s reasoning. 

2. Intermediate result filtering 

Never let raw API responses hit the context window unchecked. Your agent should consume insights, not raw data dumps. 

Before returning any tool result, ask: 

• Does the model need all of this, or just a summary? 
• Can I filter to only the rows/fields relevant to the task? 
• Should I paginate large datasets rather than dumping them? 

3. Error handling inside code blocks

When using Programmatic Tool Calling, failures happen silently inside code. Build explicit error handling and surface errors in your return value: 

try:
    result = get_expenses(employee_id=employee.id)
    return { "status": "ok", "data": result }
except APIError as e:
    return { "status": "error", "message": str(e), "employee_id": employee.id }

A thrown exception that crashes the sandbox gives the model nothing to work with. A structured error return lets the model decide how to recover. 

4. Decide what to defer vs. keep loaded 

Not everything should be deferred. The search step adds latency, for tools called on virtually every request, upfront loading wins. 

A good heuristic: 

5. Prompt cache safety

Deferred tools don’t break prompt caching, they’re excluded from the initial prompt. But watch out: if you have frequently-searched tools whose definitions keep changing between requests, each change will invalidate your cache for that section. 

Keep tool definitions stable. Version them if you need to update them. 

6. Combine with context compaction for long-running agents

Progressive discovery and programmatic calling solve the input side of token overhead. For long-running agents with many turns, context compaction handles the accumulated history side. Use both together for agents that need to maintain state across extended workflows. 

7. Use semantic search for large, overlapping tool libraries

The Claude Developer Platform provides regex-based and BM25-based search out of the box. For tool libraries with semantically overlapping descriptions (e.g., dozens of data retrieval tools with subtle differences), embedding-based semantic search significantly outperforms keyword matching. 

Build your search with vector embeddings when: 

• Tools have overlapping descriptions 
• You have 100+ tools across domains 
• Keyword queries frequently return irrelevant results 

Decision Guide: Which Pattern for Which Situation? 

The Numbers, Summarized 

One Last Thing to Remember

Neither pattern is magic in isolation. Programmatic Tool Calling requires your tools to opt in via allowed_callers. Tool Search adds a search round-trip that costs latency. And Tool Use Examples require you to actually write the examples. 

The combination of all three – discovery + code execution + usage examples – is where you unlock the full efficiency gains seen in production. 

The future of AI agents is one where models work seamlessly across hundreds or thousands of tools. That future doesn’t arrive by stuffing every tool definition into context and hoping for the best. It arrives by building agents that are as deliberate about what they load as they are about what they do.  

Related Searches

• How Leading Telecom Enterprise Transformed Enterprise Analytics with Fractal GPT
• Real-Time Banking Data And AI-Powered Mule Detection with Confluent Platform
• Modernizing Healthcare Data Integration with Azure Event Hubs – OpsTree
• Top Generative AI Development Companies

Related Solutions

• AI-Led FinTech Observability and DevSecOps Platform
• Cloud Infrastructure Services
• Build data platform for generative AI
• Automated security gates in CI/CD pipeline