With function calling, the model can decide that it needs data from your system for a response, for example a stock level or an appointment. FlowModels supports this in OpenAI's format through tools. One important point up front: We don't run your functions. The model tells you which function it wants to call with which values. You run it in your system and send the result back.
The two-step flow
A function call always consists of two requests, and both are billed:
- You send the question together with the description of your functions.
- The model responds with a call. You run it and send the result back in a second request. Only then does the model write the actual response.
Step 1: Offer functions
{
"model": "groq/openai/gpt-oss-120b",
"messages": [{"role": "user", "content": "Is item A-1042 still in stock?"}],
"tools": [{
"type": "function",
"function": {
"name": "get_stock_level",
"description": "Returns the current stock level of an item.",
"parameters": {
"type": "object",
"properties": {"item_number": {"type": "string"}},
"required": ["item_number"]
}
}
}]
}
If the model wants to use the function, you get a response with finish_reason: "tool_calls", content: null and the requested calls:
"message": {
"role": "assistant",
"content": null,
"tool_calls": [{
"id": "call_abc",
"type": "function",
"function": {"name": "get_stock_level", "arguments": "{\"item_number\":\"A-1042\"}"}
}]
}
arguments is a text with JSON inside, not an object. Parse it in your code before you use the values, and validate them like any other input.
Step 2: Send the result back
Without the Brain, you send the history so far, the model's message with tool_calls and your result as a message with role: "tool". The tool_call_id must match the id from the call exactly, otherwise the API rejects the request with HTTP 400:
{
"model": "groq/openai/gpt-oss-120b",
"messages": [
{"role": "user", "content": "Is item A-1042 still in stock?"},
{"role": "assistant", "tool_calls": [{"id": "call_abc", "type": "function", "function": {"name": "get_stock_level", "arguments": "{\"item_number\":\"A-1042\"}"}}]},
{"role": "tool", "tool_call_id": "call_abc", "content": "{\"stock\": 37, \"warehouse\": \"Hamburg\"}"}
],
"tools": [ … same list as in step 1 … ]
}
If you use the Brain with external_identifier, in the second step you send only the same external_identifier, the conversation from the response and the message with role: "tool". We've already stored the model's call. Sending the entire history again would double the context. More on the Brain in Use the Brain: store and continue conversations per end user.
Control when a function is called
tool_choice:"auto"lets the model decide,"none"prohibits calls,"required"forces at least one, and{"type": "function", "function": {"name": "get_stock_level"}}forces exactly this function. The name must appear intools.parallel_tool_calls: allows or prohibits several calls in one response.
Both fields are only allowed together with tools.
Limits
- at most 128 functions per request
- each description at most 65,536 characters, each schema at most 65,536 bytes
- function names consist of 1 to 64 characters: letters, digits, underscores and hyphens
Whether a model accepts functions at all is shown in GET /models under capabilities.tools and capabilities.parallel_tool_calls. If the capability is missing, you get 400 unsupported_for_model, see What a model can do: check capabilities, limits, output length and reasoning effort.
Streaming and Responses
With streaming, the calls arrive collected in a separate chunk right before the end, in choices[0].delta.tool_calls with index. On the /responses endpoint, they appear as entries of type function_call in output, and you respond with an entry of type function_call_output. There too, you send the functions themselves in the nested form shown above.
If something goes wrong
400 invalid_field_valuewithtoolsandflowai_tools: The two fields are mutually exclusive.flowai_toolscontrols tools on our side,toolsyour own functions.- The model keeps calling the function: Check that your message with
role: "tool"carries the righttool_call_idand that the second step includes the model's message withtool_calls. 400because of the name: Spaces, periods and umlauts aren't allowed in the function name.