Tool calling

ModelRail returns tool calls. It does not execute your application tools.

POST/v1/chat/completions

Auth · API key

application/json

Client loop

Send available tools on the completion request.
Receive assistant tool_calls when the model needs a tool.
Execute the selected tool in your application.
Add a tool message with the result and tool_call_id.
Send the next completion request.

Things to note

Prefer the modelrail-tools alias for tool-calling workloads. Capability mismatches may return 422 no_compatible_model.

Request

{
  "model": "modelrail-tools",
  "messages": [
    { "role": "user", "content": "What is the weather in Lagos?" }
  ],
  "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"
}

When the model chooses a tool, finish_reason is tool_calls and message.tool_calls contains the function name and JSON argument string.

Continuation

{
  "model": "modelrail-tools",
  "messages": [
    { "role": "user", "content": "What is the weather in Lagos?" },
    {
      "role": "assistant",
      "content": null,
      "tool_calls": [
        {
          "id": "call_abc123",
          "type": "function",
          "function": {
            "name": "get_weather",
            "arguments": "{\"city\":\"Lagos\"}"
          }
        }
      ]
    },
    {
      "role": "tool",
      "tool_call_id": "call_abc123",
      "content": "{\"temp_c\": 31, \"condition\": \"partly cloudy\"}"
    }
  ],
  "tools": [ /* same tools array */ ]
}

Keep the full conversation, including the assistant turn that requested the tool, then append each tool result before the next completion.

Fields

Field	Notes
`tools`	Max 64; type `function` only
`tool_choice`	`"none"` \| `"auto"` \| `"required"` \| named function
`message.tool_calls`	Assistant-emitted function calls
`tool_call_id`	Required on `role: "tool"` messages