Server Tools

Beta

BetaServer tools are currently in beta. The API and behavior may change.

Server tools are specialized tools operated by OpenRouter that any model can call during a request. When a model decides to use a server tool, OpenRouter executes it server-side and returns the result to the model — no client-side implementation needed.

Server Tools vs Plugins vs User-Defined Tools

	Server Tools	Plugins	User-Defined Tools
Who decides to use it	The model	Always runs	The model
Who executes it	OpenRouter	OpenRouter	Your application
Call frequency	0 to N times per request	Once per request	0 to N times per request
Specified via	`tools` array	`plugins` array	`tools` array
Type prefix	`openrouter:*`	N/A	`function`

Server tools are tools the model can invoke zero or more times during a request. OpenRouter handles execution transparently. Plugins inject or mutate a request or response to add functionality (e.g. response healing, PDF parsing). They always run once when enabled. User-defined tools are standard function-calling tools where the model suggests a call and your application executes it.

Available Server Tools

Tool	Type	Description
Web Search	`openrouter:web_search`	Search the web for current information
Datetime	`openrouter:datetime`	Get the current date and time
Image Generation	`openrouter:image_generation`	Generate images from text prompts
Web Fetch	`openrouter:web_fetch`	Fetch and extract content from URLs
Apply Patch	`openrouter:apply_patch`	Propose file edits via V4A diff patches (Responses API only)
Shell	`openrouter:shell`	Run commands in a hosted, sandboxed shell (Responses API only)
Files	`openrouter:files`	Read, write, edit, and list workspace files via the Files API
Fusion	`openrouter:fusion`	Run a panel of models and a judge for multi-model analysis
Advisor	`openrouter:advisor`	Consult a stronger model for guidance mid-generation
Subagent	`openrouter:subagent`	Delegate self-contained tasks to a smaller, faster worker model
Search Models	`openrouter:experimental__search_models`	Search and filter the OpenRouter model catalog

How Server Tools Work

You include one or more server tools in the tools array of your API request.
The model decides whether and when to call each server tool based on the user’s prompt.
OpenRouter intercepts the tool call, executes it server-side, and returns the result to the model.
The model uses the result to formulate its response. It may call the tool again if needed.

Server tools work alongside your own user-defined tools — you can include both in the same request.

Tool Call Limits

Every request that uses server tools runs an agent loop with a step budget. Each tool call the model makes (a web search, an image generation, etc.) consumes one step; when the budget is exhausted, the model is asked to produce its final answer with the context gathered so far. Two top-level request fields control the outer loop (both are siblings of messages and tools):

Field	Default	Max	Behavior
`max_tool_calls`	`30`	`30`	Total server-tool steps allowed for the request, across all server tools
`stop_server_tools_when`	—	—	Array of stop conditions (step count, spend cap, and more). When set, it overrides `max_tool_calls`

Tools that run their own inner agent loops have separate, per-tool budgets configured via the tool’s parameters:

Tool	Parameter	Default	Max
Fusion	`max_tool_calls`	`8`	`16`
Advisor	`max_tool_calls`	Provider default	`25`
Subagent	`max_tool_calls`	Provider default	`25`

These inner budgets bound each panelist, advisor, or worker model’s own tool loop and are independent of the outer request budget.

Quick Start

Add server tools to the tools array using the openrouter: type prefix:

Combining with User-Defined Tools

Server tools and user-defined tools can be used in the same request:

{
  "model": "openai/gpt-5.2",
  "messages": [...],
  "tools": [
    { "type": "openrouter:web_search", "parameters": { "max_results": 3 } },
    { "type": "openrouter:datetime" },
    {
      "type": "function",
      "function": {
        "name": "get_stock_price",
        "description": "Get the current stock price for a ticker symbol",
        "parameters": {
          "type": "object",
          "properties": {
            "ticker": { "type": "string" }
          },
          "required": ["ticker"]
        }
      }
    }
  ]
}

The model can call any combination of server tools and user-defined tools. OpenRouter executes the server tools automatically, while your application handles the user-defined tool calls as usual.

Usage Tracking

Server tool usage is tracked in the response usage object:

{
  "usage": {
    "input_tokens": 105,
    "output_tokens": 250,
    "server_tool_use": {
      "web_search_requests": 2
    }
  }
}

Next Steps

Web Search — Search the web for real-time information
Datetime — Get the current date and time
Image Generation — Generate images from text prompts
Web Fetch — Fetch and extract content from URLs
Apply Patch — Propose file edits via V4A diffs
Shell — Run commands in a hosted, sandboxed shell
Files — Read, write, edit, and list workspace files
Fusion — Run a panel of models and a judge for multi-model analysis
Advisor — Consult a stronger model for guidance mid-generation
Subagent — Delegate self-contained tasks to a smaller, faster worker model
Search Models — Search and filter the OpenRouter model catalog
Tool Calling — Learn about user-defined tool calling

Overview

Models & Routing

Features

Privacy

Best Practices

Community

Server Tools vs Plugins vs User-Defined Tools

Available Server Tools

How Server Tools Work

Tool Call Limits

Quick Start

Combining with User-Defined Tools

Usage Tracking

Next Steps

​Server Tools vs Plugins vs User-Defined Tools

​Available Server Tools

​How Server Tools Work

​Tool Call Limits

​Quick Start

​Combining with User-Defined Tools

​Usage Tracking

​Next Steps

Server Tools vs Plugins vs User-Defined Tools

Available Server Tools

How Server Tools Work

Tool Call Limits

Quick Start

Combining with User-Defined Tools

Usage Tracking

Next Steps