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.

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

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:

Named advisors

Instead of a single advisor, you can configure a roster of named profiles in parameters.advisors. Each profile has a required name plus its own optional model, instructions, and the other advisor fields. The executor model still sees one advisor tool and selects a profile by passing its name:

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

The model then consults a specific profile:

1
{ "name": "reviewer", "prompt": "Review this concurrency approach." }

A selected profile’s config takes precedence over the request-wide parameters for that call. Profile names must be unique within the roster — a duplicate name fails the request with a 400. When a roster is configured, the model must pass a name that matches one of the profiles; an unknown or missing name returns an error result listing the valid names.

The single-advisor form (no advisors roster) continues to work unchanged — pass model/instructions directly in parameters and the model calls the tool with just a prompt.

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
}

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