Tool Choice — required vs auto vs none

~12 min · tools, tool-choice

Level 0Apprentice

0 XP0/100 lessons0/14 achievements

0/120 XP to next level120 XP to go0% complete

Three modes, three behaviors

auto — model decides whether to call a tool or answer directly. Default for chat.
required / any — model must call some tool. Useful when you've narrowed the task to tool-only paths.
tool with name — model must call this specific tool. The cleanest way to enforce JSON schema (Anthropic JSON pattern).
none — disable tool calling. Useful for the 'just answer' branch of a router.

Why this is a prompt decision

Tool choice changes the contract. If you use required, you've taken "answer directly" off the table; the prompt must make that obvious or the model will produce ill-fitting tool calls. If you use auto, your prompt must tell the model when not to call a tool — otherwise it tool-calls reflexively.

Code

Forced specific tool (Anthropic)·python

client.messages.create(
    model="claude-opus-4-7",
    tools=[verdict_tool],
    tool_choice={"type": "tool", "name": "emit_verdict"},
    messages=[...]
)

Required-any (OpenAI)·python

client.chat.completions.create(
    model="gpt-5.5",
    tools=[t1, t2, t3],
    tool_choice="required",
    messages=[...]
)

External links

Exercise

On a tool-using prompt currently in 'auto,' identify cases where the model tool-calls when it shouldn't. Add 'do not call tools when X' to the prompt or switch to 'none' on that branch. Measure improvement.

Progress

Progress is local-only — sign in to sync across devices.

← PreviousTool Calling — How the Model Decides Next →Multi-Tool Orchestration

Spotted a bug or have feedback on this page?Report an Issue

Comments 0

🔔 Reply notifications (sign in)

No comments yet — be the first.