# Tool use and function calling

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

_Source: https://aiprimetech.io/docs/api-reference/tool-use/ · Home > Docs > API reference_

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)

```json
{
  "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

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

> `tool_result` goes in a message with role `user`, and `tool_use_id` must match the id from the model's request exactly. Mismatched ids are rejected as an invalid request.


## 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.

> Tool schemas are stable across turns, which makes them a strong [prompt caching](/docs/guides/prompt-caching/) candidate alongside the system prompt.

- [Messages API](https://aiprimetech.io/docs/api-reference/messages/) — Base reference
- [Cost control](https://aiprimetech.io/docs/guides/cost-control/) — Where agent tokens go
- [MCP servers](https://aiprimetech.io/docs/guides/mcp-servers/) — Ready-made tools for Claude Code


---
_ClaudeAPIKey.dev is an independently operated, Anthropic-compatible API gateway. Not affiliated with Anthropic._