7. Advanced Tool Use Patterns (API)

Confidence: 90% (Tier 1 - Official Anthropic Engineering) Source: Anthropic Engineering: Advanced Tool Use | Programmatic Tool Calling Docs

Four API-level features released as generally available on February 18, 2026 (with Opus/Sonnet 4.6). These are relevant to developers building agents on the Anthropic API or Agent SDK. They are not available directly in the Claude Code CLI.

Feature	Problem Solved	Availability
Programmatic Tool Calling (PTC)	Agent loops burn tokens on round trips	API + Foundry
Dynamic Filtering	Web search bloats context with noise	API + Foundry
Tool Search Tool	Too many tool definitions bloat context	API + Foundry
Tool Use Examples	Schema alone can't express usage patterns	API + Foundry

Strategic layering: address your biggest bottleneck first:

• Context bloated by tool definitions → Tool Search Tool
• Large intermediate results → Programmatic Tool Calling
• Web research returning noise → Dynamic Filtering
• Parameter errors despite correct schema → Tool Use Examples

Programmatic Tool Calling (PTC)

The paradigm shift: instead of calling tools one at a time with a full model round trip each, Claude writes Python code that orchestrates all tool calls internally. Only the final stdout enters the context window.

Traditional: prompt → Claude → tool 1 → response 1 → Claude → tool 2 → response 2 → Claude → answer
             (3 tools = 3 inference passes, 3× intermediate results in context)

PTC:         prompt → Claude → writes Python → code calls tool 1, 2, 3 → stdout → Claude → answer
             (3 tools = 1 inference pass, only final output in context)

Configuration: mark tools callable from the code execution sandbox with allowed_callers:

{
  "tools": [
    { "type": "code_execution_20250825", "name": "code_execution" },
    {
      "name": "query_database",
      "description": "Execute SQL. Returns rows as JSON: id (str), name (str), revenue (float).",
      "input_schema": {
        "type": "object",
        "properties": { "sql": { "type": "string" } },
        "required": ["sql"]
      },
      "allowed_callers": ["code_execution_20250825"]
    }
  ]
}

allowed_callers value	Behavior
omitted / ["direct"]	Traditional calling only
["code_execution_20250825"]	Callable from Python sandbox only
["direct", "code_execution_20250825"]	Both modes, not recommended (confuses Claude)

Patterns (all run in 1 inference pass):

• Batch processing: loop over N items, aggregate, print summary
• Early termination: break as soon as success criteria are met
• Conditional tool selection: pick lightweight vs heavy tool based on intermediate result
• Data filtering: reduce what Claude sees (errors = [l for l in logs if "ERROR" in l])

Token efficiency: tool results from programmatic calls never enter Claude's context; only final stdout does. 10 programmatic tool calls ≈ 1/10th the context tokens of 10 direct calls. The ~37% overall token reduction claim is community-reported (Shayan Tabe's analysis) and not officially confirmed by Anthropic.

Constraints: API and Foundry only (not Bedrock/Vertex). No MCP tools, no web search/fetch, no strict: true tools. Container lifetime ~4.5 minutes. Not covered by Zero Data Retention.

Dynamic Filtering for Web Search/Fetch

Web search and fetch tools dump full HTML into context: navigation, ads, boilerplate included. Dynamic Filtering lets Claude write Python to pre-process and filter results before they enter its context window.

Configuration: use updated tool type versions with a beta header:

{
  "tools": [
    { "type": "web_search_20260209", "name": "web_search" },
    { "type": "web_fetch_20260209", "name": "web_fetch" }
  ]
}

Header required: anthropic-beta: code-execution-web-tools-2026-02-09. Filtering is enabled by default when using these tool type versions with Sonnet 4.6 or Opus 4.6.

Official benchmark results (Anthropic, BrowseComp dataset):

Model	Without Filtering	With Filtering	Improvement
Sonnet 4.6	33.3%	46.6%	+13.3 pp
Opus 4.6	45.3%	61.6%	+16.3 pp

Average input token reduction: ~24%. Best suited for multi-step research, citation verification, and extracting specific data points from large pages.

Tool Use Examples

JSON schemas define structure but can't express when to include optional parameters, which combinations make sense, or format conventions. Add input_examples to tool definitions to show concrete usage patterns:

{
  "name": "create_ticket",
  "input_schema": { ... },
  "input_examples": [
    { "title": "Login page 500 error", "priority": "critical", "assignee": "oncall-team", "labels": ["bug", "auth"] },
    { "title": "Add dark mode", "priority": "low", "labels": ["feature-request"] },
    { "title": "Update API docs for v2" }
  ]
}

Accuracy on complex parameter handling: 72% → 90% in Anthropic's benchmarks. Use 1-5 realistic examples per tool, covering minimal, partial, and full specifications.

Claude Code Relevance

Feature	Claude Code CLI	Action for CLI users
Tool Search (MCP lazy loading)	Built-in since v2.1.7 as MCPSearch auto mode	Tune ENABLE_TOOL_SEARCH=auto:N (documented in §6 above)
Tool Use Examples	Not configurable from CLI	Relevant for custom MCP server authors; add input_examples to tool schemas
Programmatic Tool Calling	Not available in CLI	Relevant for Agent SDK developers building custom agents
Dynamic Filtering	Not available in CLI	Relevant for Agent SDK users doing web research pipelines