Kimi K3.1 Pro tool choice configuration: automatic, forced, and disabled tool calls

One-sentence takeaway

Kimi K3.1 Pro's tool_choice can select automatic decision-making, disable tools, require at least one tool call, or specify a particular function for each request; tool search commonly uses required on the first round and switches back to auto after retrieval.

Use cases

• Suitable tasks: Chat Completions requests that need to control whether the current turn enters a tool path, such as forced retrieval, ordinary conversation, and text-only answers.

• Unsuitable tasks: Using required without declaring any callable tools, or forcing a particular function while thinking is enabled.

• Applicable model version: kimi-k3.1-pro; the official complete request example explicitly uses this model ID.

• Applicable client, Agent, or API: Kimi API Chat Completions; the client declares tools in the request and handles the tool results.

• Recommended reasoning tier and parameters: The page gives no separate recommendation for a reasoning tier; specifying a function is incompatible with enabled thinking and returns 400.

Ready-to-use content

The four selection methods are as follows. Omitting tool_choice is equivalent to setting it to "auto":

{"tool_choice": "auto"}
{"tool_choice": "none"}
{"tool_choice": "required"}
{"tool_choice": {"type": "function", "function": {"name": "get_weather"}}}

• auto: The model decides from the context whether to call a tool; this is also the default value.

• none: Disables tool calls. The model returns plain text and does not produce tool_calls.

• required: Requires at least one tool call in the current turn; the request must declare at least one callable tool.

• Function object: Forces the specified function to be called; it is incompatible with enabled thinking.

Official K3.1 Pro request example:

curl https://api.moonshot.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $MOONSHOT_API_KEY" \
  -d '{
    "model": "kimi-k3.1-pro",
    "messages": [{
      "role": "user",
      "content": "What is the weather like in Beijing today?"
    }],
    "tools": [{
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Get the current weather for a given city",
        "parameters": {
          "type": "object",
          "properties": {
            "city": {"type": "string", "description": "City name"}
          },
          "required": ["city"]
        }
      }
    }],
    "tool_choice": "required"
  }'

Test or workflow steps

1. Declare the complete function definitions allowed in the current turn under tools; for ordinary conversation, omit tool_choice or explicitly set it to "auto".

2. Set "required" for forced retrieval or database queries, and confirm that at least one callable tool is available; tool search can force a call to search_tools on the first round.

3. After tool retrieval is complete, switch back to "auto" in the next request so the model can decide whether to call a retrieved tool.

4. Set "none" when only a text answer is needed, avoiding accidental tool calls and reducing latency and token consumption.

5. Use a function object when only one function is allowed, and confirm that thinking is not enabled; tool_choice independently constrains each request's generation and can be adjusted by round.

Original evidence and data

• The page defines auto as the default; not setting tool_choice is equivalent to setting it to "auto". required requires at least one tool call in the current turn, and the request must declare at least one callable tool.

• none produces plain text and does not generate tool_calls; the page notes that this can also reduce latency and token consumption.

• A specified function uses {"type":"function","function":{"name":"get_weather"}}; the page explicitly states that it is incompatible with enabled thinking and returns 400.

• The official complete request example uses model: "kimi-k3.1-pro", a weather function, and tool_choice: "required"; the first round can also use required to force a call to search_tools, followed by a switch back to auto after retrieval.

• tool_choice constrains generation only for the current request; setting or changing it does not invalidate the prefix cache.

Scope and limitations

• The “at least one call” requirement for required assumes that callable tools have been declared; the page gives no specific error code for a request without tools, so no unverified error conclusion should be added.

• none only expresses that the current turn should not produce a tool call; whether tools are declared and how historical messages are handled remain the client's responsibility. The page does not describe the full behavior of auto, none, or required under thinking.

• The K3.1 Pro-specific evidence is the model ID in the official complete request; the page's general explanation of tool_choice should not be treated as model-specific hands-on testing for other legacy models.

• tool_choice does not execute functions, validate parameters, enforce permissions, handle timeouts, or retry; those responsibilities remain with the client.

• This note did not use an API key to make local or online calls, and records no success rate, latency, cost, or actual 400 response.

Reproduction notes

1. Open the official Tool Choice page and verify the four values and the complete K3.1 Pro request example.

2. Using an available API key, send separate requests with model="kimi-k3.1-pro" and at least one function tool for auto, none, and required.

3. First use required to call the tool search function, then switch to auto in the next request and verify the tool selection on each round.

4. Send the specified function object separately with thinking enabled, record the 400 returned by the API, and do not treat a static documentation example as a completed API test.

5. Record each request's tool_choice, whether it produced tool_calls, response status, and token usage; do not write API keys or sensitive parameters to logs.