Claude Architect · Lesson

tool_choice: auto / any / forced

Let the model choose, force a tool, or pin one by name.

Who Decides: Model or You?

When you give Claude tools, one question shapes the whole interaction: who decides whether a tool runs?

The tool_choice field on your API request answers it. You can let the model decide, force it to call some tool, or pin one specific tool by name.

Getting this right is core to Tool Allocation: the wrong setting produces chatty text when you needed structured data, or a forced tool call when the model should have just answered.

The Three Modes

There are three values for tool_choice:

auto — the model freely picks: emit text, or call a tool.
any — the model must call some tool (its choice which), so the turn returns a tool call, never free text.
{"type":"tool","name":"X"} — force one specific named tool.

Each maps to a different intent: flexible reasoning, guaranteed structured output, or a hard-pinned action.

request = {
    "model": "claude-sonnet-4-5",
    "max_tokens": 1024,
    "tools": tools,
    "tool_choice": {"type": "auto"},  # or "any", or a named tool
    "messages": messages,
}

All lessons in this course

← Back to Claude Architect