Stop Letting Claude Skip the Tool: Four Modes of tool_choice for Reliable Agent Pipelines

tool_choice: {type: "any"} forces Claude to call a tool; {type: "tool", name: "X"} forces a specific one — eliminating the stochastic skips that break agent pipelines.

By default (tool_choice: {type: "auto"}), Claude decides on its own whether to call a tool or answer directly. That's fine for chat — but in an agent pipeline it will occasionally surprise you: a research agent skips save_findings because the answer fits in a paragraph; a pricing step answers from training data instead of calling get_current_price. The fix is one field.

The four modes

Mode	What Claude does	Use when
{type: "auto"}	Decides on its own	Default; fine for open-ended chat
{type: "any"}	Must call any tool	Force live data retrieval; prevent stale-training answers
{type: "tool", name: "X"}	Must call tool X	Structured output, persisting state, required audit logging
{type: "none"}	No tool calls	Synthesis turn after data is gathered

Walk-through

import anthropic

client = anthropic.Anthropic()

tools = [
    {
        "name": "save_findings",
        "description": "Persist research findings. Always call this before finishing.",
        "input_schema": {
            "type": "object",
            "properties": {
                "summary": {"type": "string"},
                "confidence": {"type": "number"},
            },
            "required": ["summary", "confidence"],
        },
    }
]

# Claude MUST call save_findings — no skipping, no text-only responses
response = client.messages.create(
    model="claude-sonnet-5-20251001",
    max_tokens=1024,
    tools=tools,
    tool_choice={"type": "tool", "name": "save_findings"},
    messages=[
        {"role": "user", "content": "Summarize this week's AI security news."}
    ],
)

# stop_reason == "tool_use" — guaranteed
tool_call = next(b for b in response.content if b.type == "tool_use")
print(tool_call.input)  # {"summary": "...", "confidence": 0.91}

Pattern for multi-step loops: use {type: "any"} on collection turns (force at least one lookup), then flip to {type: "none"} for the synthesis turn (synthesize what you have; no new fetches). Your agent loop becomes a predictable state machine instead of a probabilistic guess.

Parallel guard: add "disable_parallel_tool_use": true alongside tool_choice when your tools have ordering dependencies — forces one call at a time, deterministic sequence.

Sources: Parallel tool use — Claude Platform Docs · Tool choice — Claude Cookbook · Tool reference — Claude Platform Docs