How to beginner · 3 min read

OpenAI tool choice parameter explained

Quick answer

The OpenAI tools parameter lets you define external functions or tools your chat model can call during completion. Instead of the deprecated functions and function_call parameters, use tools to specify callable actions with JSON schema, enabling the model to invoke them dynamically.

PREREQUISITES

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

Setup

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

Install SDK: pip install openai
Set environment variable: export OPENAI_API_KEY='your_api_key' (Linux/macOS) or setx OPENAI_API_KEY "your_api_key" (Windows)

bash

pip install openai

output

Collecting openai
  Downloading openai-1.x.x-py3-none-any.whl (xx kB)
Installing collected packages: openai
Successfully installed openai-1.x.x

Step by step

Use the tools parameter to define a function your chat model can call. The model will respond with a tool_calls finish reason when invoking the tool.

python

import os
import json
from openai import OpenAI

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

# Define a tool for getting weather info
weather_tool = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "Get weather for a location",
        "parameters": {
            "type": "object",
            "properties": {
                "location": {"type": "string"}
            },
            "required": ["location"]
        }
    }
}]

messages = [{"role": "user", "content": "What's the weather in New York?"}]

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=messages,
    tools=weather_tool
)

print("Model response:", response.choices[0].message.content)

if response.choices[0].finish_reason == "tool_calls":
    tool_call = response.choices[0].message.tool_calls[0]
    args = json.loads(tool_call.function.arguments)
    print("Tool call name:", tool_call.function.name)
    print("Tool call arguments:", args)

output

Model response: 
Tool call name: get_weather
Tool call arguments: {'location': 'New York'}

Common variations

You can use different models like gpt-4o or gpt-4o-mini. The tools parameter replaces the older functions and function_call parameters. For async usage, use async client calls. Streaming is supported but tool calls are typically synchronous.

python

import asyncio
import os
import json
from openai import OpenAI

async def main():
    client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])

    tools = [{
        "type": "function",
        "function": {
            "name": "get_time",
            "description": "Get current time",
            "parameters": {"type": "object", "properties": {}, "required": []}
        }
    }]

    messages = [{"role": "user", "content": "What time is it?"}]

    response = await client.chat.completions.create(
        model="gpt-4o",
        messages=messages,
        tools=tools
    )

    print("Async model response:", response.choices[0].message.content)

asyncio.run(main())

output

Async model response:

Troubleshooting

If you see no tool_calls finish reason, ensure your tools parameter is correctly formatted and the model supports tool use.
Do not use deprecated functions or function_call parameters; they are replaced by tools.
Check your API key and environment variable setup if authentication errors occur.

✅

Key Takeaways

Use the tools parameter to define callable functions for OpenAI chat models.
The model signals tool invocation with finish_reason == 'tool_calls' and provides arguments in tool_calls.
Avoid deprecated functions and function_call parameters; use tools instead.

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

Verify ↗