Advanced Tool Use with the Claude API

Tool use usually fails for one of three reasons: tool definitions consume the context window, the model sends invalid arguments, or large intermediate results repeatedly pass through the model. Diagnose the failure first, then choose Tool Search, Programmatic Tool Calling, or input_examples. They solve different problems.

---

Choose the control that matches the failure

Tool Search reduces the definitions loaded up front. Programmatic calls reduce tool_result round trips. Prompt caching lowers the cost of stable prefixes, while context editing can remove results that no longer help the task.

---

1. Tool Search: load definitions on demand

Tool Search is useful when the catalogue itself affects baseline context. Marking a tool with defer_loading: true keeps its full definition out of the initial prompt. Claude searches first, then loads matching tools through a tool reference.

import os
from anthropic import Anthropic

client = Anthropic()

tools = [
    {"type": "tool_search_tool_regex_20251119", "name": "tool_search"},
    {
        "name": "get_customer_orders",
        "description": "Return orders for one customer. Use for order history, not account details.",
        "defer_loading": True,
        "input_schema": {
            "type": "object",
            "properties": {"customer_id": {"type": "string"}},
            "required": ["customer_id"],
        },
    },
]

response = client.messages.create(
    model=os.environ["ANTHROPIC_MODEL"],
    max_tokens=1200,
    tools=tools,
    messages=[{"role": "user", "content": "Show the three latest orders for C-1042"}],
)

Acceptance checks

• Deferred schemas are absent from the initial prompt.
• Search distinguishes tools with similar names but different responsibilities.
• Each description says when to use the tool and when not to use it.
• Traces record search hit rate, added latency, and input tokens.

---

2. Programmatic Tool Calling: keep batch work in the sandbox

Programmatic Tool Calling lets Claude write code in a Code Execution environment and call authorised tools from that code. It works well for fan-out, aggregation, filtering, and conditional branches because intermediate results do not have to enter the conversation one item at a time.

tools = [
    {"type": "code_execution_20260120", "name": "code_execution"},
    {
        "name": "get_service_health",
        "description": "Return health and latency for one service.",
        "allowed_callers": ["code_execution_20260120"],
        "input_schema": {
            "type": "object",
            "properties": {"service": {"type": "string"}},
            "required": ["service"],
        },
    },
]

For “find every service above 500 ms latency,” the useful data path is:

Claude writes a loop
  → sandbox calls get_service_health concurrently
  → sandbox filters latency_ms > 500
  → only anomalous services enter the model context

Do not use this pattern when every step needs a fresh model judgement. In that case, code execution adds overhead without removing model turns.

---

3. input_examples: fix valid-looking but wrong arguments

JSON Schema expresses types and required fields, but team conventions are often more specific: timestamps need a business timezone, two optional fields must appear together, or evidence links are mandatory for a high-severity action.

{
    "name": "create_incident",
    "description": "Create an incident after an alert is verified. Do not use for unverified alerts.",
    "input_schema": {
        "type": "object",
        "properties": {
            "service": {"type": "string"},
            "severity": {"type": "string", "enum": ["sev1", "sev2", "sev3"]},
            "started_at": {"type": "string", "description": "ISO 8601 with timezone"},
            "evidence_urls": {"type": "array", "items": {"type": "string"}},
        },
        "required": ["service", "severity", "started_at", "evidence_urls"],
    },
    "input_examples": [{
        "service": "checkout-api",
        "severity": "sev2",
        "started_at": "2026-08-25T09:42:00+10:00",
        "evidence_urls": ["https://monitor.example/incidents/abc"],
    }],
}

Examples consume tokens too. Add them only where argument errors are common. Improve the description first, add an example second, and add prompt rules only when those controls are insufficient.

---

A rollout that produces evidence

1. Classify trace failures as wrong tool, invalid arguments, or oversized result.
2. Change one control for each failure class.
3. Build an eval set of 30–100 real tasks, including empty results and permission errors.
4. Compare success rate, input tokens, tool rounds, P95 latency, and total cost.
5. Roll out gradually and retain standard tool use as a fallback.

Definition of done

• Tool-selection accuracy has not regressed.
• Schema validation failures are below the team threshold.
• Large results are filtered before entering the model.
• Every claimed saving is backed by traces or billing data.

Common mistakes

Practice task

For a catalogue of 35 order, customer, refund, inventory, and shipping tools:

1. Identify the 3–5 tools needed to investigate a delayed order.
2. Defer the remaining definitions.
3. Query order and shipping status programmatically.
4. Add a refund input example with a timezone and evidence link.
5. Compare the old and new approach on the same 20 tasks.

Self-check

• I can explain which failure each technique reduces.
• I have not treated version strings in examples as permanent constants.
• I record cost, latency, and accuracy separately.
• I can fall back to standard tool use.

Related reading

• Code Execution with MCP
• Tool Design Principles
• Agent Evaluation

Official references

• https://platform.claude.com/docs/en/agents-and-tools/tool-use/manage-tool-context
• https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-reference
• https://www.anthropic.com/engineering/advanced-tool-use