Tool Calling

• /v1/chat/completions (OpenAI-style tools and tool_calls)
• /v1/responses (Responses-style function_call output items)
• /v1/messages (Anthropic-style tool_use blocks)

​

Request

curl https://api.phaseo.app/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5-nano",
    "messages": [
      { "role": "user", "content": "What is the weather in London?" }
    ],
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "get_weather",
          "description": "Get current weather by city",
          "parameters": {
            "type": "object",
            "properties": {
              "city": { "type": "string" }
            },
            "required": ["city"]
          }
        }
      }
    ],
    "tool_choice": {
      "type": "function",
      "function": { "name": "get_weather" }
    },
    "stream": false
  }'

​

Response

{
  "id": "chatcmpl_...",
  "object": "chat.completion",
  "choices": [
    {
      "index": 0,
      "finish_reason": "tool_calls",
      "message": {
        "role": "assistant",
        "content": null,
        "tool_calls": [
          {
            "id": "call_123",
            "type": "function",
            "function": {
              "name": "get_weather",
              "arguments": "{\"city\":\"London\"}"
            }
          }
        ]
      }
    }
  ]
}

​

Built-in server tools

• gateway:datetime
• phaseo:web_search
• phaseo:web_fetch
• phaseo:advisor
• phaseo:image_generation
• phaseo:apply_patch

{
  "tools": [
    {
      "type": "gateway:datetime",
      "parameters": {
        "timezones": ["Europe/London", "UTC"]
      }
    }
  ]
}

• parameters.timezones is optional and can request up to 5 valid IANA timezones in one call.
• The result contains a timezones array with ISO datetime plus the resolved timezone for each requested zone.
• Usage includes usage.server_tool_use.datetime_requests.
• Prefer tool_choice: "auto" so the model can decide when to call it.

​

Web search example

{
  "tools": [
    {
      "type": "phaseo:web_search",
      "parameters": {
        "engine": "exa",
        "max_results": 5,
        "max_total_results": 15,
        "search_context_size": "medium",
        "max_characters": 2048,
        "allowed_domains": ["arxiv.org", "nature.com"],
        "include_highlights": true
      }
    }
  ]
}

• The model supplies the search query when it calls the tool.
• engine: "auto" resolves to managed Exa search. engine: "exa", engine: "parallel", and engine: "firecrawl" run managed gateway search when the matching provider key is configured.
• engine: "native" on phaseo:web_search is converted to the provider-native web search tool for the request surface, such as OpenAI web_search_preview or Anthropic web_search_20250305.
• max_results caps each search call; max_total_results caps cumulative results across the server-tool loop.
• Managed search supports allowed_domains / excluded_domains, search_context_size, and max_characters where the selected engine exposes matching controls.
• Usage includes usage.server_tool_use.web_search_requests, usage.server_tool_use.web_search_results, and usage.server_tool_use.web_search_extra_results.
• Pricing can bill managed Exa search with server_tool_web_search_requests and server_tool_web_search_extra_results meters.

​

Web fetch example

{
  "tools": [
    {
      "type": "phaseo:web_fetch",
      "parameters": {
        "engine": "direct",
        "max_chars": 12000,
        "allowed_domains": ["docs.example.com"],
        "blocked_domains": ["internal.example.com"]
      }
    }
  ]
}

• The model supplies the target url when it calls the tool.
• Only HTTP(S) URLs and text-like content types are supported.
• engine: "auto" uses native fetch on the Anthropic Messages surface, otherwise Exa when EXA_API_KEY is configured, otherwise direct gateway HTTP fetch.
• engine: "direct" uses direct gateway HTTP fetch. engine: "exa" uses Exa content extraction when EXA_API_KEY is configured.
• engine: "parallel" uses Parallel Extract when PARALLEL_API_KEY is configured. engine: "firecrawl" uses Firecrawl Scrape when FIRECRAWL_API_KEY is configured.
• engine: "native" on the Anthropic Messages surface is converted to Anthropic’s native web_fetch_20260209 tool. Other request surfaces should use engine: "direct" or a managed extraction engine.
• max_content_tokens is accepted as a token-style bounded fetch size alias when max_chars is omitted.
• allowed_domains and blocked_domains constrain which URLs can be fetched.
• HTML content is reduced to bounded plain text before being injected back into the model loop.
• Usage includes usage.server_tool_use.web_fetch_requests.
• Pricing can bill managed fetch with the server_tool_web_fetch_requests meter. Provider-native fetch/search usage is priced with native_web_fetch_requests and native_web_search_requests; model price cards can override the built-in provider defaults.

{
  "tools": [
    {
      "type": "phaseo:web_fetch",
      "parameters": {
        "engine": "native",
        "max_content_tokens": 9000,
        "allowed_domains": ["docs.example.com"]
      }
    }
  ],
  "tool_choice": "phaseo:web_fetch"
}

​

Advisor example

{
  "tools": [
    {
      "type": "phaseo:advisor",
      "parameters": {
        "name": "reviewer",
        "model": "claude-opus-5",
        "instructions": "Review plans for correctness, missing edge cases, and implementation risk.",
        "forward_transcript": true,
        "max_uses": 2,
        "max_completion_tokens": 1400,
        "temperature": 0.2
      }
    }
  ],
  "tool_choice": "phaseo:advisor"
}

• Advisor is gateway-managed and works across supported text models. The calling model receives an phaseo_advisor tool, or a named variant such as phaseo_advisor_reviewer, and the gateway executes the Advisor request.
• parameters.name is optional. Use unique names to expose multiple advisors; names may contain letters, numbers, spaces, underscores, and dashes.
• parameters.model pins the Advisor model. If omitted, the tool call can provide model; otherwise the gateway falls back to the outer request model.
• parameters.forward_transcript defaults to false. Set it to true when the Advisor should receive the current conversation transcript.
• The model normally supplies the Advisor prompt when it calls the tool. When forward_transcript is true, the gateway can execute a transcript-only Advisor call if no prompt is supplied. max_tokens is accepted as a legacy alias for max_completion_tokens.
• Usage includes usage.server_tool_use.advisor_requests.

​

Image generation example

{
  "tools": [
    {
      "type": "phaseo:image_generation",
      "parameters": {
        "model": "openai/gpt-image-2",
        "quality": "high",
        "aspect_ratio": "16:9",
        "output_format": "png"
      }
    }
  ]
}

• The model supplies the image prompt when it calls the tool. description is also accepted as a prompt alias.
• parameters.model pins the image model. If omitted, the tool call can provide model; otherwise Phaseo uses the default image model.
• The tool result contains either imageUrl or base64 image data, depending on the provider response.
• Usage includes usage.server_tool_use.image_generation_requests; image-model token usage is merged into the parent request.

​

Apply patch example

{
  "tools": [
    {
      "type": "phaseo:apply_patch"
    }
  ],
  "tool_choice": "auto"
}

• phaseo:apply_patch is supported on the Responses API.
• Phaseo validates patch operations and returns them in the tool result. Your client decides whether to apply or reject the patch.
• Supported operation types are create_file, update_file, and delete_file.
• Usage includes usage.server_tool_use.apply_patch_requests.

​

Streaming behavior

• materialize the upstream tool-call turn
• execute the server tool
• continue the model loop
• re-emit a synthetic stream back to the client

​

Next guides

1. Tool Calling Patterns
2. Tool Calling Safety and Validation
3. Structured Outputs