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
- Describe your functions in
tools, each with a JSON Schema for its arguments. - If the model decides to call one, the response has
finish_reason: "tool_calls"and the assistant message carriestool_callswith the function name and JSON-encoded arguments. - Run the function, append the assistant message and a
toolmessage with the result, and send the conversation again, with the sametools. The model then answers using the result.
Example
1. Declare the tool and send the request
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
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:
{
"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 carryargumentsthat are not valid JSON. Do not run it: send the request again with a highermax_tokens, or ask for less. When you setmax_tokens(ormax_completion_tokens), a tool call it cuts is reported as"length", never as"tool_calls".usage.completion_tokensequal to themax_tokensyou 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, 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:
{
"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. 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 for the same mechanism applied to the final answer.
Recommendations
- Always validate
argumentsbefore 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
toolmessages. Everything you send back counts as input tokens. - For long chains of calls, prefer
orion-pro; see 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.