Documentation
Tool calling
Let a model call your functions.
Defining tools
Pass JSON Schema function definitions. Only type: "function" exists — there are no hosted or server-side tools yet, so a tool always runs on your side.
Not every model takes tools. Check supports_tools in the model list first: a model that refuses them returns 400 tools_not_supported before the request reaches it, rather than quietly answering without calling anything.
1{2 "model": "anthropic/claude-haiku-4-5-20251001-v1:0",3 "messages": [{ "role": "user", "content": "Weather in Istanbul?" }],4 "tools": [{5 "type": "function",6 "function": {7 "name": "get_weather",8 "description": "Current weather for a city",9 "parameters": {10 "type": "object",11 "properties": { "city": { "type": "string" } },12 "required": ["city"]13 }14 }15 }]16}tool_choice
| Value | Effect |
|---|---|
"auto" | The model decides. This is the default when tools are present. |
"none" | Tools are dropped from the request entirely. |
"required" | The model must call one of them. |
{ "type": "function", "function": { "name": "..." } } | The model must call that one. |
The round trip
The reply comes back with finish_reason: "tool_calls". Run the function, then send the whole conversation again with the assistant message and a tool message answering it.
1"messages": [2 { "role": "user", "content": "Weather in Istanbul?" },3 { "role": "assistant", "tool_calls": [{4 "id": "call_1",5 "type": "function",6 "function": { "name": "get_weather", "arguments": "{\"city\":\"Istanbul\"}" }7 }] },8 { "role": "tool", "tool_call_id": "call_1", "content": "18C, clear" }9]A request may define up to 128 tools. Tool results are text; a tool cannot return an image.