Docs

Tools & function calling

Defining tools, the call loop, and why tool schemas count as input tokens.

Tools (function calling) work on both surfaces — chat/completions and messages — and in both streaming and non-streaming mode.

Defining a tool

python

tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "آب‌وهوای فعلی یک شهر را برمی‌گرداند",
        "parameters": {
            "type": "object",
            "properties": {"city": {"type": "string"}},
            "required": ["city"],
        },
    },
}]

resp = client.chat.completions.create(
    model="openai/gpt-4o-mini",
    messages=[{"role": "user", "content": "هوای تهران چطوره؟"}],
    tools=tools,
)

The call loop

Send the request with tools.
If the model decides to call one, finish_reason is tool_calls and message.tool_calls is populated.
Run the function yourself.
Append the result with role tool and the same tool_call_id , then send again.

python

messages.append(resp.choices[0].message)          # the assistant's tool call
messages.append({
    "role": "tool",
    "tool_call_id": resp.choices[0].message.tool_calls[0].id,
    "content": '{"temp_c": 31}',
})
final = client.chat.completions.create(model=..., messages=messages, tools=tools)

Tool schemas are part of the prompt and count as input tokens — on every call of that conversation. Ten tools with long descriptions can cost more than the user's actual question. Send only the tools that could plausibly be needed at that step.

The wallet hold accounts for tool schemas too, so the hold grows with a large tool set.