# Custom function calling

Tool calling enables IFM models to use functions implemented by an application. Interfaces are defined with the standard OpenAI tool schema, so existing tool definitions work unchanged.

1. **The application** implements and executes the function.
2. **The function interface** — including its name, description, and parameters — is defined in the `tools` array.
3. **The model** selects the appropriate function and generates its arguments but does not execute the function itself.

## Declare the interface

Pass an array of function definitions in `tools`. Names, descriptions, and JSON Schema parameters are all standard.

In the example below, `lookup_order_status` is a function your application already implements.

```
{
  "type": "function",
  "function": {
    "name": "lookup_order_status",
    "description": "Current status of a customer order.",
    "parameters": {
      "type": "object",
      "properties": { "order_id": { "type": "string" } },
      "required": ["order_id"]
    }
  }
}
```

## The tool loop

The model answers with `finish_reason: "tool_calls"` and an empty `content`. Execute the function, append the result, and re-send — looping until `finish_reason: "stop"`.

```
messages = [
  {"role": "user", "content": "Where is my order A-10432?"},
  {
    "role": "assistant",
    "content": "",
    "reasoning_content": "User wants live order status; call lookup_order_status with the order id.",
    "tool_calls": [{"id": "call_1", "type": "function",
      "function": {"name": "lookup_order_status", "arguments": "{\"order_id\":\"A-10432\"}"}}]
  },
  {"role": "tool", "tool_call_id": "call_1", "content": "{\"status\": \"shipped\", \"eta\": \"2026-09-17\"}"},
  # the next assistant message answers using the tool result
]
```

## Choosing when tools run

`tool_choice` controls whether the model is allowed — or required — to call a function on a given turn.

| Value | Behavior |
| --- | --- |
| "auto" | Default when tools are present. The model decides whether to call a tool or answer directly. |
| "none" | Tools stay visible to the model but are never called. Useful for a final summarizing turn. |
| "required" | The model must call at least one tool. Use when your flow cannot proceed without data. |
| {"type": "function", …} | Forces one named function. The model still chooses the arguments. |

The model may return several entries in `tool_calls` in a single turn — each one needs its own `tool` message back.

_Last updated: September 2, 2026_