Tool Calling

Use function tools through Chat, Responses, Claude Messages, or Gemini schemas when supported by the model.

How tool calling works

You describe functions in tools. The model may respond with one or more tool_calls instead of plain text. Your code runs each call, then sends the results back as tool-role messages so the model can produce a final answer. This loop repeats until the model returns a normal message.

Define and call a tool

curl https://onerouter.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.2",
    "messages": [{"role": "user", "content": "What is the weather in Paris?"}],
    "tools": [{
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Get the current weather for a city",
        "parameters": {
          "type": "object",
          "properties": { "city": {"type": "string"} },
          "required": ["city"]
        }
      }
    }],
    "tool_choice": "auto"
  }'

Tool call response

When the model decides to call a tool, finish_reason is tool_calls and the call appears in message.tool_calls. Execute it, then append the result as a tool message keyed by tool_call_id.

JSON
{
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "tool_calls": [{
        "id": "call_abc",
        "type": "function",
        "function": { "name": "get_weather", "arguments": "{\"city\":\"Paris\"}" }
      }]
    },
    "finish_reason": "tool_calls"
  }]
}

Protocol differences

ParameterTypeRequiredDescription
Chat CompletionstoolsoptionalUse `tools`, `tool_choice`, assistant `tool_calls`, and tool-role messages.
ResponsestoolsoptionalUse response output items such as function calls and function call outputs.
Claude MessagestoolsoptionalUse Claude `tool_use` and `tool_result` content blocks.
GeminitoolsoptionalUse Gemini function declarations and function responses.

Model-dependent features

OneRouter keeps protocol compatibility and forwards model-specific parameters where supported. Features such as tool calling, structured output, reasoning, prompt caching, web search, image input, audio input, video generation, and provider-specific options depend on the selected model and upstream provider. Check the model detail page before relying on a feature in production.