Tool Search, Programmatic Tool Calling, Tool Use Examples: cut tokens for tool-heavy agents

Connect five MCP servers with a few dozen tools and your agent has already "eaten" tens of thousands of tokens on tool definitions before the user asks their first question. On top of that, every tool call is a model turn, and intermediate results (logs, data tables) all pour into context. In November 2025 Anthropic launched three beta features on the Claude Developer Platform aimed at exactly these three bottlenecks: Tool Search Tool, Programmatic Tool Calling and Tool Use Examples. All three are enabled with the beta header advanced-tool-use-2025-11-20.

Overview

1. Tool Search Tool: load tools on demand

Mark tools as deferred: Claude only sees the search tool and non-deferred tools; when it needs something, it searches, and only matching tools are expanded into full definitions. It doesn't break prompt caching because tools are added after the prefix.

"tools": [
  {"type": "tool_search_tool_regex_20251119", "name": "tool_search_tool_regex"},
  {"name": "github_create_issue", "description": "...",
   "input_schema": {...}, "defer_loading": true}
]

There's a BM25 variant, or you can write your own embedding-based search. For MCP, set defer_loading as the default for a whole server and keep a few frequently used tools loaded.

Use it when: tool definitions exceed ~10K tokens, you have 10+ tools, or several MCP servers. Skip it when: under 10 tools, or every tool is used in every session.

2. Programmatic Tool Calling: let code call tools

Instead of one model turn per tool, Claude writes Python that runs in the code execution environment, calling tools in loops, conditionals and in parallel, then filtering/aggregating results. Only the script's final output enters context. The post's example: a budget compliance check reduced about 200KB of raw expense data to about 1KB of results.

"tools": [
  {"type": "code_execution_20250825", "name": "code_execution"},
  {"name": "get_expenses", "description": "...", "input_schema": {...},
   "allowed_callers": ["code_execution_20250825"]}
]

When the script calls a tool you receive a tool_use with a caller field, return the result as usual, and the script continues.

Use it when: large data where only aggregates matter, chains of 3+ dependent calls, bulk operations. Skip it when: a single simple call, or when Claude should reason over every intermediate result.

3. Tool Use Examples: teach by example

JSON Schema describes types but can't express conventions: date formats, when to fill nested objects, which parameters go together. Add an input_examples array to the tool definition:

"input_examples": [
  {"title": "Login returns 500", "priority": "critical",
   "escalation": {"level": 2, "notify": ["oncall"]}},
  {"title": "Update internal docs"}
]

Recommendations: 1–5 examples per tool, realistic values, a mix of minimal and full versions, focused on what the schema leaves ambiguous.

Risks and caveats

• All of these are beta: type names and headers may change, so keep an eye on the docs.
• Tool search adds a search step, i.e. latency; only worth it when context savings are large.
• Programmatic calling needs the code execution environment; tools allowed to be called from code should be safe to run repeatedly/in parallel.
• Examples cost tokens too; don't add them to simple tools.
• The numbers are Anthropic's; measure on your own eval set.

How to apply it

• Dev: Measure the tokens taken by tools in your requests. Above 10K, try tool search first; for multi-step data-processing workflows, try programmatic calling.
• Tech Lead: Start from your biggest bottleneck: context bloat (tool search), large intermediate results (PTC), or wrong parameters (examples). The three complement each other.
• PM: For products integrating many systems, these features directly cut cost per task and belong in your optimisation plan.