MCP tools reference
Every Ideafy tool the agent can call, what it does, what it changes. Tools are grouped by family. Names below are without the mcp__ideafy__ prefix that the agent uses internally.
Local (CRUD) tools
get_card
Purpose. Fetch a single card by ID.
Input. id — UUID, display ID (KAN-14), or task number.
Output. The card JSON plus any inline images extracted from the HTML fields.
Side effects. None.
create_card
Purpose. Create a new card in a project.
Input. title (required), projectId (required), description, solutionSummary, status, complexity, priority, groupId (all optional).
groupId. The card_groups.id of the chain this card belongs to — the row the board folds it into. A group is membership only: it has no status, no completion state and no date of its own, so it is not an epic.
Output. The new card's ID.
Side effects. Inserts a new row in cards, increments projects.next_task_number, fires a sync-card call to Supabase if the project is team-linked.
update_card
Purpose. Change fields on an existing card.
Input. id and any subset of title, description, solutionSummary, status, complexity, priority, useWorktree, groupId (null removes the card from its chain).
Output. Confirmation.
Side effects. Updates the card row; fires a sync-card call.
Not accepted: testScenarios — the call is refused with "use save_tests instead", because save_tests is what preserves existing checkbox state and guards against accidental wipes. aiOpinion is likewise routed through save_opinion.
move_card
Purpose. Move a card to another column.
Input. id, status (the target column).
Output. Confirmation.
Side effects. Sets status; fires a sync-card call. Does not run any AI processing — this is a dumb move.
list_cards
Purpose. List cards in a project, optionally filtered by status.
Input. Optional status, optional projectId.
Output. Array of cards plus up to 10 inline images.
Side effects. None.
get_project_by_folder
Purpose. Resolve a folder path to an Ideafy project.
Input. folderPath (absolute).
Output. { found: boolean, project } or an error.
Side effects. None. Used by skills as a defensive "are we in an Ideafy project" check before running anything else.
Workflow tools
The three tools that write a phase's output onto the card. Two of them (save_plan, save_tests) also move the card, and that move is the side effect you're buying when you call them. The third (save_opinion) writes only — see below.
save_plan
Purpose. Save an implementation plan to the Solution tab.
Input. id, solutionSummary (markdown — gets rendered as Tiptap HTML).
Output. Confirmation.
Side effects. Sets solutionSummary. Moves the card to progress (In Progress). Fires a sync-card call.
save_tests
Purpose. Save acceptance tests to the Tests tab, and record results as they're verified.
Input. id, testScenarios (markdown with - [ ] checkboxes), optional allowDeletion (boolean).
Output. Confirmation. Under allowDeletion, the summary also reports how many existing scenarios were removed and how many kept.
Side effects. Sets testScenarios after preserving any existing checked state (see Tests tab). Moves the card to test (Human Test). Fires a sync-card call.
Guards. This tool is deliberately stricter than update_card, and refuses rather than silently losing work:
| Situation | Result |
|---|---|
| Payload contains no markdown checkboxes at all | Refused — plain paragraphs would wipe checkbox state. True even under allowDeletion: it's a format mistake, not a deletion |
| Existing list has checked items but the payload preserves none | Refused — send the [x] items back verbatim |
| Payload drops an existing item (fuzzy text match) | Refused — append-only. Resend the full list plus your additions |
Same, but allowDeletion: true | Allowed — the payload becomes a literal replacement |
Style contract. The tool's description carries the same checklist contract every other AI surface injects — capped ## Core flow group first, real card data instead of placeholders, second-person imperative steps. It's copied verbatim from the app's shared module at build time rather than maintained separately, so a checklist written through MCP reads the same as one written in the chat panel. The description is static text assembled at server start, long before any card is known, so it ships the English body and leaves the "mirror the card's language" rule in play. See The core flow.
allowDeletion. The append-only guard is absolute, so this flag is the only way to remove a scenario. It's meant for the turn where the user explicitly asks to remove, drop, or undo scenarios. Turning it on skips the append-only check, the checked-item check and the check-state merge — whatever is sent becomes the checklist, [x]/[ ] state included — so every surviving item must be copied over exactly as it stands. Omit it for normal appends and nothing changes.
save_opinion
Purpose. Save an AI evaluation to the Opinion tab.
Input. id, aiOpinion (markdown, expected to follow the Summary Verdict / Strengths / Concerns / Recommendations / Priority / Final Score template), optional aiVerdict (positive / negative).
Output. Confirmation.
Side effects. Sets aiOpinion and aiVerdict — and nothing else. It does not move the card between columns; whatever the verdict, the card stays where it is. Fires a sync-card call.
To move the card, the agent asks separately after the opinion lands, then calls move_card — backlog on a positive verdict, withdrawn on a negative one. Both the tool's own description and the Ideation phase policy say this, because the model reads both and will believe whichever one it finds first.
Branch tools
ensure_branch
Purpose. Make sure the working tree is on the branch this card is supposed to be implemented on. Remediation for the deny emitted by the PreToolUse hook (see branch enforcement).
Input. cardId — UUID, display ID (KAN-54), or task number.
Output. A short message: either "already on branch X", "created worktree at Y", "switched to branch Z", or "enforcement disabled for this card".
Side effects. Idempotent.
- Worktree mode (project
useWorktrees = true, the default): if the worktree at.worktrees/kanban/[PRJ-N-...]doesn't exist, creates it with the correct branch checked out. If it exists, no-op. - In-place mode (project
useWorktrees = false): checks out the card's branch in the main working directory, creating it frommainif needed. - No-op conditions: card's effective
useWorktreepolicy isfalse, working tree already on the target branch, card status isn't implementable, or card has no resolvable project folder. The tool never writes to files or commits — it only manipulates branches and worktrees. Safe to call any time.
Pool tools (Team edition only)
These only work when the project is linked to a team and the user is signed in.
pool_list
Purpose. List pool cards for a team.
Input. Optional teamId. "all" returns pool cards across every team the user is in.
Output. Formatted table of pool cards with pushedByName, assignedToName, status.
Side effects. None. Read-only; works even when subscription is expired.
pool_push
Purpose. Push a local card to the team pool.
Input. cardId, optional assignedTo.
Output. The pool card UUID.
Side effects. Creates or updates a row in Supabase pool_cards. Sets poolCardId and poolOrigin = "pushed" on the local card. If assignedTo === you (self-claimed push), the pool row's pulled_by is also set to you — you already hold the local copy, so the pull lock is yours. If assignedTo is a teammate, fires a pool_assigned notification. Blocked if subscription is expired.
pool_pull
Purpose. Pull a pool card into your local board.
Input. poolCardId.
Output. The new local card's ID.
Side effects. Atomically claims the pool card (sets pulled_by and assigned_to). Creates a new local card with poolOrigin = "pulled". Blocked if subscription is expired. Race-safe: concurrent pulls fail with 409.
pool_claim
Purpose. Claim, unclaim, or reassign a pool card.
Input. poolCardId, optional action (claim default / unclaim / reassign), optional assignToUserId for reassign.
Output. Confirmation.
Side effects. Sets or clears assigned_to on the pool row. The current assignee can reassign the card (to another member or to null) without admin rights; admins / owners can also reassign cards claimed by others. A claim-or-reassign that lands on the original pusher also promotes them into the pull lock if the lock is currently free; reassigning away from a pusher who held the lock clears it so the new assignee can pull. Fires pool_assigned / pool_claimed notifications as appropriate. Blocked if subscription is expired.
What fires sync-card?
Every local CRUD mutation (create_card, update_card, move_card, save_plan, save_tests, save_opinion) fires a fire-and-forget /api/internal/sync-card call. In the Team edition, this keeps the pool view on teammates' machines in sync with your local state within seconds. If the network's down, the call silently fails and the next mutation retries.
What moves the card
Only three tools move a card between columns:
| Tool | From | To |
|---|---|---|
save_plan | any | progress (In Progress) |
save_tests | any | test (Human Test) |
move_card | any | any (explicit) |
Everything else respects the current column.
Prev: Bundled Claude Code hooks Next: Autonomous vs quick-fix Up: User guide index