# Tool calling

> Let the model call your functions with the OpenAI tools and tool_choice parameters.

Source: https://docs.serenityedge.ai/docs/tool-calling/

Tool calling lets the model ask your application to run a function and then continue the conversation with the result. Serenity Edge follows the OpenAI `tools` and `tool_choice` contract, so any client built for it works unchanged.

## How it works

1.  Describe your functions in `tools`, each with a JSON Schema for its arguments.
2.  If the model decides to call one, the response has `finish_reason: "tool_calls"` and the assistant message carries `tool_calls` with the function name and JSON-encoded arguments.
3.  Run the function, append the assistant message and a `tool` message with the result, and send the conversation again, with the same `tools`. The model then answers using the result.

## Example

### 1\. Declare the tool and send the request

```python
from openai import OpenAI
import json

client = OpenAI(base_url="https://api.serenityedge.ai/v1", api_key="YOUR_SERENITY_EDGE_API_KEY")

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get the current weather for a city.",
            "parameters": {
                "type": "object",
                "properties": {"city": {"type": "string", "description": "City name"}},
                "required": ["city"],
            },
        },
    }
]

messages = [{"role": "user", "content": "What is the weather in Valencia today?"}]

response = client.chat.completions.create(model="orion-pro", messages=messages, tools=tools, tool_choice="auto")
message = response.choices[0].message
```

### 2\. Run the function and send the result back

```python
if response.choices[0].finish_reason == "tool_calls":
    messages.append(message)
    for call in message.tool_calls:
        args = json.loads(call.function.arguments)
        result = get_weather(**args)  # your own function
        messages.append({"role": "tool", "tool_call_id": call.id, "content": json.dumps(result)})

    final = client.chat.completions.create(model="orion-pro", messages=messages, tools=tools)
    print(final.choices[0].message.content)
```

The assistant message returned in step 1 looks like this:

```json
{
  "role": "assistant",
  "content": null,
  "tool_calls": [
    {
      "id": "call_3f2a9c",
      "type": "function",
      "function": {
        "name": "get_weather",
        "arguments": "{\"city\": \"Valencia\"}"
      }
    }
  ]
}
```

## Check `finish_reason` and `usage` before you run a call

Run the calls of a response only when its `finish_reason` is `"tool_calls"`.

-   **`"length"`** means the answer reached its output limit and stopped, possibly in the middle of a call. A cut call can name a function you did not declare, lack required arguments, or carry `arguments` that are not valid JSON. Do not run it: send the request again with a higher `max_tokens`, or ask for less. When you set `max_tokens` (or `max_completion_tokens`), a tool call it cuts is reported as `"length"`, never as `"tool_calls"`.
-   **`usage.completion_tokens`** equal to the `max_tokens` you sent also means the answer was cut. Checking it too keeps the same code safe with other OpenAI-compatible providers, some of which report a cut call as `"tool_calls"`.

Set `max_tokens` on requests with tools, with room for the longest call you expect (a call that writes a file can take thousands of tokens) and for the reasoning when it is on.

On the [Responses API](https://docs.serenityedge.ai/docs/responses-api/), the same cut ends the response with `status: "incomplete"` and `incomplete_details.reason: "max_output_tokens"`, and its `function_call` item has `status: "incomplete"`. Run only `function_call` items whose `status` is `"completed"`.

## Send `tools` on every request of the conversation

Declare the same `tools` on every request whose `messages` hold tool calls or tool results, including the one that sends the results back, as step 2 above does. The model reads the earlier calls against those definitions. Without them it can still write a call, and that call may come back as text in `content` instead of in `tool_calls`, where your application would miss it.

## Give each tool its own name

Every function tool in `tools` needs a name of its own. A request that declares two function tools with the same name is refused with HTTP 400, before it reaches the model:

```json
{
  "error": {
    "message": "More than one tool is named 'get_weather': each tool needs its own name.",
    "type": "invalid_request_error",
    "param": "tools[1].function.name",
    "code": "invalid_request_error"
  }
}
```

`param` points at the second tool with that name: `tools[<i>].function.name` on `POST /v1/chat/completions`, and `tools[<i>].name` on the [Responses API](https://docs.serenityedge.ai/docs/responses-api/). Names are compared exactly, letter case included, so `get_weather` and `Get_Weather` are two different names. Such a request used to be accepted, and the arguments of a call to that name were then converted with the schema of the tool declared first, while only the name came back: your application could not tell which tool the model meant. Rename one of the tools, or remove the duplicate.

## Controlling tool use with `tool_choice`

| Value | Behaviour |
| --- | --- |
| `"auto"` (default when `tools` is set) | The model decides whether to call a tool. |
| `"none"` | The model never calls a tool. |
| `"required"` | The model must call at least one tool. |
| `{"type": "function", "function": {"name": "get_weather"}}` | The model must call that specific function. |

By default the model may return several tool calls in one response (`parallel_tool_calls: true`). Run them all and append one `tool` message per call, in any order, before sending the next request.

## Strict schemas

Set `"strict": true` on a function definition to guarantee that `arguments` matches your JSON Schema exactly. Strict mode requires `additionalProperties: false` on every object and every property listed in `required`. Use it when you parse arguments into typed structures; see [Structured outputs](https://docs.serenityedge.ai/docs/structured-outputs/) for the same mechanism applied to the final answer.

## Recommendations

-   Always validate `arguments` before use. Even in strict mode, treat them as untrusted input.
-   Act on calls only after checking `finish_reason`; see above.
-   Keep function descriptions short and concrete. The model chooses tools from the description.
-   Return compact results in `tool` messages. Everything you send back counts as input tokens.
-   For long chains of calls, prefer `orion-pro`; see [Models](https://docs.serenityedge.ai/docs/models/).

## Known limitations

-   **Tool markup inside an argument value.** If the value of a tool-call argument contains the markup the model uses to write tool calls, for example the literal text `<parameter=`, the argument can be cut at that point and an extra argument added, with no error to the client. This is a known issue. Avoid that literal text in argument values, or check the arguments of each call on your side (the expected arguments are there, none is unexpected, each value is complete) before you run it.
