# MCP tools

Each run's agent session gets an MCP server named `andon`, started by the agent (`andon mcp`). Its tools are how a run
talks to the board: it asks you a question, shows a preview, records what it learned, and reports at the end of a turn.
In Claude Code they appear as `mcp__andon__<tool>`.

The server holds no credentials. A tool call goes to this machine's agent over 127.0.0.1 with the run's id, and the
agent writes to the board as the machine, for that run's card only.

Four sets of tools exist. A card's run gets the run tools; a conversation in the board's chat gets the chat tools; a
planning session gets the planning session tools; a coordinated workstream's coordinator gets the coordinator tools.
Every tool below, and the arguments of every run, planning session and coordinator tool, are checked against the code by
a test (`apps/agent/src/reference-docs.test.ts`).

## Run tools

An argument marked * is required.

| Tool | What it does | Arguments |
|---|---|---|
| `ask` | Ask the person a question on the board. The answer arrives as the run's next message, so the run ends its turn after asking. | `question`* |
| `report` | Once at the end of each turn: a short structured summary for the board, and the outcome that moves the card (`done`, `needs_review`, `blocked`, `parked`). `checked` names the card notes' checklist items the turn finished (by text or number); Andon ticks them in the notes. | `headline`*, `done`, `decisions`, `next`, `risks`, `outcome`, `verify`, `waiting_on`, `checked`, `issues` |
| `set_status_note` | Show a short progress line on the card (up to 280 characters). | `text`* |
| `note` | Append a short note to the card. | `text`* |
| `comment` | Comment in the card's Comments thread, as the machine. It mentions nobody: to get an answer, use `ask`. A run comments only on its own card; `reply_to` answers a comment in its thread. | `text`*, `card`, `reply_to` |
| `add_card` | Make a follow-up card, in this card's team and project unless another is named, with the default recipe. A named team or project the machine's owner can't see is refused as not found. | `title`*, `notes`, `team`, `project`, `column` (`inbox`, `backlog` or `next`) |
| `attach` | Attach a file from the workspace to the card, such as a screenshot. | `path`*, `caption` |
| `publish_output` | Publish a file from the workspace as a run output for review on the board. An `.html` file is shown as a page: one self-contained file of at most 5 MB. | `path`*, `label` |
| `step_done` | PR group runs: tick off one of the numbered issues in the prompt. | `item`*, `note` |
| `request_review` | Ask for an Andon code review of the card's open pull request. The review starts in its own session once this turn ends. | none |
| `preview` | Share a web server the run started as a preview link on the card, through the machine's tunnel. Only a port the run's own process listens on; the app gets only the cookies it set. Fails when previews are off. | `port`*, `label` |
| `preview_screen` | Show a native app live on the card: the iOS Simulator (`ios`), an Android emulator or device (`android`), or a macOS window (`window`) of an app the run built or started. | `target`*, `app`, `device`, `label` |
| `preview_capture` | Capture a PNG frame of a preview and save it on the card as an output. A web preview is loaded read-only in headless Chrome at the given size (default 1280 × 800). | `label`, `port`, `path`, `width`, `height` |
| `preview_element` | Name the element at a pixel of a captured web frame: its CSS path, tag, role, text and box. | `frame`, `x`*, `y`* |
| `stop_preview` | Close a preview and take its link off the card. | `port`* |
| `memory_search` | Search the team's active memory, ranked. | `query`*, `limit` (1 to 20) |
| `remember` | Record something the repository should remember: a proposed entry under `.andon/memory` on the run's branch, staged for its commit. At most 5 a run. Secrets, email addresses and home paths are refused. See the [file format](https://andon-docs.pages.dev/reference/andon-directory.md). | `kind`*, `title`*, `text`*, `evidence`*, `tags`, `paths`, `supersedes` |
| `knowledge` | Write or rewrite a knowledge note, `.andon/knowledge/<topic>.md`, staged for the commit. | `topic`*, `text`*, `title`, `tags`, `paths` |
| `review_result` | Code-review runs: report the review round once, at the end, with each finding, the visual findings on captured frames, the pushed commit, and up to 5 things to remember. | `verdict`* (`clean`, `fixed` or `blocked`), `findings`*, `head_sha`*, `visual_findings`, `memory`, `memory_conflicts` |
| `propose_steps` | Propose a workstream's steps for review on the board. Nothing is made until a person approves. | `steps`* |
| `propose_project` | Study runs: propose a new project with its cards, their order and the open questions. Nothing is made until a person accepts it. At most 30 cards. | `name`*, `cards`*, `description`, `questions` |
| `permission` | The permission prompt of a headless run. Claude Code calls it; a run never does. | `tool_name`*, `input`*, `tool_use_id` |

## Chat tools

The board's chat runs on a machine (when [`orchestrator`](https://andon-docs.pages.dev/reference/policy.md#subcommands) is on there) with only these tools. Each
acts for the person in the chat, within what they may see and do, and is audited as the chat's. The ones marked "asks first" never act: the person sees a
confirmation and their tap does it.

| Tool | What it does |
|---|---|
| `orch_overview` | The board at a glance: machines, active runs, what needs the person, workstreams. |
| `orch_list_cards` | Cards, filtered by column, team, project, group or text. |
| `orch_card` | One card in full: fields, notes, workspace, PR group, latest run, requests, outputs, links. |
| `orch_run_tail` | A run with more of its terminal output and its report. |
| `orch_machines` | Every machine of the org: online, capabilities, active and queued runs. |
| `orch_groups` | The PR groups, filtered by team, project and state. |
| `orch_group` | One PR group by name or id. |
| `orch_repo_memory` | What a team's repositories remember (their `.andon/` memory on the default branch). |
| `orch_open` | Open a card, team, project or group on the person's screen. |
| `orch_create_card` | Make a card as the person. It never starts a run. |
| `orch_plan_cards` | Add a feature planned in the chat as cards, in one call, once the person agrees to the plan: in order, in the Backlog, each card's notes naming the earlier cards it depends on. Cards that ship together come back for `orch_group_cards` to propose. |
| `orch_update_card` | Change a card's title, notes, team, project, recipe or priority. |
| `orch_move_card` | Move a card. Into Working starts a run. |
| `orch_start_run` | Start a run on a card now. |
| `orch_reply` | Send text to a card's session, or continue it. |
| `orch_stop` | Stop a run. Asks first when an interactive run is waiting on the person. |
| `orch_propose_steps` | Propose a workstream's steps for a card. |
| `orch_run_group` | Run a planned PR group now. |
| `orch_group_cards` | Asks first: group two or more cards into one pull request. |
| `orch_decide` | Asks first: allow or deny a run's pending permission request or question. |
| `orch_remove_workspace` | Asks first: remove a card's workspace from its machine. |
| `orch_archive_card` | Asks first: archive a card. |
| `orch_start_over` | Asks first: start a card over with a fresh run. |
| `orch_move_to_machine` | Asks first: move a card's work to another machine. |

## Planning session tools

A planning session's agent builds a draft of cards with the person, beside the chat. It keeps these chat tools:
`orch_overview`, `orch_list_cards`, `orch_card`, `orch_repo_memory`, `orch_groups` and `orch_open`, and gets the tools
below instead of the rest: it never makes, moves or runs a card, and nothing it writes is a card until the person accepts
the draft. It runs in a read-only checkout of the team's repository and reads it with its own file tools (Claude Code's
`Read` inside the checkout, Codex's shell under a read-only sandbox, Gemini CLI's file-reading tools). Each change names
the item's `rev` as the agent last read it, so an edit over the person's comes back as a conflict, with the item as it
is now, instead of landing. A team, project or recipe is given by name or id, a board card by key (`WEB-12`) or id.

| Tool | What it does | Arguments (* required) |
|---|---|---|
| `plan_read_draft` | The draft: its project, cards, findings and questions, each with its key and `rev`. With `since`, only what changed after that draft revision and who changed it. | `since` |
| `plan_set_project` | The project the draft proposes, or instead the existing project it adds to. | `name`, `description`, `project` (one of `name` or `project`) |
| `plan_upsert_card` | Add a card to the draft (no `rev`; it needs a `title`) or change one (its `rev`; only the fields given change). `depends_on` names draft cards it waits for, `pr_group` gives cards that ship in one pull request the same handle. | `key`*, `title`, `notes`, `team`, `project`, `recipe`, `estimate`, `depends_on`, `depends_on_cards`, `pr_group`, `after`, `migration`, `protected_paths`, `rev` |
| `plan_remove_card` | Remove a card from the draft. | `key`*, `rev`* |
| `plan_move_card` | Move a card to go after another (`after: null`: first). Cards are made in this order. | `key`*, `after`* |
| `plan_add_finding` | Record a finding with its evidence: a file and line, a count and how it was counted, a command and its output, a link or a quote. With `key` and `rev`, change one. | `title`*, `evidence`*, `key`, `body`, `cards`, `rev` |
| `plan_remove_finding` | Remove a finding. | `key`*, `rev`* |
| `plan_ask` | Ask the person an open question, naming the draft cards it affects. An unanswered question holds back Accept of those cards. | `question`*, `key`, `cards` |
| `plan_answer` | Answer an open question once the code settles it. | `key`*, `answer`* |
| `plan_status` | Set the line on the session's card; `ready: true` marks the draft ready to review. | `text`*, `ready` |
| `plan_git` | The checkout's history: `log`, `show`, `grep`, `blame`, `diff` or `ls-files`, with flags from an allowed list and paths inside the checkout. Never `--output`, `-O`, `--ext-diff`, `--textconv`, `-c`, `--exec-path`, `--git-dir`, `--work-tree` or `--no-index`. Output is capped at 64 KB. | `command`*, `args` |

## Coordinator tools

A coordinated workstream's coordinator, on the machine that hosts it, has only these
tools, on its own coordinator thread. Each acts for the person who switched the coordinator on, only on that
workstream's steps, and only while it handles an event; each decision goes on the step's history as the coordinator's.
Starting a step or sending it back only queues a run: Andon still picks the machine. Under the `plan` permission mode
it gets only `coord_workstream` and `coord_step`. A step is its card id or key (`WEB-12`).

| Tool | What it does | Arguments (* required) |
|---|---|---|
| `coord_workstream` | The workstream now: every step's state, what it waits for, its accepted run, retries used, the open escalations and the turns left. | none |
| `coord_step` | One step in full: notes, latest run with its report and tail, pull requests and checks, outputs, pending questions. | `step`* |
| `coord_start_step` | Queue a step's start run with the coordinator's instructions, rendered into the run's prompt. Refused while it has a live run or has run already, a step it waits for isn't accepted and merged, the workstream is paused, or the step is archived. | `step`*, `instructions`* (`target`*, `change`*, `constraints`, `acceptance`*, at most 8,000 characters together) |
| `coord_accept_step` | Accept a step's latest finished run, approving its outputs waiting for review. Never merges: the steps after it wait for its pull requests to merge, and the result names the steps that may start now. | `step`*, `note` |
| `coord_send_back` | Send a step back: a revise run with the feedback as its prompt, or a fresh run after a failure. Refused while its run is live, or once its retries are used up. | `step`*, `feedback`* |
| `coord_answer` | Answer a step's pending question as the person would. Never a permission prompt. | `request`*, `answer`* |
| `coord_revise_steps` | Change steps that have no run yet, all or nothing: update a title, notes or what it waits for, add a step, archive one. Refused for a step with a run or in Done, or a change that makes a cycle. At most 30 changes. | `changes`* (each `{op: update, step, title, notes, waits_for}`, `{op: add, key, title, notes, waits_for, recipe, team}` or `{op: archive, step}`) |
| `coord_escalate` | Ask the person something the coordinator can't decide, with up to six choices. At most three open on a workstream. | `question`*, `choices`, `step` |
