MCP endpoints¶
Polaris speaks MCP (Model Context Protocol), so any MCP client (Claude, an agent framework, your own tooling) can work with a brain. There are three servers:
| Server | Where | For | Credential |
|---|---|---|---|
| Advisor | https://<host>/v1/mcp |
Grounded, cite-then-verified answers from a published brain | A key with advisor:read, or a tenant user's access token |
| Questions Framework | https://<host>/v1/mcp/questions |
The Questions lifecycle: read, propose, draft, eval, approve, certify | A key with at least one Questions Framework scope |
| Operator (stdio) | a local process | Polaris developers driving the whole platform | POLARIS_MCP_API_KEY with mcp:invoke |
The Advisor endpoint is the companion to the OpenAI-compatible endpoint: same Advisor, same API keys, a second transport.
Advisor endpoint¶
- Your key selects the brain. Each API key is bound to one brain, so one URL serves the brain your key belongs to. There is no path parameter.
<host>is wherever the capability gateway is published. Locally that'slocalhost:8088. The reference deployment fronts the gateway with nginx behind a Tailscale Funnel, so/v1/mcpis served at the tailnet hostname. See Edge & Tailscale.- It can't change the brain's knowledge. It exposes only the Advisor's four tools (below). It is not strictly read-only, though: every call writes an audit row, and when the Advisor asks a follow-up question it stores the paused route (in Redis, for 30 minutes) so your reply can resume it.
- It is separate from the local operator server used by Polaris developers.
Auth¶
Send your key as a bearer token:
The credential is a long-lived Polaris API key (sk-polaris-…) carrying the advisor:read
scope: the same key that works on /chat/completions. A tenant user's Polaris access token also
works (the brain comes from the token). A platform admin's token has no single brain, so it can't
connect. A key may carry other scopes too; this endpoint only needs advisor:read.
Auth failures reject the connection with an HTTP status and an OAuth-style body,
{"error": "…", "error_description": "…"}:
| HTTP | error |
Meaning |
|---|---|---|
| 401 | invalid_token |
Missing, unknown or revoked credential. |
| 403 | insufficient_scope |
A valid key without the advisor:read scope. |
Revocation takes effect on the next request: a revoked key stops connecting at once.
The brain needs its own OpenRouter key¶
A brain with no OpenRouter key of its own has no Advisor. Every answer and retrieve call then
returns no answer: the envelope's guardrail is
{"status": "block", "rule_id": "advisor.openrouter_key_required", "message": "This brain's Advisor needs an OpenRouter key. An admin can add one under Settings → Model providers."}
and the text content says the same. The fix is a brain admin's, not your agent's: an Admin adds
the key under Settings → Model providers.
Tools¶
| Tool | Input | Returns |
|---|---|---|
answer |
query: string, topic_ids?: string[], and to reply to a follow-up: route_token?: string, question_id?: string, slots?: {name: string}, reply?: string |
A grounded, cite-then-verified answer envelope: result, citations, confidence, guardrail, brain_version. Or, when the Advisor must ask first, needs_input (see Follow-up questions). |
retrieve |
query: string, topic_ids?: string[] |
The scope-filtered source passages that ground an answer: citations, no synthesis. Use it when your agent wants the raw evidence. It never asks a follow-up. |
topic_cards |
none | The subjects this brain knows it can be asked about. Each card has an id to pass back as topic_ids. |
read_wiki |
entity?: string |
Browse the published brain as articles. Omit entity for the index (categories and titles); pass a title for that article. |
Follow-up questions (needs_input)¶
Before it answers, the Advisor works out whether a question is one of the brain's published
Questions, and whether it knows the facts that Question's answer turns on (its slots). If it
needs something from the person, answer returns a follow-up instead of an answer. This happens
only where the brain has the advisor_question_routing flag on; otherwise answer always answers.
The design is in Advisor question routing.
A follow-up sets structuredContent.needs_input, and result holds the question as plain text.
needs_input.reason is one of:
choose_question: the Advisor isn't sure which Question is meant.candidateslists them (question_id,text,probability).slots: the Advisor knows the Question (question_id) but needs facts.slotslists each one to ask:name,type,ask_text,required, andvalues(the allowed values; empty for free text).messagemay say why, for example that a required fact was answered "I don't know".
Ask the person. Don't answer for them. Then call answer again with the same query and:
route_token:needs_input.token, always;question_id: the chosen candidate'squestion_id, or"none"for none of them;slots: slot name → the person's own words, "I don't know" included;- or
reply: what the person said, verbatim, if you didn't map it yourself.
slots, question_id or reply without route_token is refused with an error result,
{"error": …, "code": "route_token_required", "remedy": …}. A route allows at most three replies
and expires after 30 minutes. If it has expired, the Advisor says so and asks the person to ask
again.
A worked round trip¶
1. Ask. The question could be one of two Questions:
{
"result": "Which of these do you mean?\n1. Adverse action notice for a declined consumer credit application\n2. Adverse action notice when a credit report contributed to the decline\nOr none of these.",
"citations": [],
"confidence": null,
"guardrail": { "status": "pass", "rule_id": null, "message": null },
"brain_version": "147676ad69c2…",
"needs_input": {
"reason": "choose_question",
"token": "u2Q8m0kXr4V…",
"question_id": null,
"candidates": [
{ "question_id": "Q-dee-48", "text": "Adverse action notice for a declined consumer credit application", "probability": 0.52 },
{ "question_id": "Q-fcra-615a", "text": "Adverse action notice when a credit report contributed to the decline", "probability": 0.31 }
],
"slots": [],
"message": ""
}
}
2. Choose. The person picks the first one:
{ "name": "answer",
"arguments": { "query": "What notices do we owe when we decline someone?",
"route_token": "u2Q8m0kXr4V…", "question_id": "Q-dee-48" } }
The Advisor now needs a fact the answer turns on:
{
"result": "Before I answer, I need to know:\n- Is the credit for personal, family or household use, or for a business? (consumer, business)",
"citations": [],
"confidence": null,
"needs_input": {
"reason": "slots",
"token": "u2Q8m0kXr4V…",
"question_id": "Q-dee-48",
"candidates": [],
"slots": [
{ "name": "credit_purpose", "type": "credit_purpose",
"ask_text": "Is the credit for personal, family or household use, or for a business?",
"required": true, "values": ["consumer", "business"] }
],
"message": ""
}
}
3. Fill the slot. Pass the person's own words:
{ "name": "answer",
"arguments": { "query": "What notices do we owe when we decline someone?",
"route_token": "u2Q8m0kXr4V…", "slots": { "credit_purpose": "consumer" } } }
4. The answer. No needs_input; the answer ends with a note saying which facts it used:
{
"result": "You must send the applicant an adverse action notice within 30 days … (12 CFR 1002.9(a)(1)).\n\nThis answer is based on:\n- You told me: credit purpose: consumer.",
"citations": [ { "source_id": "12 CFR Part 1002 — Equal Credit Opportunity Act (Regulation B)", "kind": "passage", "…": "…" } ],
"confidence": 0.82,
"guardrail": { "status": "pass", "rule_id": null, "message": null },
"brain_version": "147676ad69c2…"
}
The note lists the facts the person told the Advisor, defaults it assumed ("Assumed, because it wasn't known: …"), and facts it hedged over ("Not known, so the answer covers each case: …"). Facts the question itself stated need no note.
The text content mirrors this: for a follow-up it is the question plus one line telling your agent which arguments to send back.
Scoping a question to a subject¶
A question rarely names the citations it needs. "What notices do we owe when we turn someone down?"
never says § 1002.9 or 15 U.S.C. § 1681m(a), and similarity search can't bridge that gap,
because a provision's text does not repeat its own citation. Asking the index for
12 CFR 1026.4 returns citation fragments, not the rule.
A topic card closes the gap. A curator names a kind of question and the provisions its answers turn on. Passing the card's id supplies those provisions' verbatim text by exact key: the one retrieval path that can't near-miss.
Two calls. List the catalog, then scope:
cards = (await client.call_tool("topic_cards", {})).structured_content
for c in cards["topics"]:
print(c["id"], "—", c["label"])
print(" ", c["covers"]) # the fact patterns, in the words people ask in
result = await client.call_tool("answer", {
"query": "We declined an applicant because their credit score was below our threshold. "
"What notices do we owe, and how specific must the reasons be?",
"topic_ids": ["denying-an-application-the-notices-we-owe"],
})
Each card returns:
| Field | Meaning |
|---|---|
id |
Pass this back as an entry in topic_ids. |
label |
Short name: what a reader picks from a list. |
covers |
The fact patterns it covers, written in the asker's words rather than the law's. Match your question against this, not against the label. |
anchors |
The citation keys this subject's answers turn on. |
The operator server's list_topic_cards also reports unsupportable_anchors (how many anchors the
corpus can't supply). The Advisor endpoint's topic_cards doesn't.
Rules worth knowing:
- Optional; omitting it changes nothing. An unscoped
answerretrieves exactly as it always has. - Keep it to one or two cards. A question spanning more than two subjects is usually two questions.
- An unknown id is ignored, not an error. A stale id from a cached catalog degrades to an unscoped answer.
- An empty catalog is normal.
topic_cardsreturns no topics for a brain whose curator hasn't written any, andanswerbehaves as before. - Scope is recorded. The audit row for a scoped answer carries the card ids that routed it.
Match on
covers, not onlabel. Labels are short by design;coversis the sentence written to be matched against a real question.
The citation model¶
Every answer/retrieve citation is a navigable entry point back into the knowledge base, not
just a label. Each entry in citations[]:
| Field | Meaning |
|---|---|
source_id |
The cited source (a document title or entity name). |
kind |
passage (verbatim source chunk; strongest evidence) or entity (graph/entity summary; contextual). |
quote |
The verbatim supporting span from the source (the sentence that supports the claim, not a prefix). |
locator |
A precise in-document locator (e.g. §1026.2) when the extractor captured one. |
score |
Retrieval relevance of the source, 0–1. |
verified / verification |
verification.method is entailment (LLM judge), lexical, lexical_fallback (judge errored, so unconfirmed) or unverified, plus a score. |
provenance |
Hard provenance: source_doc_pk, doc_title, origin_url (the source document's root URL), jurisdiction. |
wiki |
Deep links into the published Wiki: [{entity, ref}] where ref is GET /v1/brains/{brain_id}/wiki/{entity}. Follow these (or call read_wiki(entity)) to pull the full article. |
concept_refs |
Entity names for graph traversal from the answer into the knowledge base (feed to read_wiki / retrieve). |
The envelope also carries confidence (0–1, weighted by per-citation verification and retrieval
strength) and guardrail (pass / disclaim / block). Treat a disclaim or low-confidence
answer as "not grounded", even if prose is returned.
Two channels per result: rendered text and structured citations¶
answer and retrieve return both MCP content channels, so each consumer gets the right
shape:
content(text): the answer followed by a rendered## Sourcesblock: one numbered entry per citation with the verbatim quote,[source](origin_url), and[wiki: entity](ref)deep links. Labels are cleaned (single-line) and de-duplicated. Interactive harnesses hand this text to a summarizing model, which often drops raw JSON; pre-rendering the sources means even a small local model can carry the provenance into its prose.structuredContent: the full envelope (result, enrichedcitations[],confidence,guardrail,brain_version, andneeds_inputwhen set). Programmatic consumers read this directly. (The structured list is the raw pipeline output: it is not de-duplicated and labels are not cleaned; do that yourself if you render it.)
How an agent should consume citations¶
- Programmatic integrations (recommended): read
structuredContent, ignore the prose. Iteratecitations[]:origin_urlto link the evidence document,quoteto quote it,wiki[].ref/read_wiki(entity)to expand a concept,concept_refsto traverse the graph,verification/scoreto weight or filter. Gate onconfidenceandguardrail. - Interactive harnesses (a model summarizes the tool result): the model decides what to show.
A summarizing model, especially a small local one, often rewrites the answer and drops the
citations. That is the client's behaviour, not a Polaris omission. Tell the agent to reproduce
the
## Sourcesblock verbatim (see the OpenCode guide for a ready-made rule), and prefer a stronger model when citations matter.
"Good answer, no citations" is almost always the model, not the endpoint. Check with a raw MCP
tools/call: if the result carriescitations[]and a## Sourcesblock, the endpoint is fine and the consuming model is dropping them.
Connect a client¶
Claude Code / Claude Desktop: add it as a remote HTTP MCP server:
claude mcp add --transport http polaris-advisor https://<host>/v1/mcp \
--header "Authorization: Bearer sk-polaris-…"
Then /mcp lists polaris-advisor with its tools. Ask a question in plain language and the client
calls answer. To scope a question, ask the client to call topic_cards first and pass the
matching id.
Any MCP SDK (for example Python fastmcp):
from fastmcp import Client
from fastmcp.client.transports import StreamableHttpTransport
transport = StreamableHttpTransport(
url="https://<host>/v1/mcp",
headers={"Authorization": "Bearer sk-polaris-…"},
)
async with Client(transport) as client:
tools = await client.list_tools() # answer, retrieve, topic_cards, read_wiki
query = "Do I need a CA lender license?"
result = await client.call_tool("answer", {"query": query})
env = result.structured_content # the full envelope: read this, not prose
while env.get("needs_input"): # the Advisor asks before it answers
ni = env["needs_input"]
print(env["result"]) # the question, as text
args = {"query": query, "route_token": ni["token"],
"reply": input("> ")} # or question_id / slots, if you mapped it
env = (await client.call_tool("answer", args)).structured_content
print(env["result"], "\n")
if env["guardrail"]["status"] != "pass" or (env["confidence"] or 0) < 0.5:
print("not well-grounded") # gate on grounding before trusting it
for c in env["citations"]:
prov = c.get("provenance") or {}
print(f"- [{c['kind']}] {c['source_id']} ({prov.get('origin_url')})")
print(f" “{c['quote']}”")
Managing keys¶
Keys are created and revoked exactly as for the completions endpoint: from the web app
(Settings → API keys, raw key shown once), over REST (POST/GET/DELETE
/v1/brains/{brain_id}/api-keys), or with the CLI (bb apikey mint|list|revoke). See
Managing keys and
Access, flags and scopes. One key with advisor:read works on
both MCP and completions.
Questions Framework over MCP¶
The same Questions Framework lifecycle as the developer REST API, as MCP tools for an agent.
Connect¶
claude mcp add --transport http polaris-questions https://<host>/v1/mcp/questions \
--header "Authorization: Bearer sk-polaris-…"
- Keys only. The endpoint accepts a bearer
sk-polaris-…key that carries at least one Questions Framework scope:questions:read,questions:write,eval:run,eval:submit,grades:submit,answer_key:approve,certification:sign_off,questions:publishorslots:write. A signed-in session's access token is not accepted. - Auth failures reject the connection:
401 invalid_tokenfor a missing, unknown or revoked key (checked on every request, so a revoked key stops at once), and403 insufficient_scopefor a valid key with no Questions Framework scope. Theerror_descriptionnames the scopes that would do. - One brain. The key's brain is the only brain. Tools take an optional
brain_id; omit it. Naming another brain is refused withcode: brain_forbidden. - Flag. Every tool call is refused with
code: feature_disabledunless the brain hasqf_developer_apiandquestion_store_dbon.update_slotsandpublish_question_versionalso needquestion_slot_editing;certification_statusandsign_off_certificationalso needquestions_workspace. A platform admin turns flags on; see Access, flags and scopes. - Who acts. A tool call acts as the key's actor: the person who minted it over REST, or the
--actorof a key minted withbb apikey mint. Every write is attributed to that actor, and Curator acts record the key's id in the audit log.
Tools¶
Each tool checks its own scope. A refusal is a normal tool result,
{"error": "…", "code": "…", "remedy": "…"}, so your agent can branch on code. The autonomy class
says what a tool may do without a person (see Autonomy classes).
| Tool | Scope | Role | Class | What it does |
|---|---|---|---|---|
list_questions |
questions:read |
any | A0 | The brain's Questions; include_drafts, topic narrow it. |
get_question |
questions:read |
any | A0 | One Question and its Answer Keys. The rubric only for a Curator or Admin key (rubric_visible). |
get_slots |
questions:read |
any | A0 | A Question's slots, published and draft, with each binding. |
list_slot_types |
questions:read |
any | A0 | The slot types a binding may use; include_proposed adds the brain's proposed ones. |
question_standing |
questions:read |
any | A0 | Standing over time, each point with its comparability tuple. |
certified_bindings |
questions:read |
any | A0 | What is certified at a brain version (default: the published one). |
certification_status |
questions:read |
any | A0 | Per binding: eligible, certified, reasons, and the certification_id to sign off. Needs questions_workspace. |
list_eval_runs |
questions:read |
any | A0 | Run rows, newest first (limit 1–500). Never answer text. |
get_eval_run |
questions:read |
any | A0 | One run and its results, with each result's id for grading. |
estimate_run |
eval:run |
any | A0 | What run_eval would cost; allowed: false with reason if it would be refused. Free. |
run_eval |
eval:run |
any | A1 | Live Advisor answers, judged, scored and stored. Spends the eval budget, checked before any model call. |
propose_question |
questions:write |
any | A2 | A draft Question in the brain's store. |
draft_answer_key |
questions:write |
any | A2 | A draft Answer Key for one binding, from expert_answer (free) or use_drafter=true (budgeted model calls). answer_key_id names it. |
propose_slot_type |
questions:write |
any | A2 | One of the brain's own slot types, proposed until someone else approves it. |
save_answer_key_draft |
questions:write |
Curator or Admin key | A2 | Save a whole rubric as a draft; returns validation. |
submit_answers |
eval:submit (+ eval:run to judge) |
any | A2 | Answers your system produced; Polaris scores them. |
request_approval |
questions:write or answer_key:approve |
any | A2 | Ask a named Curator or Admin to approve a draft. |
withdraw_approval |
questions:write or answer_key:approve |
any | A2 | Withdraw a request this key's actor made (an Admin key may withdraw any). |
update_slots |
slots:write |
Curator or Admin key | A2 | Edit a draft version's slots, or a published one's ask_text. dry_run available. |
submit_grade |
grades:submit |
Curator or Admin key | A3 | The key owner's own grade on one judged criterion. The actor must be an active Curator or Admin of the brain. |
approve_answer_key |
answer_key:approve |
Curator or Admin key | A3 | Approve a draft, so it scores and can certify. Same checks as the web app. |
approve_slot_type |
slots:write |
Curator or Admin key | A3 | Approve a proposed slot type; never the proposer's own. |
sign_off_certification |
certification:sign_off |
Curator or Admin key | A3 | Sign off an eligible certification. Needs questions_workspace. |
publish_question_version |
questions:publish |
Curator or Admin key | A3 | Start version N+1 of a published Question; bindings carry over as drafts. dry_run available. |
A Curator act with a Reader key is role_forbidden, whatever its scopes. A Curator act (approve,
sign off, publish a version, edit slots, save a rubric, approve a slot type) also needs the key's actor to be an active Curator or
Admin account of the key's brain, not an agent identity, checked at every call:
actor_not_a_curator (or not_a_person) otherwise. So a key minted by a platform operator can't
do Curator acts for a tenant, a key stops doing them once its actor is deactivated or demoted, and
a key minted with bb apikey mint must name a real Curator's login email as --actor to do them
(the CLI's default apikey@polaris is refused). withdraw_approval withdraws only a request the
key's own actor made, as over REST, whatever the key's role. A tool the key lacks the scope for is scope_forbidden.
Rubric detail (the rubric, per-criterion results, penalty wording) is returned only to a Curator or
Admin key that also has questions:read. Answer text is never returned, except that run_eval
returns it to Curator and Admin keys.
Lifecycle order¶
- Find or propose.
list_questions(or the Advisor's routing) to see what exists. If nothing covers what people ask,propose_question. - Draft.
list_slot_types(andpropose_slot_type/approve_slot_typefor a type the brain lacks), thendraft_answer_keyfor each binding, andsave_answer_key_draftto write its rubric. - Approve.
request_approval(a person decides in the web app), orapprove_answer_keywith a Curator or Admin key. Only an approved Answer Key certifies. - Evaluate.
estimate_run, thenrun_eval(ref="published"andjudge=trueto count toward certification). Orsubmit_answersfor answers your own system produced; those never certify. - Review.
list_eval_runs,get_eval_run,question_standing;submit_gradewhere a person has read the answer. - Certify.
certification_status, thensign_off_certificationwith a Curator or Admin key.certified_bindingsshows the result.
To change a published Question later: get_slots, then update_slots (ask text only) or
publish_question_version.
How scopes map¶
Internally, this endpoint binds each call to an operator identity with the key's Questions
Framework scopes, plus mcp:invoke, plus mcp:write when the key holds any write scope
(questions:write, eval:run, eval:submit, grades:submit or a Curator scope). It never grants
mcp:any-brain. You don't mint mcp:* scopes for this endpoint.
Operator (stdio) server¶
Polaris developers drive the full tool surface (Librarian, Scout, corpus health, the crawler,
certify/publish, the Questions Framework, …) from a local stdio MCP server registered in Claude
Code. It is not the customer surface above. The flow is documented in the repo cookbook:
cookbooks/MCP_USER_GUIDE.md. It is local by design: never expose it remotely. It writes
corpora.
Identity¶
There is no bearer header here: this is stdio, not HTTP, so there is no request to attach auth to.
The credential arrives at process launch, and is resolved once against the same api_key
table:
bb apikey mint --operator --brain-id calliope --actor you@example.com --label "claude-code"
export POLARIS_MCP_API_KEY='sk-polaris-…'
With a key, the session acts as that key's actor. A caller that passes a different actor is
refused rather than silently overwritten. The key's brain becomes the default, and every audit row
carries authenticated: true and the key id.
| Scope | Grants |
|---|---|
mcp:invoke |
Use the operator toolset at all. Required: an advisor:read key does not authenticate here. |
mcp:write |
Tools that change a corpus or a brain's Questions (autonomy class A2/A3), and the metered Questions Framework tools that spend the eval budget (question_check, question_check_compare, question_eval: scope_forbidden without it). Omit it with --read-only. |
mcp:any-brain |
Act on a brain other than the key's own. Without it, naming another brain is refused. |
questions:read |
The Questions Framework read tools. With a Curator or Admin role, rubric detail too. |
questions:write |
propose_question, request_approval. |
eval:run |
run_eval (spends the eval budget), and judging in submit_answers. |
eval:submit |
submit_answers. |
grades:submit |
submit_grade, as the key's own actor. |
answer_key:approve |
approve_answer_key (the key's actor is the approver), and request_approval. |
certification:sign_off, questions:publish, slots:write |
Curator acts on the developer REST API and the remote Questions Framework endpoint. A Curator or Admin key only. |
Add Questions Framework scopes at mint time with --scope, for example
bb apikey mint --operator --scope questions:read --scope eval:run …. The full scope reference is
Access, flags and scopes.
Without a key the server still runs, under weaker guards: writes need an explicit brain_id
and a named, non-placeholder actor. That actor is self-asserted, so every write result and
audit row records authenticated: false. Questions Framework tools that spend budget, submit
answers, request approvals or grade refuse an unauthenticated session (not_authenticated).
Call mcp_session before anything that writes, to see which mode you are in.
The credential is resolved once per process, so a key revoked mid-session keeps working until the server restarts.
Questions Framework tools¶
The operator server has list_questions, get_question, question_standing,
certified_bindings, run_eval, propose_question, submit_answers, request_approval and
submit_grade (from app/mcp/qf_tools.py), next to the older draft_question,
approve_answer_key, question_eval, match_question, question_spec and coverage.
- The brain comes from the key. Omit
brain_idand the tool acts on the key's brain. Another brain needsmcp:any-brain, and even then a tenant key never spends another tenant's budget or writes its Questions. - Writes need
mcp:writeas well as the tool's own scope. - Budgets.
run_evaland a judgedsubmit_answersare checked against the brain's monthly eval budget and run cap before any model call (budget_exceeded,run_cap_exceeded). The older A1 tools (question_check,question_check_compare,question_eval) are checked the same way, take amax_cost_usdceiling, needmcp:writeon a key, and their model calls are recorded against the monthly budget. - Coded errors. Every failure is
{"error": …, "code": …, "remedy"?: …}, for examplefeature_disabled,scope_forbidden,brain_forbidden,not_found,seed_unpinned,citations_missing. - Approval. On the operator server,
request_approvalonly asks; the named person approves in the web app (or with their ownanswer_key:approvekey andapprove_answer_key). - Lifecycle with
question_store_dbon:propose_question→draft_question(question_id=…)→request_approval→ the approver approves →run_eval→question_standing/certified_bindings.
The operator answer tool takes the same follow-up arguments as the Advisor's
(route_token, question_id, slots, reply).
Autonomy classes¶
Tools declare what they may do without a person, enforced by app/mcp/_autonomy.py. The rule:
an MCP default may never be more permissive than what the web app shows a person. Where the app
renders a choice, the tool must refuse, require an explicit parameter, or disclose the default it
applied.
| Class | Meaning | Gate |
|---|---|---|
| A0 | Read: no cost, no change | none |
| A1 | Metered: spends credits, quota or model calls | a budget or ceiling; spend always returned |
| A2 | Reversible write: changes the draft; git-revertible | identity; dry_run where it applies |
| A3 | Judgement write: records a curator's claim | a named person (the key's actor, or approved_by) |
| A4 | Irreversible: publishes or leaves the system | never automated |
The full tool inventory lives in the app/mcp/server.py module docstring, and a test keeps it in
step with what is registered.
Limits (current)¶
- The Advisor endpoint has four tools:
answer,retrieve,topic_cards,read_wiki. It can't change the brain's knowledge. - One brain per key (the key's brain); no cross-brain access on either remote endpoint.
- Grounded answers need a published version of the brain (
read_wikireports if there is none), and the brain's own OpenRouter key.