The tool_choice parameter controls whether and how the model calls tools. Four modes, each for a specific use case.
The four modes
auto (default) — the model decides freely whether to call a tool, which tool to call, or respond with text only. Maximum flexibility. Use for general-purpose agents where the model should choose the best approach.
any — the model MUST call a tool but can choose which one. Guarantees a tool call without specifying which. Use when you need tool execution but the specific tool depends on context.
tool + name — forces the model to call a specific named tool. {"type": "tool", "name": "extract_metadata"} guarantees extract_metadata runs. Use for pipeline steps where ordering matters (“always extract metadata first”).
none — prevents all tool calls. The model responds with text only. Use for analysis/response-only steps where tool execution should be blocked.
When forced selection matters
In extraction pipelines, the first step must always call extract_metadata before any processing. With auto, the model might skip it or call a different tool first. With forced selection (type: "tool", name: "extract_metadata"), it’s guaranteed.
After the forced first step, switch back to auto for subsequent steps where the model should choose freely.
auto vs any
auto allows text-only responses — the model might decide no tool is needed. any requires a tool call — the model must pick one. If you need guaranteed tool execution without caring which tool, use any. If the model should sometimes just respond without tools, use auto.
Changing tool_choice between turns
tool_choice can change between API calls within an agentic loop. First call: forced extract_metadata. Second call: auto for free selection. Third call: none for text-only summary. This gives per-turn control over tool usage.
One-liner: auto (model decides), any (must call a tool), tool+name (forces specific tool), none (text only) — use forced selection for pipeline ordering and auto for general-purpose flexibility.