Models → Pricing → Docs → Blog → Changelog → Contact → Status →
Get started freeLog in

Tool Calling

Let models call your functions — the mechanism behind AI coding agents.

⏱ 3 min read

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

Value Behaviour
"auto" Model decides whether to call a tool (default when tools is present)
"none" Never call a tool
"required" Must call at least one tool
{"type": "function", "function": {"name": "get_weather"}} Must call that specific function

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="fm_your_key_here", base_url="https://freemodel.in/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)
Was this page helpful?
Still stuck?
Open a support ticket from your dashboard or ask the community on Telegram.
CommunityGet help