> ## 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/ai-router/responses/v3-create-response)
* [`POST /v3/router/chat/completions`](/reference/ai-router/chat/create-chat-completion)

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.

`max_tool_calls` limits the server-side loop. Chat Completions defaults to 10 calls and accepts values from 1 to 30. The field is optional on the Responses API.

## 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://api.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" }
      ],
      "max_tool_calls": 10
    }'
  ```

  ```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://api.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://api.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="/docs/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="/docs/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="/docs/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="/docs/ai-gateway/features/server-tools/image-generation">
    `orq:image_generation`: Generate an image with a configured image model.
  </Card>

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

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

  <Card title="Apply patch" icon="file-pen" href="/docs/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="/docs/ai-gateway/features/server-tools/knowledge-bases">
    `retrieve_knowledge_bases` and `query_knowledge_base`: List and query
    knowledge bases in the workspace.
  </Card>

  <Card title="Search models" icon="magnifying-glass-chart" href="/docs/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="/docs/ai-gateway/features/server-tools/subagent">
    `orq:subagent`: Delegate a self-contained task to another model.
  </Card>

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

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

## 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](/docs/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
    }
  }
}
```

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`.

## Chat Completions limitations

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

* `plugins`
* legacy `guardrails` or `evaluators`
* `n` greater than `1`
* provider-hosted tool types such as `web_search` or `file_search`

The endpoint returns `400` for these combinations. Function tools remain supported alongside server tools.

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`      |