Function calling (also known as tool calling) provides a powerful and flexible way for OpenAI models to interface with external systems and access data outside their training data. This guide shows how you can connect a model to data and actions provided by your application. We’ll show how to use function tools (defined by a JSON schema) and custom tools which work with free form text inputs and outputs.
For Agents API sessions, use Functions to register functions and handle session action requests. The examples in this guide show the Responses API and Chat Completions integrations.
If your application has many functions or large schemas, you can pair function calling with tool search to defer rarely used tools and load them only when the model needs them. Only gpt-5.4 and later models support tool_search.
GPT-6 Astra requires the Responses API for tool calling. The Chat Completions examples use GPT-5.6 for compatibility. See the migration guide to update an existing integration.
How it works
Let’s begin by understanding a few key terms about tool calling. After we have a shared vocabulary for tool calling, we’ll show you how it’s done with some practical examples.
The tool calling flow
Tool calling is a multi-step conversation between your application and a model via the OpenAI API. The tool calling flow has five high level steps:
- Make a request to the model with tools it could call
- Receive a tool call from the model
- Execute code on the application side with input from the tool call
- Make a second request to the model with the tool output
- Receive a final response from the model (or more tool calls)
With Responses, your application can continue this flow for as many tool calls as the task requires. If you want a framework that packages recurring orchestration around that loop, see how the Responses API compares with the Agents SDK.
Function tool example
Let’s look at an end-to-end tool calling flow for a get_horoscope function that gets a daily horoscope for an astrological sign.
from openai import OpenAI
import json
client = OpenAI()
# 1. Define a list of callable tools for the model
tools = [
{
"type": "function",
"function": {
"name": "get_horoscope",
"description": "Get today's horoscope for an astrological sign.",
"parameters": {
"type": "object",
"properties": {
"sign": {
"type": "string",
"description": "An astrological sign like Taurus or Aquarius",
},
},
"required": ["sign"],
"additionalProperties": False,
},
"strict": True,
},
},
]
def get_horoscope(sign):
return f"{sign}: Next Tuesday you will befriend a baby otter."
messages = [{"role": "user", "content": "What is my horoscope? I am an Aquarius."}]
# 2. Prompt the model with tools defined
response = client.chat.completions.create(
model="gpt-5.6",
messages=messages,
tools=tools,
)
messages.append(response.choices[0].message)
for tool_call in response.choices[0].message.tool_calls or []:
if tool_call.function.name == "get_horoscope":
# 3. Execute the function logic for get_horoscope
args = json.loads(tool_call.function.arguments)
horoscope = get_horoscope(args["sign"])
# 4. Provide function call results to the model
messages.append(
{
"role": "tool",
"tool_call_id": tool_call.id,
"content": json.dumps({"horoscope": horoscope}),
}
)
response = client.chat.completions.create(
model="gpt-5.6",
messages=messages,
tools=tools,
)
# 5. The model should be able to give a response!
print(response.choices[0].message.content)from openai import OpenAI
import json
client = OpenAI()
# 1. Define a list of callable tools for the model
tools = [
{
"type": "function",
"name": "get_horoscope",
"description": "Get today's horoscope for an astrological sign.",
"parameters": {
"type": "object",
"properties": {
"sign": {
"type": "string",
"description": "An astrological sign like Taurus or Aquarius",
},
},
"required": ["sign"],
},
},
]
def get_horoscope(sign):
return f"{sign}: Next Tuesday you will befriend a baby otter."
# Create a running input list we will add to over time
input_list = [{"role": "user", "content": "What is my horoscope? I am an Aquarius."}]
# 2. Prompt the model with tools defined
response = client.responses.create(
model="gpt-6-astra",
tools=tools,
input=input_list,
)
# Save function call outputs for subsequent requests
input_list += response.output
for item in response.output:
if item.type == "function_call":
if item.name == "get_horoscope":
# 3. Execute the function logic for get_horoscope
sign = json.loads(item.arguments)["sign"]
horoscope = get_horoscope(sign)
# 4. Provide function call results to the model
input_list.append(
{
"type": "function_call_output",
"call_id": item.call_id,
"output": horoscope,
}
)
print("Final input:")
print(input_list)
response = client.responses.create(
model="gpt-6-astra",
instructions="Respond only with a horoscope generated by a tool.",
tools=tools,
input=input_list,
)
# 5. The model should be able to give a response!
print("Final output:")
print(response.model_dump_json(indent=2))
print("\n" + response.output_text)Note that for reasoning models like GPT-5 or o4-mini, any reasoning items returned in model responses with tool calls must also be passed back with tool call outputs.
Defining functions
Functions are usually declared in the tools parameter of each API request. With tool search, your application can also load deferred functions later in the interaction. Either way, each callable function uses the same schema shape. A function definition has the following properties:
| Field | Description |
|---|