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

# Server Tools

> Give models access to real-time capabilities like web search and datetime. Server Tools are executed by ARouter on behalf of the model, with no additional client-side logic required.

Server Tools are capabilities that ARouter executes on behalf of models during inference. Unlike user-defined function calling (where your code runs the function), Server Tools are handled entirely by ARouter — the model decides when to invoke them, ARouter executes them, and the results are injected back into the conversation automatically.

<Note>
  Server Tools are currently in **beta**. The interface is stable but additional tools are being added.
</Note>

## Available Server Tools

| Tool ID      | Description                                                 | Pricing          |
| ------------ | ----------------------------------------------------------- | ---------------- |
| `web_search` | Search the web and return structured results with citations | Per search query |
| `datetime`   | Return the current date and time in any timezone            | Free             |

## Server Tools vs Plugins vs User-Defined Tools

|                            | Server Tools                 | Plugins                        | User-Defined Tools           |
| -------------------------- | ---------------------------- | ------------------------------ | ---------------------------- |
| Who executes?              | ARouter                      | ARouter                        | Your application             |
| Model controls invocation? | Yes                          | No (applied every request)     | Yes                          |
| Structured citations?      | Yes                          | Yes (web only)                 | N/A                          |
| Available in streaming?    | Yes                          | Yes                            | Yes                          |
| Configuration              | Per-request in `tools` array | Per-request in `plugins` array | Per-request in `tools` array |

Use Server Tools when you want the model to decide whether and when to search, rather than forcing a search on every request.

## How Server Tools Work

```mermaid theme={null}
sequenceDiagram
    participant App as Your App
    participant AR as ARouter
    participant Model as LLM Model
    participant Tool as Tool (e.g. Web)

    App->>AR: POST /v1/chat/completions (with server tools)
    AR->>Model: Forward request with tool definitions
    Model->>AR: Tool call: web_search("latest AI news")
    AR->>Tool: Execute search
    Tool->>AR: Search results
    AR->>Model: Inject results as tool response
    Model->>AR: Final response with citations
    AR->>App: Return response
```

The entire tool execution cycle happens server-side. Your application receives the final response with results already incorporated.

## Quick Start

Add Server Tools to any chat completion request via the `tools` array using the `arouter:` namespace:

```json theme={null}
{
  "model": "openai/gpt-5.4",
  "messages": [
    {"role": "user", "content": "What are the top AI news stories today?"}
  ],
  "tools": [
    {"type": "arouter", "arouter": {"id": "web_search"}}
  ]
}
```

<Tabs>
  <Tab title="TypeScript">
    ```typescript theme={null}
    import OpenAI from "openai";

    const client = new OpenAI({
      baseURL: "https://api.arouter.ai/v1",
      apiKey: "lr_live_xxxx",
    });

    const response = await client.chat.completions.create({
      model: "openai/gpt-5.4",
      messages: [
        { role: "user", content: "What are the top AI news stories today?" }
      ],
      tools: [
        { type: "arouter", arouter: { id: "web_search" } } as any,
      ],
    });

    console.log(response.choices[0].message.content);
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    from openai import OpenAI

    client = OpenAI(
        base_url="https://api.arouter.ai/v1",
        api_key="lr_live_xxxx",
    )

    response = client.chat.completions.create(
        model="openai/gpt-5.4",
        messages=[
            {"role": "user", "content": "What are the top AI news stories today?"}
        ],
        tools=[
            {"type": "arouter", "arouter": {"id": "web_search"}}
        ],
        extra_body={},
    )

    print(response.choices[0].message.content)
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    curl https://api.arouter.ai/v1/chat/completions \
      -H "Authorization: Bearer lr_live_xxxx" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "openai/gpt-5.4",
        "messages": [
          {"role": "user", "content": "What are the top AI news stories today?"}
        ],
        "tools": [
          {"type": "arouter", "arouter": {"id": "web_search"}}
        ]
      }'
    ```
  </Tab>
</Tabs>

## Combining Multiple Server Tools

You can enable multiple Server Tools in a single request. The model will choose which to invoke based on the user's query:

```json theme={null}
{
  "model": "openai/gpt-5.4",
  "messages": [
    {"role": "user", "content": "What important AI events happened this week?"}
  ],
  "tools": [
    {"type": "arouter", "arouter": {"id": "web_search"}},
    {"type": "arouter", "arouter": {"id": "datetime"}}
  ]
}
```

## Combining with User-Defined Tools

Server Tools can coexist with your own function definitions:

```json theme={null}
{
  "model": "openai/gpt-5.4",
  "messages": [{"role": "user", "content": "..."}],
  "tools": [
    {"type": "arouter", "arouter": {"id": "web_search"}},
    {
      "type": "function",
      "function": {
        "name": "get_user_data",
        "description": "Get data from our internal database",
        "parameters": {...}
      }
    }
  ]
}
```

ARouter handles the `arouter` type tools; your application handles the `function` type tools.

## Usage Tracking

Server Tool usage is tracked in the `usage` field:

```json theme={null}
{
  "usage": {
    "prompt_tokens": 450,
    "completion_tokens": 210,
    "total_tokens": 660,
    "cost": 0.00234,
    "server_tool_calls": {
      "web_search": 2
    }
  }
}
```

## Next Steps

* [Web Search Tool](/en/guides/features/server-tools/web-search) — Full configuration reference for search engines, domain filtering, and pricing
* [Datetime Tool](/en/guides/features/server-tools/datetime) — Inject current time into model context
* [Migrating from Web Plugin](/en/guides/features/web-search) — How to migrate from the deprecated `web` plugin