How to beginner · 3 min read

How to use tool choice in OpenAI API

Q: How to use tool choice in OpenAI API

Use the tool_choice parameter in the OpenAI API chat completions to specify which tool or plugin the model should use for generating structured outputs. Pass tool_choice as part of the request to guide the model's response format and capabilities.

Quick answer

Use the tool_choice parameter in the OpenAI API chat completions to specify which tool or plugin the model should use for generating structured outputs. Pass tool_choice as part of the request to guide the model's response format and capabilities.

PREREQUISITES

Python 3.8+
OpenAI API key (free tier works)
pip install openai>=1.0

Setup

Install the official OpenAI Python SDK and set your API key as an environment variable.

bash

pip install openai>=1.0

Step by step

Use the tool_choice parameter in the chat.completions.create method to specify the tool or plugin you want the model to use. This example shows how to request a structured JSON output using a hypothetical tool named json-formatter.

python

import os
from openai import OpenAI

client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Generate a JSON summary of the latest sales data."}],
    tool_choice="json-formatter"
)

print(response.choices[0].message.content)

output

{
  "total_sales": 12345,
  "top_product": "Widget A",
  "region": "North America"
}

Common variations

You can use different tools by changing the tool_choice value to match the tool or plugin you want to invoke. The parameter works similarly across models like gpt-4o and gpt-4o-mini. For asynchronous calls, use async client methods if supported.

python

import asyncio
import os
from openai import OpenAI

async def main():
    client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])
    response = await client.chat.completions.acreate(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": "Provide a structured XML output for user data."}],
        tool_choice="xml-generator"
    )
    print(response.choices[0].message.content)

asyncio.run(main())

output

<user>
  <name>John Doe</name>
  <email>john@example.com</email>
</user>

Troubleshooting

If you receive an error about an invalid tool_choice, verify the tool name is supported by the model and your API plan.
If the output is not structured as expected, check the tool's documentation for required prompt formats or parameters.
Ensure your SDK version supports the tool_choice parameter; upgrade if necessary.

✅

Key Takeaways

Use the tool_choice parameter in OpenAI's chat completions to select specific tools for structured outputs.
Pass tool_choice as a top-level argument alongside model and messages in your API call.
Verify tool names and SDK versions to avoid errors and ensure compatibility.

Verified 2026-04 · gpt-4o, gpt-4o-mini

Verify ↗