Skip to main content
Use a current public model ID from Models or GET /models. Example IDs and options must match the selected model’s advertised capabilities and limits.
Let models call your functions. You describe the tools your application exposes; the model decides when to call them and with what arguments; you run the function and hand the result back.

​
How it works

  • You send tools: a list of function definitions with JSON Schema parameters.
  • When the model wants a function, it responds with tool_calls instead of text, and finish_reason is "tool_calls".
  • You execute the function yourself, append the result as a role: "tool" message, and call the API again.
  • The model answers using the result (or requests another call).
The model never executes anything: it only asks. Your code stays in control of every side effect.

​
Defining tools

  • type must be "function".
  • name: 1-64 characters, letters, digits, underscores, dashes.
  • description is what the model reads to decide when to call it; write it well.
  • parameters is a standard JSON Schema object. Up to 64 tools per request.

​
The tool call response

content is null on pure tool-call turns. arguments is a JSON string; parse it before use, and validate it since models can produce imperfect arguments. On reasoning models, reasoning_content may accompany the tool call.

​
Returning results

Append the assistant’s tool-call message and one role: "tool" message per call, then request again:
tool_call_id must match the id from the assistant message. content is a string; JSON-encode structured results. The model then answers normally (finish_reason: "stop").

​
Streaming tool calls

With "stream": true, tool calls arrive as delta.tool_calls fragments in the standard OpenAI shape: the first fragment carries the id, type, and function name; subsequent fragments append to function.arguments. Accumulate by the fragment’s index until the final chunk reports finish_reason: "tool_calls". OpenAI SDK streaming helpers handle this assembly for you.

​
Controlling tool choice

parallel_tool_calls (boolean, default true) controls whether the model may request several tool calls in one turn.

​
Which models support it

Check capabilities.function_calling on GET /models, or the Function Calling tag on the models page. Sending tools to an unsupported model fails fast with 400 model_lacks_function_calling before anything is billed. Tool definitions and tool calls are ordinary tokens: definitions count as input, generated calls as output, at the model’s normal rates.