---
title: "Tools and actions | Annsa Docs"
product: annsa
url: /docs/tools-and-verbs
canonical_url: "https://annsa.ai/docs/tools-and-verbs"
last_updated: 2026-11-22
type: doc
related:
  - /agents
summary: Every Annsa MCP tool and every action, with one line on what it does and whether an agent, a person, or both may run it.
mcp_server: https://app.annsa.ai/mcp
disambiguation: "Annsa (annsa.ai) is project management and customer feedback software for founders and small teams working with AI agents. It is not Asana, the work management tool; not ANSA, the Italian news agency; and not Ansa, the chatbot product."
---

> For agents: connect to the Annsa MCP server at https://app.annsa.ai/mcp to give every agent one shared plan. Setup guide: https://annsa.ai/docs/quick-start. Index of every page: https://annsa.ai/llms.txt.

# Tools and actions | Annsa Docs

> Every Annsa MCP tool and every action, with one line on what it does and whether an agent, a person, or both may run it.

[Docs / Agents](https://annsa.ai/docs)

Eight tools, thirty-odd actions, and who is allowed to run each.

## 01 The eight tools

Three tools read and change nothing (`annsa.priorities`, `annsa.spec`, `annsa.ask`). Five act, split by how much they can change (`annsa.work`, `annsa.file`, `annsa.decide`, `annsa.board`, `annsa.share`), so you can allow `annsa.work` and `annsa.file` without asking and approve the other three.

- `annsa.priorities`: Your ranked to-do list. Use it to see what to work on next: every open priority in rank order, with how many customers asked and why each one ranks where it does. Ask for one priority by its number to get just that row. For the full plan behind a priority, read annsa.spec. It doesn't search what customers said; that's annsa.ask.
- `annsa.spec`: The plan for one priority. Use it before starting work: it gives you the Problem, What to build, and the Done When lines you'll have to prove. The reply carries build\_id, the spec id (build\_…) that verify and ship take as spec\_id. Add include\_evidence to see Evidence and direction, Files to touch and the customer quotes behind it. It doesn't list or rank priorities; that's annsa.priorities.
- `annsa.ask`: Ask Annsa a question in plain words. Use it to find what customers said about something, what's on the board, or how Annsa works. about picks where to look: feedback (default), annsa (the docs), surveys, customer, accounts, templates or transcript. You get an answer with the quotes and priorities it came from. Before filing a bug, send do\_we\_have with your text to check whether a priority already covers it. It doesn't list the ranked work; that's annsa.priorities.
- `annsa.work`: Do the work on a priority. Use it to claim a priority, write your part of the spec, leave notes, prove each Done When line with verify, and mark it shipped. claim gives you a spec\_id for write, verify and ship, and a holder\_key for write and ship. Ship only records that it shipped; it doesn't deploy anything. If you need a person to decide something, use escalate. It doesn't move, merge or re-rank priorities; that's annsa.board. Actions: `ship`, `claim`, `note`, `handoff`, `dispatch`, `unclaim`, `close`, `write`, `verify`, `escalate`, `resolve` and `undo`.
- `annsa.file`: Add something new to the board. Use it to file what a customer said, a bug or finding you found, or an idea. It attaches to the matching priority if there is one; add stand\_alone to make a new priority instead. The reply tells you which priority it landed on. It doesn't change rows that already exist; that's annsa.board. To tell the Annsa team about Annsa itself, use report. Actions: `submit`, `report`, `add_page`, `add_template`, `connect_goal`, `add_transcript`, `import_direction` and `add_priority`.
- `annsa.decide`: Record what a person decided. A person uses it to answer a question an agent raised or sign off a priority. As an agent you can list principles, propose one, approve or dismiss a proposed spec change, or pass on a person's exact words with person\_words. To ask a person something, use annsa.work escalate instead. Actions: `approve`, `dismiss`, `answer`, `ask_back`, `direct`, `choose`, `sign` and `principle`.
- `annsa.board`: Tidy the board. Use it to change a priority's stage or severity, merge duplicates, move priorities between groups, fix a title, place priorities on a bet, or cut a release. A merge retires the duplicate numbers for good. Some actions, like park and assign, are for people only. It doesn't do the work on a priority; that's annsa.work. Actions: `set_stage`, `assign`, `correct`, `park`, `unpark`, `retract`, `regroup`, `merge`, `bet`, `direction`, `set_severity`, `cut`, `pick`, `approve_findings` and `view`.
- `annsa.share`: Tell customers their request shipped. Use it after a priority ships to email or notify everyone who asked for it. Emails can't be unsent, so only a signed-in person can run it. The reply says who was told. It doesn't mark anything shipped; that's annsa.work ship. Actions: `share`.

`annsa.help` and `annsa.surveys` are retired and refused. Use `annsa.ask about=annsa` or `annsa.ask about=surveys`. `annsa.act` is still callable as the single tool behind the five. Old action names are refused too, and the reply names the new one: calling `release` answers that it is no longer an action and to send `unclaim`. An agent credential is refused these actions, whichever tool carries them: `dispatch`, `add_transcript`, `import_direction`, `ask_back`, `direct`, `choose`, `sign`, `assign`, `park`, `retract`, `approve_findings` and `share`.

A priority filed in the last few minutes can be missing from the next list read. `annsa.priorities` with `priority_number=N` returns it.

## 02 Who may run an action

Each row says who may run the action. **Agent** means an agent credential may run it. **Agent, or person** means either may. **Agent, only with workspace planning authority** means the agent credential must hold that authority. **Person** means the agent credential is refused on purpose, because these are decisions and an agent that could make them would be approving its own work. **Partly** means an agent may run one form of it. The credential decides, not the client, so Claude Code signed in with OAuth is you and has your rights, and an agent credential you minted does not. `who.actor.kind` says `user` or `agent`.

## 03 Work on a priority

| Action | What it does | Who may run it |
| --- | --- | --- |
| `claim` | Take a priority to work on. Starts a spec if there isn't one and gives you spec\_id and holder\_key. | Agent |
| `note` | Leave a note on the spec about what you did or found. To correct an earlier note, send a new one with supersedes. | Agent |
| `unclaim` | Unclaim a priority so another agent can pick it up. | Agent |
| `handoff` | Pass the work to another agent or a person, with a note for them. | Agent |
| `close` | Close the priority in one call, even if it's claimed or has a PR. It stays under Closed with your reason. | Agent |
| `dispatch` | Post @claude on the priority's GitHub issue so Claude picks it up there. The person stays assigned. A person's action. | Person |
| `ship` | Mark the priority shipped. It only records it; nothing deploys. retract undoes it. | Agent |
| `verify` | Record how you checked one Done When line, by proof kind: a test id for (proof: test), a URL for staging or prod. It doesn't block ship. | Agent |
| `set_stage` | Move a priority to open, ready or closed. | Agent, only with workspace planning authority |
| `retract` | Unfile feedback, or mark a shipped priority as not shipped. A person's action; without confirm it only shows the plan. | Person |
| `resolve` | Settle a routine question, like 'is this a duplicate of #N?', the way your principles already decide it. Each outcome fits one kind of question. Returns use\_id so you can undo. | Agent |
| `undo` | Reverse your own resolve, by use\_id. | Agent |

## 04 Write the spec

| Action | What it does | Who may run it |
| --- | --- | --- |
| `write` | Replace one section of the spec with new text. If the section belongs to someone else, your text is saved as a proposed change for them. | Agent |
| `approve` | Accept another writer's proposed section text, by update\_id. | Agent |
| `dismiss` | Turn down a proposed section text; the current text stays. | Agent |
| `correct` | Fix a title, detail or ruled-out entry. The old wording is kept. | Partly: an agent can fix a title, detail or ruled-out entry; category is a person's |
| `direction` | Read, list, update or comment on a Direction page. op says which. | Partly: an agent can read, list, update and comment; approving is a person's |

## 05 File and tidy

| Action | What it does | Who may run it |
| --- | --- | --- |
| `submit` | File what a customer said or what you found. With priority\_number it attaches to that priority; with stand\_alone it starts a new one. | Agent |
| `add_priority` | Add a priority from a title and detail, with no customer words. | Agent |
| `merge` | Fold duplicate priorities into one. Their numbers are retired for good. Shipped priorities can't be merged. | Agent |
| `regroup` | Move priorities between groups; the reply carries the undo. | Agent |
| `set_severity` | Set a priority's severity, P0 to P3. From an agent it's a proposal and needs a reason; a person's typed severity wins. | Partly: an agent proposes it, and a person's severity wins |
| `add_transcript` | Add a call transcript as customer feedback. What the customer asked for is filed from it. A person's action. | Person |
| `import_direction` | Import a strategy doc in two steps. First preview its lines, then add the ones you pick as ideas. A person's action. | Person |
| `report` | Tell the Annsa team about a bug, gap or idea in Annsa itself. Send text; title names the tool and action. Keep your customers' data out of it. | Agent |
| `add_page` | Make a page from a template, private to you. Returns the link. | Agent |
| `add_template` | Save a template with a title, text and when to use it. {blanks} in the text become its fields. | Agent |
| `connect_goal` | Answer the welcome's optional question about what you want from Annsa, up to 300 characters. Goes to the Annsa team, not your board. | Agent |
| `approve_findings` | Let through agent findings held back by the daily limit. The owner's action. | Person |

## 06 Decide and direct

| Action | What it does | Who may run it |
| --- | --- | --- |
| `bet` | List, create, update, delete or reorder bets, or place priorities on one. op says which. | Partly: an agent can list, create, place and update; a person reorders and deletes |
| `sign` | Record a person's decision on a priority (do\_this, do\_nothing, park or dismiss), with because. A person's action. | Person |
| `park` | Take a priority off the list, with a reason, until someone unparks it. A person's action. | Person |
| `unpark` | Put a parked priority back on the list. | Agent |
| `assign` | Set who a spec is assigned to. A person's action. | Person |
| `principle` | Your decision memory. Agents can list principles or propose one; a person writes, retires or reactivates them. A proposal applies at once. | Partly: an agent can list and propose; a person writes, retires and activates |
| `direct` | A person gives the agent holding a priority a direction; the agent reads it on its next reply. A person's action. | Person |
| `pick` | Set a person's short list of priorities, in order. | Agent |
| `view` | Save a board view. An agent's is a suggestion until a person keeps or dismisses it. | Partly: an agent's view is a suggestion until a person keeps it |

## 07 Ask and answer

| Action | What it does | Who may run it |
| --- | --- | --- |
| `escalate` | Ask a person to decide something; it lands in their Needs you. Send topic, ask, trigger, principle and checked. One open ask per priority; the same topic updates it. | Agent |
| `answer` | Record a person's answer to the open ask on a priority. An agent passes on the person's exact words with person\_words. Picking an option labelled Merge, Ship it, Park it or Retract the ship runs it; free text is only recorded. | Partly: an agent can relay a person's exact words |
| `ask_back` | A person asks the agent a question back on a priority. A person's action. | Person |
| `choose` | Record a person's pick on a Needs you question (send disagreement\_id). One option, or neither. A person's action. | Person |

Settled topics aren't asked again. Signed in as yourself, you can answer from your own terminal. An answer runs something only when you pick an option that names an action: Merge on a "Looks like #NNN" question, Ship it, Park it, Retract the ship, or Dismiss or Close. Anything you type is stored, and the agent reads it on the spec as `decision` if the priority has a spec.

## 08 Tell customers and cut releases

| Action | What it does | Who may run it |
| --- | --- | --- |
| `share` | Email or notify the customers who asked that it shipped. An email cannot be unsent. | Person |
| `cut` | Close a release and write its changelog. op=publish marks its rows Shared. | Agent |

- [What your agent can do](https://annsa.ai/docs/agent-access)

## Keep reading

- [Every agent works from the same plan.](https://annsa.ai/agents)

## Related pages

> For AI agents: the pages that follow this one on annsa.ai. The full index is https://annsa.ai/llms.txt.

- [AI agent platform: one plan for every agent](https://annsa.ai/agents)

If anything on this page is wrong or missing, tell us: https://annsa.ai/contact
