Tool Calling

FlowAPI can forward OpenAI-style tool calling fields such as tools and tool_choice when the selected upstream model supports them. Because support is provider- and model-dependent, tool calling should be treated as a compatibility feature rather than a uniform platform guarantee.

Request Shape

Typical tool-calling requests use:

{
  "model": "gpt-4o",
  "messages": [
    { "role": "user", "content": "What is the weather in Singapore?" }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Get current weather by city name",
        "parameters": {
          "type": "object",
          "properties": {
            "city": { "type": "string" }
          },
          "required": ["city"]
        }
      }
    }
  ],
  "tool_choice": "auto"
}

Possible Model Response

When a model chooses to call a tool, the assistant message may include tool_calls:

{
  "role": "assistant",
  "content": null,
  "tool_calls": [
    {
      "id": "call_123",
      "type": "function",
      "function": {
        "name": "get_weather",
        "arguments": "{\"city\":\"Singapore\"}"
      }
    }
  ]
}

Returning Tool Results

After executing the tool in your application, send the result back as a tool message:

{
  "role": "tool",
  "tool_call_id": "call_123",
  "content": "{\"temperature_c\":30,\"condition\":\"Sunny\"}"
}

Then continue the conversation by sending the updated messages array back to the model.

Support Expectations

Tool calling support depends on:

• the selected model
• the selected provider behind that model
• how closely the upstream API matches OpenAI tool semantics

If a model does not reliably support tool calling, the safest fallback is to use structured prompting plus JSON output instead.

Best Practices

• Keep tool schemas small and explicit.
• Return machine-readable tool results such as compact JSON.
• Validate tool arguments before executing them.
• Treat tool calling as model capability, not universal API behavior.