Tool choice (often exposed as tool_choice) is the setting that tells an LLM whether it may decide on its own to call a tool, must call a tool, or must not call any tool.
Tool choice lets you control how an assistant interacts with external capabilities like search, databases, calculators, or internal APIs.
You reach for it when you want to:
In practice, this is one of the main levers for making agentic systems predictable.
Tool choice is usually part of the model request. The client declares which tools are available, then sets a policy for whether the model may use them.
Common modes are:
auto: the model can choose between replying directly and calling a tool.required: the model must call one of the provided tools before answering.none: the model is not allowed to call tools and must respond directly.Under the hood, auto delegates the decision to the model based on the prompt and tool descriptions. required is useful when the assistant should always route through a tool, such as a search or retrieval step. none is the simplest mode: no tool invocation, just text generation.
The exact API shape varies by provider, and some platforms expose additional options or slightly different names. But the core idea is stable: tool choice controls whether tool calling is optional, mandatory, or disabled.
Imagine a weather assistant with one tool: get_weather(city).
tool_choice: "auto", the model might answer “I can’t verify the weather” or call get_weather("Paris") if the user asks for today’s forecast.tool_choice: "required", it must call get_weather(...) before answering.tool_choice: "none", it can only respond from its own text knowledge and cannot call the weather tool at all.A request might look like this conceptually:
{
"messages": [{"role": "user", "content": "What's the weather in Paris?"}],
"tools": ["get_weather"],
"tool_choice": "auto"
}
required if the tool is optional. It can force unnecessary calls and add latency or cost.auto when you need strict determinism. The model may choose differently across similar prompts.none for tasks that depend on current or private data. The model will not be able to fetch it.In practice, most teams start with auto, then move to required only for workflows that truly need a tool every time.
/doc/function-calling/doc/tools/doc/agent/doc/retrieval-augmented-generation