> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nomask.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Function Calling

> Let models call your functions: define tools, receive tool calls, return results.

> [!NOTE]
>
> Use a current public model ID from [Models](https://nomask.ai/models) or `GET /models`. Example IDs and options must match the selected model's advertised capabilities and limits.

Let models call your functions. You describe the tools your application exposes; the model decides when to call them and with what arguments; you run the function and hand the result back.

## How it works

* You send `tools`: a list of function definitions with JSON Schema parameters.
* When the model wants a function, it responds with `tool_calls` instead of text, and `finish_reason` is `"tool_calls"`.
* You execute the function yourself, append the result as a `role: "tool"` message, and call the API again.
* The model answers using the result (or requests another call).

The model never executes anything: it only asks. Your code stays in control of every side effect.

## Defining tools

```json theme={"system"}
{
  "model": "kimi-k2.6",
  "messages": [{"role": "user", "content": "What is the weather in Lagos right now?"}],
  "tools": [{
    "type": "function",
    "function": {
      "name": "get_weather",
      "description": "Get current weather for a city",
      "parameters": {
        "type": "object",
        "properties": {"city": {"type": "string"}},
        "required": ["city"]
      }
    }
  }],
  "tool_choice": "auto"
}
```

* `type` must be `"function"`.
* `name`: 1-64 characters, letters, digits, underscores, dashes.
* `description` is what the model reads to decide when to call it; write it well.
* `parameters` is a standard JSON Schema object. Up to 64 tools per request.

## The tool call response

```json theme={"system"}
{
  "choices": [{
    "message": {
      "role": "assistant",
      "content": null,
      "tool_calls": [{
        "id": "functions.get_weather:0",
        "type": "function",
        "function": {"name": "get_weather", "arguments": "{\"city\": \"Lagos\"}"}
      }]
    },
    "finish_reason": "tool_calls"
  }]
}
```

`content` is `null` on pure tool-call turns. `arguments` is a JSON *string*; parse it before use, and validate it since models can produce imperfect arguments. On reasoning models, `reasoning_content` may accompany the tool call.

## Returning results

Append the assistant's tool-call message and one `role: "tool"` message per call, then request again:

```json theme={"system"}
{
  "model": "kimi-k2.6",
  "messages": [
    {"role": "user", "content": "What is the weather in Lagos right now?"},
    {"role": "assistant", "content": null, "tool_calls": [{
      "id": "functions.get_weather:0",
      "type": "function",
      "function": {"name": "get_weather", "arguments": "{\"city\": \"Lagos\"}"}
    }]},
    {"role": "tool", "tool_call_id": "functions.get_weather:0",
     "content": "{\"temp_c\": 31, \"condition\": \"partly cloudy\"}"}
  ],
  "tools": [ ... same tools ... ]
}
```

`tool_call_id` must match the id from the assistant message. `content` is a string; JSON-encode structured results. The model then answers normally (`finish_reason: "stop"`).

## Streaming tool calls

With `"stream": true`, tool calls arrive as `delta.tool_calls` fragments in the standard OpenAI shape: the first fragment carries the `id`, `type`, and function `name`; subsequent fragments append to `function.arguments`. Accumulate by the fragment's `index` until the final chunk reports `finish_reason: "tool_calls"`. OpenAI SDK streaming helpers handle this assembly for you.

## Controlling tool choice

| Value | Behavior |
| - | - |
| `"auto"` | The model decides whether to call a tool. The default when tools are present. |
| `"none"` | Never call tools; answer in text. |
| `"required"` | Must call at least one tool. |
| `{"type": "function", "function": {"name": "get_weather"}}` | Must call that specific tool. |

`parallel_tool_calls` (boolean, default true) controls whether the model may request several tool calls in one turn.

## Which models support it

Check `capabilities.function_calling` on `GET /models`, or the Function Calling tag on the [models page](https://nomask.ai/models). Sending `tools` to an unsupported model fails fast with `400 model_lacks_function_calling` before anything is billed. Tool definitions and tool calls are ordinary tokens: definitions count as input, generated calls as output, at the model's normal rates.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.