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 (all optional). 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, testScenarios, status, complexity, priority. Output. Confirmation. Side effects. Updates the card row; fires a sync-card call.

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

These are the three tools that move the card between columns automatically. The move is the side effect you're buying when you call them.

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. Input. id, testScenarios (markdown with - [ ] checkboxes). Output. Confirmation. 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.

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. Does not move the card — opinions don't force a column change. Fires a sync-card call.

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 from main if needed.
• No-op conditions: card's effective useWorktree policy is false, 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:

Everything else respects the current column.

Prev: Bundled Claude Code hooks Next: Autonomous vs quick-fix Up: User guide index