Server tools

Server tools let a model take actions during a request without a separate tool executor in the application. Add a supported tool to the standard tools array. The AI Gateway presents it to the model, runs each tool call, and returns the model’s final answer. Server tools are available on:

orq:image_generation is available on the Responses API only. The selected model must support tool calling.

Server tools and function tools

	Server tool	Function tool
Who decides to call it	The model	The model
Who executes it	Orq.ai	The application
Request type	`orq:*` for most tools	`function`
Calls per request	Zero or more, within the configured limits	Zero or more
Result handling	The AI Gateway returns the result to the model	The application submits the function result

Server tools can share a request with function tools. Provider-hosted tools such as web_search or file_search are separate from the orq:* tools documented here.

How server tools work

Add one or more server tools to the request’s tools array.
The model chooses whether to call a tool and supplies its runtime arguments.
The AI Gateway executes the tool and returns the result to the model.
The model can call another tool or finish the response.

limits.max_iterations bounds the server-side loop. It defaults to 10 model calls and accepts values from 1 to 100. max_tool_calls is accepted on both endpoints (1 to 30 on Chat Completions) and echoed in the response, but it does not limit the server-side loop. The model sees each server tool under its type with orq: replaced by orq_ (for example orq:web_search becomes orq_web_search), and output items carry that name. Tool names must be unique within a request, so a function tool may not reuse a server tool’s name.

Quick start

This example gives the model access to web search and the current date. The model can use either tool, both tools, or neither. The upstream OpenAI TypeScript types do not define orq:* tools, so the TypeScript examples cast the tools array.

curl -X POST https://my.orq.ai/v3/router/chat/completions \
  -H "Authorization: Bearer $ORQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.4-mini",
    "messages": [
      {
        "role": "user",
        "content": "What changed in EU AI Act enforcement this month?"
      }
    ],
    "tools": [
      { "type": "orq:web_search", "max_results": 5 },
      { "type": "orq:datetime", "timezone": "Europe/Amsterdam" }
    ]
  }'

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: process.env.ORQ_API_KEY,
  baseURL: 'https://my.orq.ai/v3/router',
});

const response = await client.chat.completions.create({
  model: 'openai/gpt-5.4-mini',
  messages: [
    {
      role: 'user',
      content: 'What changed in EU AI Act enforcement this month?',
    },
  ],
  tools: [
    { type: 'orq:web_search', max_results: 5 },
    { type: 'orq:datetime', timezone: 'Europe/Amsterdam' },
  ] as any,
});

console.log(response.choices[0].message.content);

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ.get("ORQ_API_KEY"),
    base_url="https://my.orq.ai/v3/router",
)

response = client.chat.completions.create(
    model="openai/gpt-5.4-mini",
    messages=[
        {
            "role": "user",
            "content": "What changed in EU AI Act enforcement this month?",
        }
    ],
    tools=[
        {"type": "orq:web_search", "max_results": 5},
        {"type": "orq:datetime", "timezone": "Europe/Amsterdam"},
    ],
)

print(response.choices[0].message.content)

Available tools

Web search

orq:web_search: Search the public web for current information.

Web fetch

orq:web_fetch: Fetch and extract text from a public URL.

Datetime

orq:datetime: Return the current date and time in an IANA timezone.

Image generation

orq:image_generation: Generate an image with a configured image model. Responses API only.

Code interpreter

orq:code_interpreter: Run Python in an isolated sandbox.

Shell

orq:shell: Run commands in an isolated Linux sandbox.

Apply patch

orq:apply_patch: Validate file changes before the application applies them.

Knowledge bases

orq:retrieve_knowledge_bases and orq:query_knowledge_base: List and query knowledge bases in the workspace.

Search models

orq:search_models: Search the Orq.ai model catalog by capability and cost.

Subagent

orq:subagent: Delegate a self-contained task to another model.

Advisor

orq:advisor: Ask another model for advice during a response.

Fusion

orq:fusion: Compare answers from a panel of models.

The tools array also accepts orq:function, orq:http, and orq:mcp entries with a tool_id that references a tool saved in the workspace. These are references to existing platform tools, not server tools with their own configuration.

Combine server tools with functions

Function tools keep the standard OpenAI shape. The AI Gateway executes orq:* tools and returns function calls to the application.

JSON

{
  "model": "openai/gpt-5.4-mini",
  "messages": [
    { "role": "user", "content": "Find the latest EUR/USD rate and save it." }
  ],
  "tools": [
    { "type": "orq:web_search", "max_results": 3 },
    {
      "type": "function",
      "function": {
        "name": "save_exchange_rate",
        "description": "Save an exchange rate in the application database",
        "parameters": {
          "type": "object",
          "properties": {
            "pair": { "type": "string" },
            "rate": { "type": "number" }
          },
          "required": ["pair", "rate"]
        }
      }
    }
  ]
}

See Tool calling and function execution for the function-call response loop.

Usage reporting

When a counted server tool runs, the response includes its call count in usage.server_tool_use.

JSON

{
  "usage": {
    "input_tokens": 1200,
    "output_tokens": 300,
    "server_tool_use": {
      "web_search_requests": 2,
      "web_fetch_requests": 1,
      "subagent_requests": 1
    },
    "server_tool_use_details": {
      "tool_calls_executed": 4,
      "tool_calls_requested": 4
    }
  }
}

The usage object can include these counters:

Field	Tool
`web_search_requests`	Web search
`web_fetch_requests`	Web fetch
`datetime_requests`	Datetime
`code_interpreter_sessions`	Code interpreter
`advisor_requests`	Advisor
`subagent_requests`	Subagent
`search_models_requests`	Search models
`image_generation_calls`	Image generation
`fusion_requests`	Fusion
`shell_commands`	Shell

Knowledge-base retrieval and apply-patch calls do not add a field to usage.server_tool_use. usage.server_tool_use_details totals the same calls across tools: tool_calls_requested counts every server tool call the model made and tool_calls_executed counts the ones the gateway ran. For web search, web fetch, shell, and fusion, a call rejected by a max_uses limit is requested but not executed. Advisor and subagent count a rejected call as executed. Chat Completions returns these counters but not the tool result itself; read the result from the Responses API output items, or send store: true and retrieve the response.

Chat Completions limitations

On POST /v3/router/chat/completions, a request that includes an orq:* server tool cannot also include:

n greater than 1
provider-hosted tool types such as web_search or file_search
orq:image_generation
response_format.type other than text or json_schema
tool_choice other than auto, none, required, or a function selection
a model that is not in provider/model format

The endpoint returns 400 for these combinations. Function tools remain supported alongside server tools. plugins, guardrails, and evaluators are applied the same way as on requests without server tools: caller-supplied config, matched routing and guardrail rules, and workspace-enforced defaults (such as the PII redaction floor) all take effect. In streaming mode, output guardrails are skipped and output evaluators still run once the response has been assembled, matching the non-server-tool streaming behavior. Chat Completions is stateless unless store is set to true.

Legacy names

The following aliases remain accepted:

Current type	Legacy alias
`orq:web_search`	`orq:google_search`
`orq:web_fetch`	`orq:web_scraper`
`orq:datetime`	`orq:current_date`
`orq:subagent`	`orq:sidekick`
`orq:retrieve_knowledge_bases`	`retrieve_knowledge_bases` (Responses API only)
`orq:query_knowledge_base`	`query_knowledge_base` (Responses API only)

Overview

APIs

MCP Portal

Routing

Security & Privacy

Model Capabilities

Common Scenarios

Server tools

Server tools and function tools

How server tools work

Quick start

Available tools

Web search

Web fetch

Datetime

Image generation

Code interpreter

Shell

Apply patch

Knowledge bases

Search models

Subagent

Advisor

Fusion

Combine server tools with functions

Usage reporting

Chat Completions limitations

Legacy names

​Server tools and function tools

​How server tools work

​Quick start

​Available tools

Web search

Web fetch

Datetime

Image generation

Code interpreter

Shell

Apply patch

Knowledge bases

Search models

Subagent

Advisor

Fusion

​Combine server tools with functions

​Usage reporting

​Chat Completions limitations

​Legacy names

Server tools and function tools

How server tools work

Quick start

Available tools

Combine server tools with functions

Usage reporting

Chat Completions limitations

Legacy names