Tool use and function calling

Let a model call your functions — the request loop, both formats, and the mistakes that cost tokens.

Tool use lets the model ask you to run a function and then continue with the result. It is the mechanism behind every coding agent.

The loop

1. You send messages plus tools describing what is available.
2. The model replies with stop_reason: tool_use and a tool_use block naming the tool and its arguments.
3. You execute it — the gateway never runs your code.
4. You send the whole history back plus a tool_result block.
5. The model produces its final answer, or asks for another tool.

Defining tools (Messages format)

Copy{
  "model": "claude-sonnet-4-6",
  "max_tokens": 1024,
  "tools": [{
    "name": "get_weather",
    "description": "Current weather for a city. Use when the user asks about weather.",
    "input_schema": {
      "type": "object",
      "properties": {"city": {"type": "string", "description": "City name"}},
      "required": ["city"]
    }
  }],
  "messages": [{"role": "user", "content": "Weather in Paris?"}]
}

Returning a result

Copy{
  "role": "user",
  "content": [{
    "type": "tool_result",
    "tool_use_id": "toolu_01ABC...",
    "content": "18C, light rain"
  }]
}

OpenAI format

The /v1/chat/completions endpoint takes the OpenAI tools / tool_calls shape instead, with results returned as messages with role tool.

What tool use costs

• Definitions are resent every turn. Twenty verbose tool schemas can dominate your input tokens before the conversation even starts.
• Results become context. A tool returning 200 rows of JSON puts all of it in the next request, and every request after that.
• Each round trip is a billed call. A five-tool task is at least six requests.
• Cap tool output length and summarise before returning. Truncating a result to what the model actually needs is the highest-leverage change in most agent loops.