This OpenAI function calling example walks through one complete tool call: you declare a tool, the model returns the tool name and arguments, your code runs the function, and you send the result back so the model can answer. The examples use curl and Python, and the base_url can be swapped for any OpenAI-compatible endpoint.
The model chooses a tool and produces arguments. Your application does the execution. The OpenAI Cookbook puts it plainly: "The API will not actually execute any function calls. It is up to developers to execute function calls using model outputs." If you are new to base_url swaps (the base URL is the prefix for API requests), see OpenAI-Compatible APIs Explained.
What function calling actually does
A normal chat request returns text. Add a tools array to the request and the model can return one or more tool_calls instead. Each call names a tool and carries JSON arguments. The model does not fetch the weather, query your database, or send the email. Your program does that part.
A full round trip looks like this:
You: messages + tools
Model: an assistant message containing tool_calls
Your code: parse the arguments and run the tool
You: append a role=tool message and call the API again
Model: read the tool result and write the final answer
When the model decides to call a tool, the response has finish_reason: "tool_calls" and a tool_calls object. When it answers directly, finish_reason is usually "stop" and the text sits in content. Treat those as separate cases. Do not assume content always contains text.
This is also what separates function calling from asking the model to print a JSON blob. Function calling returns a dedicated tool_calls structure and a matching finish_reason; you can then feed the tool result back as a role: "tool" message in the same conversation. A JSON blob is text with no return path.
Define a tool: name, purpose, parameters
A tool definition is a JSON object inside the request's tools array. Here is a minimal one:
{
"type": "function",
"function": {
"name": "get_weather",
"description": "Get the current weather for a city. Use this when the user asks about weather, temperature, or whether to bring an umbrella.",
"parameters": {
"type": "object",
"properties": {
"city": {
"type": "string",
"description": "The city name, for example San Francisco or New York"
},
"unit": {
"type": "string",
"enum": ["celsius", "fahrenheit"],
"description": "Temperature unit. Defaults to celsius."
}
},
"required": ["city"]
}
}
}
Each field affects how the model chooses and calls the tool.
type: this tutorial uses"function". OpenAI'stoolsalso accepts custom tools, which process input in a specified format; this tutorial covers function tools only.function.name: use letters, digits, underscores, or dashes, up to 64 characters.function.description: tell the model when to use the tool. "Get the current weather" is weaker than a sentence that names the user intents.function.parameters: describe the arguments with JSON Schema, a JSON-based format for defining data shapes. If you omitparameters, the function takes an empty parameter list.function.strict: optional. Set it totrueto ask the model to follow the schema more closely. The official type definition notes thatstrictsupports only a subset of JSON Schema, so check the official guide for the exact limits.
Spend some time on the parameter descriptions. city is required, and unit is limited by an enum. Those constraints are part of the schema the model sees, so the expected values are explicit. A clear tool description also gives the model a concrete rule for when the tool applies.
tool_choice controls whether the model may skip tools. The official type definition lists four options:
none: do not call any tool; generate a message instead.auto: the model can answer directly or call one or more tools. This is the default when tools are present.required: the model must call at least one tool.{"type": "function", "function": {"name": "..."}}: force a specific tool.
With no tools, the default is none. Use required when you want a tool call before the answer. Keep auto when the tool is optional.
One complete round trip
A tool-using turn has four steps:
| Step | What you send | What the model returns | What you do |
|---|---|---|---|
| 1. Request | User message in messages, tool definitions in tools | An assistant message with tool_calls, if it chooses a tool | Check finish_reason and tool_calls |
| 2. Parse | No new request yet | Each call has id, function.name, function.arguments | Run json.loads and validate the arguments |
| 3. Execute and return | A role: "tool" message with the result | No new response yet | Match tool_call_id to the call's id |
| 4. Request again | Original user message + assistant message + tool message | A final answer, or another tool call | Check finish_reason and read content |
Here is the response shape after the first request. The field names and nesting follow the official type definitions; the values are illustrative:
{
"id": "chatcmpl-example",
"object": "chat.completion",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": null,
"tool_calls": [
{
"id": "call_abc123",
"type": "function",
"function": {
"name": "get_weather",
"arguments": "{\"city\":\"San Francisco\",\"unit\":\"celsius\"}"
}
}
]
},
"finish_reason": "tool_calls"
}
]
}
arguments is a JSON string, not an object. Parse it, validate it, then call your function. A finish_reason of "tool_calls" means the model is waiting for tool results. content may be null in that case.
Next, append the tool result as a message with role: "tool". tool_call_id must match the id from the call:
{
"role": "tool",
"tool_call_id": "call_abc123",
"content": "San Francisco is 18°C and cloudy."
}
Then send the original user message, the assistant message with tool_calls, and the tool message back to the model. The OpenAI Cookbook adds a warning here: messages with role tool must be a response to a preceding message with tool_calls. If you drop the assistant message, the tool result has no call to attach to.
If the model has enough information, it writes the final answer; finish_reason is "stop" and content holds the text. If it wants another tool, finish_reason stays "tool_calls", and you repeat the execute-and-return step.
Minimal working example: curl and Python
The example uses gpt-5.5 as the model name and the public base_url https://www.su8.codes/v1 (as of November 15, 2026). You can replace the base_url with any OpenAI-compatible service and the model name with one your provider supports. The model name is a placeholder; check your provider's docs for tool-calling support. The example does not call a real weather API; get_weather returns fixed data so you can exercise the whole loop first.
curl: request and response
Put the key and base_url in environment variables:
export OPENAI_API_KEY="your API key"
export OPENAI_BASE_URL="https://www.su8.codes/v1" # replace with any OpenAI-compatible endpoint
First request, with the tool definition:
curl "$OPENAI_BASE_URL/chat/completions" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-d @- <<'JSON'
{
"model": "gpt-5.5",
"messages": [
{"role": "system", "content": "When the user asks about weather, call the get_weather tool instead of answering from memory."},
{"role": "user", "content": "What is the weather in San Francisco right now?"}
],
"tools": [
{
"type": "function",
"function": {
"name": "get_weather",
"description": "Get the current weather for a city. Use this when the user asks about weather, temperature, or whether to bring an umbrella.",
"parameters": {
"type": "object",
"properties": {
"city": {"type": "string", "description": "The city name, for example San Francisco or New York"},
"unit": {"type": "string", "enum": ["celsius", "fahrenheit"], "description": "Temperature unit. Defaults to celsius."}
},
"required": ["city"]
}
}
}
]
}
JSON
If the model picks the tool, the response contains tool_calls. Note the id, function.name, and function.arguments; you need them in the next request. The response shape is the one shown above; actual values depend on the model.
Now send the assistant message and the tool message back:
curl "$OPENAI_BASE_URL/chat/completions" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-d @- <<'JSON'
{
"model": "gpt-5.5",
"messages": [
{"role": "system", "content": "When the user asks about weather, call the get_weather tool instead of answering from memory."},
{"role": "user", "content": "What is the weather in San Francisco right now?"},
{
"role": "assistant",
"content": null,
"tool_calls": [
{
"id": "call_abc123",
"type": "function",
"function": {
"name": "get_weather",
"arguments": "{\"city\":\"San Francisco\",\"unit\":\"celsius\"}"
}
}
]
},
{
"role": "tool",
"tool_call_id": "call_abc123",
"content": "San Francisco is 18°C and cloudy."
}
]
}
JSON
This request omits tools, so the model answers from the tool result. If you want it to be able to call more tools, include the tools array again. The final answer is in message.content.
Python: validation, error returns, and a loop cap
Install the OpenAI Python SDK. Before you run the script, set OPENAI_API_KEY and OPENAI_BASE_URL (see the curl section above).
pip install openai
The loop below handles one or many tool_calls, validates the arguments, returns tool errors to the model, and stops after five rounds:
import json
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["OPENAI_API_KEY"],
base_url=os.environ["OPENAI_BASE_URL"],
)
MODEL = os.environ.get("MODEL", "gpt-5.5")
tools = [
{
"type": "function",
"function": {
"name": "get_weather",
"description": "Get the current weather for a city. Use this when the user asks about weather, temperature, or whether to bring an umbrella.",
"parameters": {
"type": "object",
"properties": {
"city": {
"type": "string",
"description": "The city name, for example San Francisco or New York",
},
"unit": {
"type": "string",
"enum": ["celsius", "fahrenheit"],
"description": "Temperature unit. Defaults to celsius.",
},
},
"required": ["city"],
},
},
}
]
def get_weather(city: str, unit: str = "celsius") -> str:
data = {
"San Francisco": {"celsius": "18°C and cloudy", "fahrenheit": "64°F and cloudy"},
"New York": {"celsius": "12°C and sunny", "fahrenheit": "54°F and sunny"},
}
return data.get(city, {}).get(unit, "No data")
messages = [
{"role": "system", "content": "When the user asks about weather, call the get_weather tool instead of answering from memory."},
{"role": "user", "content": "What is the weather in San Francisco right now?"},
]
for _ in range(5):
response = client.chat.completions.create(
model=MODEL,
messages=messages,
tools=tools,
)
message = response.choices[0].message
messages.append(message.to_dict())
if not message.tool_calls:
print(message.content)
break
for call in message.tool_calls:
try:
args = json.loads(call.function.arguments)
if not isinstance(args, dict):
raise ValueError("arguments must be a JSON object")
city = args.get("city")
if not isinstance(city, str) or not city:
raise ValueError("city must be a non-empty string")
unit = args.get("unit", "celsius")
if unit not in ("celsius", "fahrenheit"):
raise ValueError("unit must be celsius or fahrenheit")
result = get_weather(city, unit)
except (json.JSONDecodeError, ValueError, TypeError) as exc:
result = f"Invalid tool arguments: {exc}"
messages.append(
{
"role": "tool",
"tool_call_id": call.id,
"content": result,
}
)
else:
print("Stopped after the maximum number of tool rounds.")
A few details keep the loop correct:
message.to_dict()keeps the assistant message, includingtool_calls, in the conversation.json.loads(call.function.arguments)parses the arguments. A parse error, a non-object value, a missing required field, or a bad type goes to theexceptblock and becomes a tool message.- Each
tool_call_idgets its own tool message. If the model returns several calls, thefor call in message.tool_callsloop handles each one. for _ in range(5)is the round cap. If the model keeps asking for tools after five rounds, theelsebranch prints a message and stops.
The official openai-python repository also includes a Pydantic helper, openai.pydantic_function_tool, and a streaming tool-call example; see examples/parsing_tools.py and examples/parsing_tools_stream.py.
Multi-turn and parallel calls
Multi-turn tool use depends on message history. Every time the model calls a tool, keep the assistant message with tool_calls and the matching tool message in messages. On the next user turn, append the new user message; the model can still see the earlier tool results. Do not remove the assistant message with tool_calls in the middle, or the tool messages lose their referent.
Parallel calls are multiple tool_calls in one response. The OpenAI Cookbook says newer models such as gpt-5, gpt-4.1, or gpt-4o can call multiple functions in one turn. Handle them the same way: walk the list, run each tool, and return one tool message per id. The API also exposes a parallel_tool_calls parameter to enable or disable parallel tool use. If your tools have side effects or depend on order, turn it off or run them serially in your own code.
If you need to force a tool call, set tool_choice to a specific tool. If you need at least one call, use "required". Both are API parameters; check your provider's docs for support.
Common mistakes
Treating arguments as an object
The OpenAI type definition is explicit: arguments is a JSON-formatted string generated by the model, and the model does not always generate valid JSON. It may also hallucinate parameters that your schema does not define. Validate before you call the function. At a minimum, catch json.loads errors, check required fields and types, and re-check enum values, ranges, and formats. Do not execute invalid arguments; return the error in a tool message or show it to the user.
Dropping the assistant message
The Cookbook appends response_message.to_dict() before it appends the tool result. The reason is simple: a role: "tool" message must respond to a preceding assistant message with tool_calls. If you append only the tool message, the result has no call record and the request loses context. When you build messages by hand, check the order: user → assistant(tool_calls) → tool → assistant(final).
Throwing tool exceptions at the model
Tool calls fail for ordinary reasons: timeouts, missing records, insufficient permissions. A practical pattern is to turn the failure into a short sentence the model can read, such as "Lookup failed: city not found", and put it in the tool message's content. The model can then retry with different arguments or explain the failure. Do not put full stack traces, API keys, database connection strings, or user secrets in the content; that text enters the model context.
Running without a round cap
The model may keep asking for tool calls. Give the loop a maximum number of rounds, such as five, and stop when it is reached. Return the current result or an error to the user. There is no universal number; choose one based on your product and cost budget. The Python example uses for _ in range(5).
Executing model-generated arguments without a safety layer
Validation is a security control, not only a format check. The Cookbook warns before its database example that SQL generation can be high-risk in production because models are not perfectly reliable at generating correct SQL. Keep tools on a short leash: SQL may only read allowlisted tables, shell tools may only run fixed commands, and file operations stay inside a designated directory. A model saying "call delete_user" does not mean your code should delete the user.
Assuming every OpenAI-compatible service uses the same tool fields
OpenAI Chat Completions matches tool results with tool_call_id. Ollama's official tool-calling example uses tool_name in the native API instead. Both are called tool calling, but the message fields are not identical. Before you switch base_url or SDK, read the provider's docs for the tools and tool-message format. For the general idea of compatible endpoints, see OpenAI-Compatible APIs Explained.
Function calling vs MCP vs plugins
These terms show up together, but they live on different layers.
Function calling is a convention at the model API layer. You send a tool list, the model returns which tool to call and with what arguments, and your code handles execution and the return trip. It does not define how tools are discovered, connected, or authenticated.
MCP (Model Context Protocol) is a different layer. The official MCP docs define it as "an open-source standard for connecting AI applications to external systems." It exposes data sources, tools, and workflows to AI applications in a standard way; the docs compare it to a USB-C port for AI applications. MCP handles the connection. Function calling handles how the model expresses a call. Both can appear in the same agent system, each doing its own job. For the basics, see What Is MCP?.
A plugin is mostly a product-level idea: a client or platform packages a set of capabilities as an installable extension. The definition varies by platform, and it is not the same layer as the function calling format in a model API. When you see "plugin", check whether it means a platform extension, an SDK wrapper, or something else.
FAQ
Does OpenAI function calling require an OpenAI model?
No. It is a message format, and some OpenAI-compatible services support similar tools fields; the details vary by provider. Read the provider's docs before switching. The base_url in the example can be replaced with any OpenAI-compatible endpoint.
Does the model execute the function itself?
No. The OpenAI Cookbook says the API will not actually execute any function calls; the developer executes them using the model output. The same separation applies with an OpenAI-compatible provider: your code still owns execution.
Can the model call more than one tool at once?
Yes. tool_calls is an array, and newer models can return several calls in one turn. Return one tool message per id. The parallel_tool_calls parameter controls whether parallel tool use is allowed.
What should you do when a tool fails?
Return a short error summary in the tool message so the model can retry or explain the failure. Keep stack traces and secrets out of the content.
Why is the model not calling your tool?
Check whether the tool description explains when to use it, whether tool_choice is auto or required, and whether the model and provider support tool calling. A vague description makes a direct answer more likely.
Should you use function calling or MCP?
They are different layers. If the model only needs to call a few functions in your own code, function calling is enough. If you need to reuse one set of tool connections across multiple clients, look at MCP.
Final check
Run through this list before you ship.
- The tool name and
descriptionexplain the purpose and arguments parametersis valid JSON Schema, with required fields andenumvalues- The request includes
tools, andtool_choicematches your intent - The response is checked for
tool_callsandfinish_reason argumentsgoes throughjson.loadsand validation- The tool result uses
role: "tool"and the matchingtool_call_id - The assistant message with
tool_callsstays in the history - The loop has a round cap and returns errors
Once this loop works, the core of this OpenAI function calling example is in place: the model proposes the call, and your code executes it and keeps the guardrails in place.
Sources
- OpenAI Cookbook, How to call functions with chat models: https://github.com/openai/openai-cookbook/blob/main/examples/How_to_call_functions_with_chat_models.ipynb
- openai-python repository: https://github.com/openai/openai-python
- openai-python type definitions:
function_definition.py,completion_create_params.py,chat_completion_message_function_tool_call.py,chat_completion_tool_message_param.py,chat_completion.py - openai-python examples:
examples/parsing_tools.py,examples/parsing_tools_stream.py - MCP documentation, What is MCP: https://modelcontextprotocol.io/docs/2026-07-28/getting-started/intro
- Ollama documentation, Tool calling: https://docs.ollama.com/capabilities/tool-calling
- JSON Schema: https://json-schema.org/