Docs / MCP tools

MCP tools

The agent drives a run through eight tools served by the AOS MCP server. They are the agent’s only way to change run state, and by design none of them can approve a gate, cancel a run, lower a tier, extend a budget, or record a test run: those belong to the human and to the hooks. This page lists each tool’s inputs, results, and errors.

In Claude Code the plugin registers the server as aos, so the tools appear as mcp__plugin_aos_aos__<tool>, for example mcp__plugin_aos_aos__aos_run_start. Outside the plugin, aos mcp serves the same tools over stdio; see the CLI reference.

ToolPurposeChanges the run
aos_run_startStart a run for one piece of workcreates it
aos_statusShow stage, gate, gaps, and budgetno
aos_gate_checkEvaluate the current gate nowlogs the evaluation
aos_stage_advancePass the gate and enter the next stageyes
aos_task_addAdd a task to the current stageyes
aos_task_completeClose a taskyes
aos_evidence_recordRecord claimed evidenceyes
aos_request_approvalAsk the human to decide a human gateyes

Conventions

runId is optional. Every tool except aos_run_start takes a runId, and it defaults to the run this server started. Each host session runs its own server, so that is the session’s run. An explicit runId always wins. A server that has not started a run in its lifetime (for example after Claude Code restarts and resumes a session) has no default, and a call without runId fails with:

invalid: no run was started in this session, so pass the runId that aos_run_start returned (a session-start note also names it).

The SessionStart hook names the run id after a resume, so the agent can pass it.

Arguments are validated against each tool’s JSON Schema before anything runs. Unknown fields are rejected. Text fields are trimmed, and length limits apply after trimming.

Results come back as JSON, both as a text content block and as structuredContent.

Errors come back as tool errors (isError: true) whose text starts with a code:

CodeMeaning
invalid:The arguments are wrong: schema violations, unknown task or evidence ids, a line that does not exist, a request on a rule gate. Fix the call.
not_found:No run with that id under the repository.
refused:The call is well formed but not allowed: lowering a tier, a tier the pack does not define, evidence from outside the repository or under .aos/ or .git/, any change to a completed or cancelled run, or a run that kept changing while the call ran.
internal:Something else failed, such as a pack that does not load or git failing. aos doctor usually explains it.

A completed or cancelled run accepts only aos_status. Any other call is refused with Run <id> is <status>; only aos_status works on it. Start a new run with aos_run_start for further work.

Writes are safe against concurrent writers (a hook observing an edit, the human’s CLI, another tool call). Each call re-checks its plan under the run’s lock and re-plans up to three times. A run that keeps moving is refused with The run changed while this call ran; call aos_status and try again.

aos_run_start

Start a run. The pack proposes a tier from the brief; the agent should tell the human the tier and the reason before starting work.

InputTypeRequiredNotes
briefstringyesThe user’s request in their words, 1 to 8,000 characters.
tierspike, bounded, or architecturalnoAsk for a higher tier than proposed. A request can raise the tier, never lower it.
Result fieldMeaning
runIdThe new run’s id (a ULID).
tier, tierReasonThe tier and why, for example no tier rule matched; pack default is bounded.
stagesThe tier’s stage names, in order.
stageThe first stage.
instructionsThe first stage’s instructions (markdown).
noticeA line for the agent: the tier and reason, and that the session binds when the call returns.

The session is bound to the run by the PostToolUse hook after this call returns, not by the server; see sessions and binding.

Refusals:

  • refused: Lowering the proposed tier (<tier>: <reason>) requires a human.
  • refused: The <tier> tier is not available in this version of AOS (<why>). Ask the human how to proceed.

aos_status

Read-only. Works on active, completed, and cancelled runs.

InputTypeRequired
runIdstringno
Result fieldMeaning
runId, status, tier, stage, stagesWhere the run stands.
gateThe current stage’s gate evaluated now: stage, verdict (pending, pass, or fail), gaps, fingerprint, weakFreshness.
iterations{ used, limit } for the Stop loop’s budget.
summaryA short text summary of the run. The SessionStart hook injects the same text plus a Run id: line and, once the gate passes with a later stage left, the reminder to call aos_stage_advance.

Each gap has kind (missing, stale, or failed), who (agent or human), requirement (for example command:test, review, approval, tasks:t2, stage:verify), and text, an instruction to act on.

aos_gate_check

Evaluate the current stage’s gate now and record the evaluation in the log.

InputTypeRequired
runIdstringno
Result fieldMeaning
gateThe gate result, as in aos_status.
messagenull when the gate passes; otherwise the gaps as text, starting AOS: advance blocked: <stage> gate <verdict>.

aos_stage_advance

Pass the current gate and enter the next stage. If the gate does not pass, nothing moves and the gaps come back. The evaluation and the move land in one append, re-checked under the lock, so a task or request added meanwhile cannot be skipped.

InputTypeRequired
runIdstringno
Result fieldMeaning
advancedtrue if the run moved on or completed.
completedtrue if that was the last stage and the run is now complete.
gateThe gate result for the stage that was evaluated.
stageThe run’s stage after the call: the next stage, or the same one if it did not move.
instructionsThe new stage’s instructions, or null if it did not move or the run completed.
messagenull on success; otherwise the gaps as text, starting AOS: advance blocked:.

aos_task_add

Add a task to the current stage. A gate with tasks: all stays open until every task in its stage is completed.

InputTypeRequiredNotes
runIdstringno
titlestringyesWhat the task delivers, 1 to 500 characters.

Result: { task, stage }, where task is an id such as t1. Ids count across the whole run.

aos_task_complete

Mark a task in the current stage completed.

InputTypeRequiredNotes
runIdstringno
taskstringyesThe id from aos_task_add.
evidencestring arraynoUp to 50 evidence ids from aos_evidence_record that back the task. Every id must exist in the run.

Result: { task, open }, where open is how many other tasks in the stage are still open.

Errors (invalid): no such task, the task is already completed, the task belongs to another stage, or an evidence id is unknown.

aos_evidence_record

Record claimed evidence: the agent’s own account, kept in the log. Provenance is always claimed here; there is no provenance input. Test runs cannot be recorded through this tool: the hooks observe them.

InputTypeRequired forNotes
runIdstring
kindartifact, citation, review, or skillevery kindEach kind accepts exactly its own fields.
pathstringartifact, citationA file inside the repository, outside .aos/ and .git/. Symlinks are resolved before the check.
lineinteger, 1 or morecitationMust exist in the file.
notestringcitation (optional)What the cited line shows, up to 2,000 characters.
statusapproved, rejected, or needs-revisionreviewThe reviewer’s verdict, reported honestly.
feedbackstringreviewThe reviewer’s feedback, 1 to 8,000 characters. Required even for an approval.
reviewerstringreviewWho reviewed, such as a reviewing subagent’s name, up to 200 characters.
skillstringskillThe skill’s name, such as superpowers:brainstorming, up to 200 characters.

Result: { evidenceId, fingerprint }. The fingerprint is the tree the evidence belongs to; any change to the tree makes it stale for requirements with fresh: true.

An artifact records the file’s SHA-256. Files under 1 MiB are also copied into the run’s artifacts/ directory, unless git ignores them: an ignored file is often a secret, and a copy would outlive it. When git cannot confirm a file is not ignored, it is treated as ignored.

Refusals and errors include refused: <path> is outside the repository at <root>; evidence must come from inside it., refused: <path> is under .aos/, which holds AOS's own records and cannot be evidence., and invalid: <path> has <n> lines; line <line> does not exist.

aos_request_approval

Ask the human to approve the current stage. The agent should present the design, or the spike’s question and probe, in chat first, then call this, pass on the returned instructions, and end its turn.

InputTypeRequiredNotes
runIdstringno
summarystringyesWhat the human is approving, 1 to 4,000 characters. aos approve shows it to the human.
Result fieldMeaning
requestThe request id the human’s decision will be pinned to.
stageThe stage being decided.
instructionsFor the agent to relay, for example: Ask the human to run, in their own terminal: aos approve <run> design --root "/path/to/greeter". Then stop and wait; do not run it yourself.

A new request replaces any earlier undecided one for the stage; only the latest request since the stage was entered can be decided. On a rule gate the call fails with invalid: The <stage> gate is decided by rules, not by a human. Call aos_gate_check to see what it needs.

View this page's source on GitHub