> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orq.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Server tools

> Let models search the web, run code, query knowledge bases, consult other models, and complete other tasks through tools operated by the AI Gateway.

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:

* [`POST /v3/router/responses`](/reference/responses/create-response)
* [`POST /v3/router/chat/completions`](/reference/chat/create-chat-completion)

`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

1. Add one or more server tools to the request's `tools` array.
2. The model chooses whether to call a tool and supplies its runtime arguments.
3. The **AI Gateway** executes the tool and returns the result to the model.
4. 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.

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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" }
      ]
    }'
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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);
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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)
  ```
</CodeGroup>

## Available tools

<CardGroup cols={2}>
  <Card title="Web search" icon="magnifying-glass" href="/ai-gateway/features/server-tools/web-search">
    `orq:web_search`: Search the public web for current information.
  </Card>

  <Card title="Web fetch" icon="link" href="/ai-gateway/features/server-tools/web-fetch">
    `orq:web_fetch`: Fetch and extract text from a public URL.
  </Card>

  <Card title="Datetime" icon="clock" href="/ai-gateway/features/server-tools/datetime">
    `orq:datetime`: Return the current date and time in an IANA timezone.
  </Card>

  <Card title="Image generation" icon="image" href="/ai-gateway/features/server-tools/image-generation">
    `orq:image_generation`: Generate an image with a configured image model.
    Responses API only.
  </Card>

  <Card title="Code interpreter" icon="code" href="/ai-gateway/features/server-tools/code-interpreter">
    `orq:code_interpreter`: Run Python in an isolated sandbox.
  </Card>

  <Card title="Shell" icon="terminal" href="/ai-gateway/features/server-tools/shell">
    `orq:shell`: Run commands in an isolated Linux sandbox.
  </Card>

  <Card title="Apply patch" icon="file-pen" href="/ai-gateway/features/server-tools/apply-patch">
    `orq:apply_patch`: Validate file changes before the application applies
    them.
  </Card>

  <Card title="Knowledge bases" icon="database" href="/ai-gateway/features/server-tools/knowledge-bases">
    `orq:retrieve_knowledge_bases` and `orq:query_knowledge_base`: List and
    query knowledge bases in the workspace.
  </Card>

  <Card title="Search models" icon="magnifying-glass-chart" href="/ai-gateway/features/server-tools/search-models">
    `orq:search_models`: Search the **Orq.ai** model catalog by capability and
    cost.
  </Card>

  <Card title="Subagent" icon="user-group" href="/ai-gateway/features/server-tools/subagent">
    `orq:subagent`: Delegate a self-contained task to another model.
  </Card>

  <Card title="Advisor" icon="lightbulb" href="/ai-gateway/features/server-tools/advisor">
    `orq:advisor`: Ask another model for advice during a response.
  </Card>

  <Card title="Fusion" icon="diagram-project" href="/ai-gateway/features/server-tools/fusion">
    `orq:fusion`: Compare answers from a panel of models.
  </Card>
</CardGroup>

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 JSON theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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](/ai-gateway/features/tool-calling) 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 JSON theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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)     |