> For the complete documentation index, see [llms.txt](https://docs.qolaba.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.qolaba.ai/api-platform/openai-compatible-chat/tool-calls.md).

# Tool Calls

The API supports OpenAI-compatible function calling. Define your functions in the request; the model decides when to call them, and the server returns the call details for you to execute on the client

### Step 1 — Define tools and get a tool call

```json
import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: process.env.API_KEY,
  baseURL: 'http://localhost:9000/v1',
});

const completion = await client.chat.completions.create({
  model: 'openai/gpt-4o',
  messages: [
    { role: 'user', content: 'What is the weather in Tokyo?' }
  ],
  tools: [
    {
      type: 'function',
      function: {
        name: 'get_weather',
        description: 'Get the current weather for a city',
        parameters: {
          type: 'object',
          properties: {
            location: {
              type: 'string',
              description: 'City name, e.g. Tokyo, Japan'
            },
            unit: {
              type: 'string',
              enum: ['celsius', 'fahrenheit'],
              description: 'Temperature unit'
            }
          },
          required: ['location']
        }
      }
    }
  ],
  tool_choice: 'auto',
  built_in_tools: 'none'  // disable server tools so only yours are offered
});

console.log(completion.choices[0].message.tool_calls);
```

**Response — model decides to call your function**

```json
{
  "id": "chatcmpl-xyz",
  "object": "chat.completion",
  "created": 1740700000,
  "model": "openai/gpt-4o",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": null,
        "tool_calls": [
          {
            "id": "call_abc123",
            "type": "function",
            "function": {
              "name": "get_weather",
              "arguments": "{\"location\": \"Tokyo, Japan\", \"unit\": \"celsius\"}"
            }
          }
        ]
      },
      "finish_reason": "tool_calls"
    }
  ]
}
```

### Step 2 — Execute the function and send the result back

Parse `arguments`, call your function, then continue the conversation with a `tool` message:

```json
// Parse arguments and call your function
const toolCall = completion.choices[0].message.tool_calls[0];
const args = JSON.parse(toolCall.function.arguments);

// Your own function execution
const weatherResult = await myGetWeather(args.location, args.unit);

// Continue conversation with the tool result
const followUp = await client.chat.completions.create({
  model: 'openai/gpt-4o',
  messages: [
    { role: 'user', content: 'What is the weather in Tokyo?' },
    completion.choices[0].message,  // include the assistant's tool_calls message
    {
      role: 'tool',
      tool_call_id: toolCall.id,
      content: JSON.stringify(weatherResult)
    }
  ],
  tools: [ /* same tool definitions */ ],
  built_in_tools: 'none'
});

console.log(followUp.choices[0].message.content);
// "The current weather in Tokyo is 12°C with partly cloudy skies."
```

### Controlling tool selection

| `tool_choice` value                                    | Behaviour                                                |
| ------------------------------------------------------ | -------------------------------------------------------- |
| `"auto"` (default)                                     | Model decides whether to call a tool or respond directly |
| `"none"`                                               | Model must not call any tool                             |
| `"required"`                                           | Model must call at least one tool                        |
| `{ "type": "function", "function": { "name": "fn" } }` | Model must call this exact function                      |

```
// Force a specific function
"tool_choice": { "type": "function", "function": { "name": "get_weather" } }
```

### Multi-tool call in one turn

The model can call multiple tools at once:

```json
{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": null,
        "tool_calls": [
          {
            "id": "call_001",
            "type": "function",
            "function": { "name": "get_weather", "arguments": "{\"location\":\"Tokyo\"}" }
          },
          {
            "id": "call_002",
            "type": "function",
            "function": { "name": "get_weather", "arguments": "{\"location\":\"London\"}" }
          }
        ]
      },
      "finish_reason": "tool_calls"
    }
  ]
}
```

Send all tool results back in one follow-up request, one `tool` message per call:

```json
{
  "messages": [
    { "role": "user", "content": "Compare weather in Tokyo and London." },
    { "role": "assistant", "content": null, "tool_calls": [ ...both calls... ] },
    { "role": "tool", "tool_call_id": "call_001", "content": "{\"temp\": 12, \"condition\": \"Cloudy\"}" },
    { "role": "tool", "tool_call_id": "call_002", "content": "{\"temp\": 8, \"condition\": \"Rainy\"}" }
  ]
}
```