tool_choice and Tool Control

Steer the model toward the right tools

By default, the model decides freely which tools to use (or whether to use any at all). The tool_choice parameter gives you finer control over this behavior.

tool_choice modes

auto (default)

The model decides freely. It can use one tool, several, or none:

{
  "model": "grok-4.20-0309-reasoning",
  "input": "What is the capital of France?",
  "tools": [{"type": "web_search"}],
  "tool_choice": "auto"
}

For this simple factual question, the model will likely answer without a web search. For a question about current events, it will launch a search.

required

Forces the model to use at least one tool:

{
  "model": "grok-4.20-0309-reasoning",
  "input": "Give me today's stock market prices.",
  "tools": [{"type": "web_search"}],
  "tool_choice": "required"
}

Useful when you know the answer requires fresh data and the model shouldn’t answer from memory.

none

Prohibits tool use, even if tools are declared:

{
  "model": "grok-4.20-0309-reasoning",
  "input": "Explain the concept of recursion.",
  "tools": [{"type": "web_search"}, {"type": "code_interpreter"}],
  "tool_choice": "none"
}

Practical for forcing a purely text response in a context where tools are normally available.

Specific function

Forces the use of a specific function:

{
  "model": "grok-4.20-0309-reasoning",
  "input": "Paris",
  "tools": [{
    "type": "function",
    "name": "get_weather",
    "description": "Retrieves the weather",
    "parameters": {
      "type": "object",
      "properties": {
        "city": {"type": "string"}
      },
      "required": ["city"]
    }
  }],
  "tool_choice": {"type": "function", "name": "get_weather"}
}

The model is constrained to call get_weather with the appropriate arguments.

parallel_tool_calls

By default, parallel_tool_calls is set to true. The model can launch multiple tools in parallel within a single turn:

{
  "model": "grok-4.20-0309-reasoning",
  "input": "Compare the weather in Paris and London.",
  "tools": [{
    "type": "function",
    "name": "get_weather",
    "description": "Retrieves the weather for a city",
    "parameters": {
      "type": "object",
      "properties": {
        "city": {"type": "string"}
      },
      "required": ["city"]
    }
  }],
  "parallel_tool_calls": true
}

The model might call get_weather("Paris") and get_weather("Londres") simultaneously, which speeds up processing.

To disable this behavior:

{
  "parallel_tool_calls": false
}

Disable parallel calls if your functions have side effects or dependencies on each other (for example, if the second function depends on the result of the first).

max_turns

The max_turns parameter limits the number of interaction turns between the model and tools on the server side:

{
  "model": "grok-4.20-0309-reasoning",
  "input": "Perform an in-depth analysis of the AI market in 2026.",
  "tools": [{"type": "web_search"}, {"type": "code_interpreter"}],
  "max_turns": 5
}

A “turn” corresponds to a complete cycle: the model calls a tool, receives the result, then decides if it needs another call. With max_turns: 5, the model can perform up to 5 server-side tool call cycles before producing its final response.

Behavior with client tools

max_turns applies only to server tools. When the model calls a client function, the counter resets on the next request. This means each client-server round trip creates a new allocation of turns.

Control strategies

Key takeaways

• tool_choice controls whether and which tools the model uses: auto, required, none, or a specific function
• parallel_tool_calls (default true) enables simultaneous tool calls
• max_turns limits server tool cycles—client calls reset the counter
• Use required when fresh data is essential
• Disable parallelism if your functions have dependencies on each other