Advisor

The openrouter:advisor server tool lets a model consult a higher-intelligence advisor model mid-generation. When your model hits a decision point — before committing to an approach, when it’s stuck, or before declaring a task done — it invokes the tool with a prompt. The advisor model thinks, returns its guidance as the tool result, and your model continues, informed by the advice.

Unlike a fixed model pairing, the advisor can be any OpenRouter model, and it can optionally run as a sub-agent with its own tools (for example openrouter:web_search). The tool returns the advisor model’s response directly as the tool result — your model writes the final answer.

You can offer the model a choice of several named advisors by including multiple openrouter:advisor entries in the tools array — one per advisor (see Multiple advisors). At most one entry may omit name to act as the default advisor.

Each advisor also remembers its own prior consultations across requests when you replay the conversation transcript (see Cross-request memory), and the tool is available on the Chat Completions, Responses, and Anthropic Messages APIs (see Anthropic Messages API).

Quick start

1
const response = await fetch('https://openrouter.ai/api/v1/chat/completions', {
2
  method: 'POST',
3
  headers: {
4
    Authorization: 'Bearer {{API_KEY_REF}}',
5
    'Content-Type': 'application/json',
6
  },
7
  body: JSON.stringify({
8
    model: '{{MODEL}}',
9
    messages: [
10
      {
11
        role: 'user',
12
        content: 'Build a concurrent worker pool in Go with graceful shutdown.',
13
      },
14
    ],
15
    tools: [
16
      {
17
        type: 'openrouter:advisor',
18
        parameters: { model: '~anthropic/claude-opus-latest' },
19
      },
20
    ],
21
  }),
22
});
23
24
const data = await response.json();
25
console.log(data.choices[0].message.content);

Choosing the advisor model

The advisor model is resolved with the following precedence:

1. parameters.model on the tool definition, if set.
2. The model argument the executor passes in the tool call, if the definition does not fix one.
3. The model from the outer API request, as a fallback.

This lets you either pin the advisor model up front (parameters.model) or let the executing model pick it per call. The advisor tool itself can never be the advisor model.

When does the model invoke it?

The tool’s description steers the model to consult the advisor before substantive work, when it’s stuck, or before declaring a task done — not for trivial steps a single model can resolve directly. To force a consultation on every request, set tool_choice: "required" (with multiple advisors this forces the first entry — see Multiple advisors).

Parameters

Pass an optional parameters object on the tool entry:

1
{
2
  "tools": [
3
    {
4
      "type": "openrouter:advisor",
5
      "parameters": {
6
        "model": "~anthropic/claude-opus-latest",
7
        "instructions": "You are a senior staff engineer. Be decisive.",
8
        "tools": [{ "type": "openrouter:web_search" }],
9
        "forward_transcript": false
10
      }
11
    }
12
  ]
13
}

Tool-call arguments

When invoking the tool, the model passes:

Multiple advisors

To offer the model a choice of advisors, include multiple openrouter:advisor entries in the tools array — one per advisor. Give each its own name (plus its own model, instructions, and the other advisor fields); the model sees one distinct tool per named advisor and calls whichever fits the task:

1
{
2
  "tools": [
3
    {
4
      "type": "openrouter:advisor",
5
      "parameters": {
6
        "name": "reviewer",
7
        "model": "~anthropic/claude-opus-latest",
8
        "instructions": "You are a critical code reviewer. Find the flaws."
9
      }
10
    },
11
    {
12
      "type": "openrouter:advisor",
13
      "parameters": {
14
        "name": "architect",
15
        "model": "~openai/gpt-latest",
16
        "instructions": "You are a systems architect. Think about scale."
17
      }
18
    }
19
  ]
20
}

Rules for advisor entries:

• At most one entry may omit name — it becomes the default advisor. Two or more unnamed advisor entries fail the request with a 400: “Only one advisor tool can serve as the default. All other advisor tools must have a name defined.”
• Names must be unique across entries (compared after trimming whitespace). A duplicate name fails the request with a 400.
• Names allow letters, digits, spaces, underscores, and dashes (e.g. "Lead Architect"), are trimmed, and must be 1–64 characters.

A single advisor is just one entry — name it, or leave name off to keep it as the default. Each advisor’s result reports the model it consulted, so you can tell the advisors apart in the response.

Cross-request memory

Each advisor remembers its own prior prompt → advice exchanges across API requests in a conversation. When you send a follow-up request that replays the prior transcript — assistant messages with their advisor tool calls and results included, as returned by the API — the advisor sees its earlier consultations replayed into its context before the new prompt. Tell the advisor a fact in one request, and it can recall it in the next without the executor restating it.

This works on all three APIs; the only requirement is that you replay the advisor exchanges you received:

• Chat Completions: include the assistant message’s advisor tool_calls and the paired role: "tool" result messages from prior turns.
• Responses API: include the openrouter:advisor output items from prior responses in input, unchanged.
• Anthropic Messages API: include the assistant message’s advisor server_tool_use and advisor_tool_result content blocks from prior turns.

Memory is per advisor: in a multi-advisor setup, each advisor recalls only its own prior exchanges — a “reviewer” advisor never sees what the “architect” was told. There is no fixed limit on the number of replayed exchanges; if the history exceeds the advisor model’s context window, it is compressed with the middle-out transform, which trims the middle of the conversation and keeps the oldest and newest exchanges.

Memory applies to prompt-mode consultations. With forward_transcript: true the advisor already sees the full parent conversation, so prior exchanges are not separately replayed.

Streaming advice

By default the advice arrives only once the advisor has finished — as a single tool result. Set parameters.stream to true to have the advice stream out incrementally as the advisor model produces it:

1
{
2
  "tools": [
3
    {
4
      "type": "openrouter:advisor",
5
      "parameters": {
6
        "model": "~anthropic/claude-opus-latest",
7
        "stream": true
8
      }
9
    }
10
  ]
11
}

In the Responses API, the advisor’s output item then emits response.output_text.delta events as the advice is generated, followed by a response.output_text.done and the completed item. The completed item still carries the full advice string, so consumers that don’t read the deltas are unaffected. stream can be set per advisor entry, so you can stream some advisors and not others.

The streamed deltas mirror how a normal assistant message streams text — the item_id on each delta is the advisor output item’s id.

Streaming has no effect on the Chat Completions API (the advice arrives only as the final tool result regardless of stream). Streaming the advice in the Anthropic Messages API is a planned fast-follow; today a Messages request behaves as if stream were false.

What the tool returns

On success the tool result contains the advice text and the model that produced it:

1
{
2
  "status": "ok",
3
  "model": "anthropic/claude-opus-4.8",
4
  "advice": "Use a channel-based coordination pattern. Close the input channel first, then wait on a WaitGroup to drain in-flight work before shutdown..."
5
}

On failure the result has status: "error" with a message; the calling model continues without the advice:

1
{
2
  "status": "error",
3
  "error": "Advisor call failed: ..."
4
}

Anthropic Messages API

On /api/v1/messages, request the advisor with the native Anthropic tool shape — and it works with any executor model, not just Anthropic ones:

1
{
2
  "model": "anthropic/claude-haiku-4.5",
3
  "max_tokens": 1024,
4
  "messages": [
5
    { "role": "user", "content": "Build a concurrent worker pool in Go with graceful shutdown." }
6
  ],
7
  "tools": [
8
    {
9
      "type": "advisor_20260301",
10
      "name": "advisor",
11
      "model": "~anthropic/claude-opus-latest"
12
    }
13
  ]
14
}

The response carries the advisor consultation as the official Anthropic block shapes — a server_tool_use block with name: "advisor" for the call, followed by an advisor_tool_result block with the advice:

1
{
2
  "content": [
3
    {
4
      "type": "server_tool_use",
5
      "id": "srvtoolu_01abc",
6
      "name": "advisor",
7
      "input": { "prompt": "..." }
8
    },
9
    {
10
      "type": "advisor_tool_result",
11
      "tool_use_id": "srvtoolu_01abc",
12
      "content": { "type": "advisor_result", "text": "Use a channel-based coordination pattern..." }
13
    },
14
    { "type": "text", "text": "..." }
15
  ]
16
}

Replay these blocks unchanged on the assistant message of follow-up requests for cross-request memory.

Notes on the native shape:

• model is the only advisor configuration the native shape carries. For instructions, sub-agent tools, forward_transcript, and the other parameters, use the openrouter:advisor form on Chat Completions or Responses.
• max_uses is not honored: consultations are capped per request by OpenRouter’s fixed limit, and a max_uses below that limit does not lower it. caching, allowed_callers, and defer_loading are also ignored.
• Forcing the advisor via tool_choice: { "type": "tool", "name": "advisor" } is supported.

Sub-agent tools

When you pass tools, the advisor runs as an agentic sub-agent over them before producing its advice — for example, giving the advisor openrouter:web_search lets it ground its guidance in fresh sources. The advisor’s tool use happens inside the tool call; only its final text is returned to your model.

Recursion protection

The advisor tool cannot invoke itself. Two guards enforce this:

• A self-reference check rejects an advisor entry inside the advisor’s own tools array (and rejects the advisor tool name as the advisor model).
• Each inner advisor call carries an x-openrouter-advisor-depth header; the advisor tool is stripped from any sub-call, so an advisor sub-agent can never re-enter the advisor.

Consultations are also capped per request to bound cost and latency.

Related

• Fusion server tool — multi-model deliberation
• Web Search server tool
• Web Fetch server tool