Skip to content
Browse docs
Docs / Agents

Tools and actions

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

ActionWhat it doesWho may run it
claimTake a priority to work on. Starts a spec if there isn't one and gives you spec_id and holder_key.Agent
noteLeave a note on the spec about what you did or found. To correct an earlier note, send a new one with supersedes.Agent
unclaimUnclaim a priority so another agent can pick it up.Agent
handoffPass the work to another agent or a person, with a note for them.Agent
closeClose the priority in one call, even if it's claimed or has a PR. It stays under Closed with your reason.Agent
dispatchPost @claude on the priority's GitHub issue so Claude picks it up there. The person stays assigned. A person's action.Person
shipMark the priority shipped. It only records it; nothing deploys. retract undoes it.Agent
verifyRecord 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_stageMove a priority to open, ready or closed.Agent, only with workspace planning authority
retractUnfile feedback, or mark a shipped priority as not shipped. A person's action; without confirm it only shows the plan.Person
resolveSettle 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
undoReverse your own resolve, by use_id.Agent

04 Write the spec

ActionWhat it doesWho may run it
writeReplace 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
approveAccept another writer's proposed section text, by update_id.Agent
dismissTurn down a proposed section text; the current text stays.Agent
correctFix 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
directionRead, 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

ActionWhat it doesWho may run it
submitFile 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_priorityAdd a priority from a title and detail, with no customer words.Agent
mergeFold duplicate priorities into one. Their numbers are retired for good. Shipped priorities can't be merged.Agent
regroupMove priorities between groups; the reply carries the undo.Agent
set_severitySet 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_transcriptAdd a call transcript as customer feedback. What the customer asked for is filed from it. A person's action.Person
import_directionImport a strategy doc in two steps. First preview its lines, then add the ones you pick as ideas. A person's action.Person
reportTell 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_pageMake a page from a template, private to you. Returns the link.Agent
add_templateSave a template with a title, text and when to use it. {blanks} in the text become its fields.Agent
connect_goalAnswer 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_findingsLet through agent findings held back by the daily limit. The owner's action.Person

06 Decide and direct

ActionWhat it doesWho may run it
betList, 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
signRecord a person's decision on a priority (do_this, do_nothing, park or dismiss), with because. A person's action.Person
parkTake a priority off the list, with a reason, until someone unparks it. A person's action.Person
unparkPut a parked priority back on the list.Agent
assignSet who a spec is assigned to. A person's action.Person
principleYour 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
directA person gives the agent holding a priority a direction; the agent reads it on its next reply. A person's action.Person
pickSet a person's short list of priorities, in order.Agent
viewSave 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

ActionWhat it doesWho may run it
escalateAsk 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
answerRecord 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_backA person asks the agent a question back on a priority. A person's action.Person
chooseRecord 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

ActionWhat it doesWho may run it
shareEmail or notify the customers who asked that it shipped. An email cannot be unsent.Person
cutClose a release and write its changelog. op=publish marks its rows Shared.Agent
Next guideWhat your agent can do