Tools Reference

The complete tool surface exposed by the AI StackWorks MCP server. All content is exchanged as Markdown strings. Tools that operate on a card take a required card_id; an unknown or cross-project card_id returns card not found. See Authentication for how card_id is scoped to your project.

Cards

get_card

Read a card's current content — title, status, properties, and body. Call it before update_card so you start from the live body.

Returns the card as Markdown: frontmatter (title, status, type, priority) above the body.

update_card

Save changes to a card — its body, properties, and/or status. Pass only what you are changing.

Saving also syncs the card to its Notion mirror.

create_card

Open a new card in your project's Backlog.

Returns a confirmation with the new card's id, then the card as Markdown, so you have its id to approve and dispatch it next.

approve_card

Approve a card's plan — move it to Plan Approved. This is the approval gate that would otherwise wait on a human; the move is recorded on the Timeline as an agent approval. Approving an already-approved card is a harmless no-op.

dispatch_card

Dispatch a card to the agent fleet — move it to Ready for Dev. This kicks off the build → test → review → docs → ship pipeline. Dispatch is asynchronous: the card is placed on Ready for Dev and its execution graph is seeded shortly after (within a minute). If the project has no agent host connected, the card still moves but nothing runs until one is enrolled — the reply says so.

Card lifecycle: create_card → approve_card → dispatch_card.

Tasks

Each card has exactly one task checklist.

get_tasks

Read a card's task checklist as Markdown — one - [ ] (open) / - [x] (done) line per task, each carrying a <!-- id: N --> anchor.

update_tasklist

Edit the whole checklist in one call — add, edit, reorder, check off, or remove tasks. Read the list with get_tasks, change the Markdown, then send the full list back.

How lines map to tasks: a line that keeps its <!-- id: N --> anchor updates that task; a line with no id creates a new task; an existing task you leave out is removed. - [x] marks a task done, - [ ] open.

create_task

Append a single task without resending the whole list.

Ideas

create_idea

Capture a new idea for the project — a feature thought, suggestion, or improvement to revisit later. Call list_ideas first to avoid duplicates.

Returns a confirmation carrying the new idea's slug.

list_ideas

List the project's open ideas as a Markdown checklist (one - [status] title <!-- slug: ... --> line each). Read-only, no arguments. Dismissed and closed ideas are excluded.

Changelog

create_changelog

Record a changelog entry — a user-facing note that something shipped or changed.

Returns a confirmation carrying the new entry's slug.

Progress reporting

report_progress

How a worker narrates a pipeline stage and lets the card advance itself. Call it twice per stage you work — once on pickup (status="started") and once on completion. Do not move stage cards with update_card(status=...).

The (skill, status) pair drives the card's board column:

Any pair not listed records the event for the Timeline but does not move the card. status="blocked" (any skill) raises the card's Blocked flag and seeds the reason from your headline; the card keeps its column until an operator unblocks it. The card only ever moves forward — a stale or backward pair is recorded but does not move it.