Tool Calling

Tool Calling#

Tool calling (also called function calling) lets a model request that you run a function and feed the result back. It is what allows coding agents to read files, run commands, and search codebases.

Models advertising the Tools capability on the Models page support this.

1. Describe your tools#

{
  "model": "claude-opus-4.8",
  "messages": [{"role": "user", "content": "What is the weather in Dhaka?"}],
  "tools": [{
    "type": "function",
    "function": {
      "name": "get_weather",
      "description": "Get the current weather for a city",
      "parameters": {
        "type": "object",
        "properties": {
          "city": {"type": "string", "description": "City name"},
          "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}
        },
        "required": ["city"]
      }
    }
  }],
  "tool_choice": "auto"
}

2. The model asks for a call#

{
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": null,
      "tool_calls": [{
        "id": "call_abc123",
        "type": "function",
        "function": {
          "name": "get_weather",
          "arguments": "{\"city\":\"Dhaka\",\"unit\":\"celsius\"}"
        }
      }]
    },
    "finish_reason": "tool_calls"
  }]
}

arguments is a JSON string — parse it before use. A finish_reason of tool_calls means the model is waiting on you.

3. Return the result#

Append the assistant message verbatim, then a tool message carrying the output:

{
  "model": "claude-opus-4.8",
  "messages": [
    {"role": "user", "content": "What is the weather in Dhaka?"},
    {
      "role": "assistant",
      "content": null,
      "tool_calls": [{
        "id": "call_abc123",
        "type": "function",
        "function": {"name": "get_weather", "arguments": "{\"city\":\"Dhaka\"}"}
      }]
    },
    {
      "role": "tool",
      "tool_call_id": "call_abc123",
      "content": "{\"temp_c\":31,\"sky\":\"humid\"}"
    }
  ],
  "tools": [ ... same definitions ... ]
}

The model then answers in natural language: "It's 31°C and humid in Dhaka right now."

tool_choice#

Parallel calls#

A single response may contain several entries in tool_calls. Execute them all and return one tool message per call, each matching its own tool_call_id.

Streaming with tools#

Tool calls stream as deltas. Accumulate choices[0].delta.tool_calls[].function.arguments across chunks — arguments arrive in fragments and are only valid JSON once the stream finishes.

Python example#

import json
from openai import OpenAI

client = OpenAI(api_key="cc_your_key_here", base_url="https://cleanapis.com/v1")

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

messages = [{"role": "user", "content": "What is the weather in Dhaka?"}]

response = client.chat.completions.create(
    model="claude-opus-4.8", messages=messages, tools=tools
)
message = response.choices[0].message

if message.tool_calls:
    messages.append(message)
    for call in message.tool_calls:
        args = json.loads(call.function.arguments)
        result = {"temp_c": 31, "sky": "humid"}   # your real implementation
        messages.append({
            "role": "tool",
            "tool_call_id": call.id,
            "content": json.dumps(result),
        })

    final = client.chat.completions.create(
        model="claude-opus-4.8", messages=messages, tools=tools
    )
    print(final.choices[0].message.content)