Tool Calling

Tool calling (a.k.a. function calling) lets a model emit structured calls into JSON tool definitions you supply. ai& supports tool calling on both the OpenAI Chat Completions and Anthropic Messages surfaces.

Defining tools

OpenAI shape
Anthropic shape

tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "Get current weather for a city.",
        "parameters": {
            "type": "object",
            "properties": {"city": {"type": "string"}},
            "required": ["city"],
        },
    },
}]

response = client.chat.completions.create(
    model="...",
    messages=[{"role": "user", "content": "Weather in Tokyo?"}],
    tools=tools,
    tool_choice="auto",
)

tools = [{
    "name": "get_weather",
    "description": "Get current weather for a city.",
    "input_schema": {
        "type": "object",
        "properties": {"city": {"type": "string"}},
        "required": ["city"],
    },
}]

response = client.messages.create(
    model="...",
    max_tokens=1024,
    tools=tools,
    messages=[{"role": "user", "content": "Weather in Tokyo?"}],
)

Parallel tool calls

OpenAI-shape requests can set parallel_tool_calls: true (the default) to let the model emit multiple tool calls in a single turn.

tool_choice / forced calls

"auto" — model decides whether to call a tool (default when tools is set).
"none" — disable tool use for this request.
"required" — force the model to call a tool.
{ "type": "function", "function": { "name": "..." } } — force a specific tool.