MCP tools

Every tool the Motir MCP server exposes, and the scope that gates it. Grouped by scope, because that is the choice you make when you mint the token — leave a scope off and its whole group refuses.

55 tools · 11 permissions · derived from the server’s own permission map

These are the summaries. For a tool’s exact arguments and response shape, see the reference — it is kept beside the code because those facts change most.

View project

project:browse

Tool	What it does
`dispatch_prompt`	The server-generated coding-agent prompt for one item — the same text the CLI hands an agent.
`get_plan`	A plan with the proposals it bundles: what the planner actually proposed, not just how much.
`get_plan_status`	What became of a submitted planning job — its state, and how many proposals it produced.
`get_project_state`	A project's planning preconditions — established, code connected, indexed, repo set — before you plan.
`get_work_item`	One item in full — description, status, parent and children, dependency edges, and a readiness verdict.
`get_work_item_activity`	One page of an item's discussion and change trail: comment threads and history, interleaved.
`list_projects`	Every project this token can reach, each with the projectKey every other tool takes.
`list_ready`	The ready-to-start set for a project — every item whose dependencies are all satisfied, paginated.
`list_sprints`	A project's sprints with state, goal, window and issue count, and the ids the sprint tools take.
`next_ready`	The single highest-ranked ready item, as a full dispatch payload. The “what do I do next” call.
`search_work_items`	Search a project's items with the same filter grammar the advanced filter builder writes.
`search_work_items_semantic`	Has this already been built? Search by MEANING rather than substring — keys, titles and scores only.
`skeleton`	The whole project's tree shape in one read — every item's key, kind, title, status and parent, with no paging loop.
`validate_plan`	Would approve TAKE this plan, and is it finishable? Both, before `final: true` — nobody else will ask.
`validate_sprint`	Is this sprint finishable? Names every in-sprint item still gated by work outside it.
`validate_work_item`	Is this epic, story, task or bug finishable? Names the out-of-subtree work still gating it.
`whoami`	Who this token is: the owning user, the active workspace, and the scopes granted. Call it first.

Tool: dispatch_prompt
What it does: The server-generated coding-agent prompt for one item — the same text the CLI hands an agent.

Tool: get_plan
What it does: A plan with the proposals it bundles: what the planner actually proposed, not just how much.

Tool: get_plan_status
What it does: What became of a submitted planning job — its state, and how many proposals it produced.

Tool: get_project_state
What it does: A project's planning preconditions — established, code connected, indexed, repo set — before you plan.

Tool: get_work_item
What it does: One item in full — description, status, parent and children, dependency edges, and a readiness verdict.

Tool: get_work_item_activity
What it does: One page of an item's discussion and change trail: comment threads and history, interleaved.

Tool: list_projects
What it does: Every project this token can reach, each with the projectKey every other tool takes.

Tool: list_ready
What it does: The ready-to-start set for a project — every item whose dependencies are all satisfied, paginated.

Tool: list_sprints
What it does: A project's sprints with state, goal, window and issue count, and the ids the sprint tools take.

Tool: next_ready
What it does: The single highest-ranked ready item, as a full dispatch payload. The “what do I do next” call.

Tool: search_work_items
What it does: Search a project's items with the same filter grammar the advanced filter builder writes.

Tool: search_work_items_semantic
What it does: Has this already been built? Search by MEANING rather than substring — keys, titles and scores only.

Tool: skeleton
What it does: The whole project's tree shape in one read — every item's key, kind, title, status and parent, with no paging loop.

Tool: validate_plan
What it does: Would approve TAKE this plan, and is it finishable? Both, before final: true — nobody else will ask.

Tool: validate_sprint
What it does: Is this sprint finishable? Names every in-sprint item still gated by work outside it.

Tool: validate_work_item
What it does: Is this epic, story, task or bug finishable? Names the out-of-subtree work still gating it.

Tool: whoami
What it does: Who this token is: the owning user, the active workspace, and the scopes granted. Call it first.

View the lesson library

lesson:view

Tool	What it does
`search_lessons`	Search recorded lessons by meaning — the shared corpus and this project's own — before you plan or build.

Tool: search_lessons
What it does: Search recorded lessons by meaning — the shared corpus and this project's own — before you plan or build.

Change the lesson library

lesson:manage

Tool	What it does
`add_lesson`	Record a lesson for this project, so later plans for it are given the lesson. This project only.

Tool: add_lesson
What it does: Record a lesson for this project, so later plans for it are given the lesson. This project only.

Record a lesson recurrence

lesson:reinforce

Tool	What it does
`reinforce_lesson`	Record that a lesson you found describes something that just went wrong — whether or not you also change it.

Tool: reinforce_lesson
What it does: Record that a lesson you found describes something that just went wrong — whether or not you also change it.

Edit work items

work_item:edit

Tool	What it does
`attach_file`	Put a file ON a work item — a research findings document, a review’s notes — so a reader sees the deliverable on the card instead of hunting for a pull request.
`change_kind`	Reclassify a leaf's kind when it is mis-filed — subtask to task, and back.
`claim_next_ready`	Atomically claim the next ready subtask in the active sprint and flip it to In Progress. Race-safe.
`claim_work_item`	Atomically claim ONE named work item and flip it to In Progress. A lost claim says WHO holds it.
`complete_session`	Close out a session branch after its PR merged: every item recorded on it moves to Done.
`create_plan`	Open a plan to propose into — the reviewable container an agent fills instead of writing items.
`create_work_item`	Create an epic, story, task, bug or subtask; points, estimate, type, executor and repo in one call.
`link_pull_request`	Declare which work item a pull request delivers — call it right after opening one, once per work item it delivers. The association is a SET, so a second call ADDS rather than moving, and it works before any webhook delivery has arrived.
`link_work_items`	Create an edge between two items — blocked_by is the one that holds an item out of the ready set.
`mark_integrated`	Record that an item's work landed — the branch, the PR and the commit that carried it.
`move_to_parent`	Re-parent an item, enforcing the kind-parent matrix and refusing a cycle.
`publish_design_result`	Put the design RESULT on a design work item — the note sections you changed, the mock and the .png export, in one call. It is the deliverable a reviewer opens, and nothing else publishes it.
`transition_status`	Move an item to another status. An illegal move comes back naming the ones that are legal.
`unlink_pull_request`	Undo ONE `link_pull_request` — remove the delivery recorded between a work item and a pull request. A delivery is a row, so re-linking the right card ADDS rather than corrects; this removes exactly the one pair you name and leaves every other delivery alone.
`unlink_work_items`	Remove an edge, given the same relationship used to create it.
`update_work_item`	Edit any subset of an item's fields, including the explanation body create cannot set.

Tool: attach_file
What it does: Put a file ON a work item — a research findings document, a review’s notes — so a reader sees the deliverable on the card instead of hunting for a pull request.

Tool: change_kind
What it does: Reclassify a leaf's kind when it is mis-filed — subtask to task, and back.

Tool: claim_next_ready
What it does: Atomically claim the next ready subtask in the active sprint and flip it to In Progress. Race-safe.

Tool: claim_work_item
What it does: Atomically claim ONE named work item and flip it to In Progress. A lost claim says WHO holds it.

Tool: complete_session
What it does: Close out a session branch after its PR merged: every item recorded on it moves to Done.

Tool: create_plan
What it does: Open a plan to propose into — the reviewable container an agent fills instead of writing items.

Tool: create_work_item
What it does: Create an epic, story, task, bug or subtask; points, estimate, type, executor and repo in one call.

Tool: link_pull_request
What it does: Declare which work item a pull request delivers — call it right after opening one, once per work item it delivers. The association is a SET, so a second call ADDS rather than moving, and it works before any webhook delivery has arrived.

Tool: link_work_items
What it does: Create an edge between two items — blocked_by is the one that holds an item out of the ready set.

Tool: mark_integrated
What it does: Record that an item's work landed — the branch, the PR and the commit that carried it.

Tool: move_to_parent
What it does: Re-parent an item, enforcing the kind-parent matrix and refusing a cycle.

Tool: publish_design_result
What it does: Put the design RESULT on a design work item — the note sections you changed, the mock and the .png export, in one call. It is the deliverable a reviewer opens, and nothing else publishes it.

Tool: transition_status
What it does: Move an item to another status. An illegal move comes back naming the ones that are legal.

Tool: unlink_pull_request
What it does: Undo ONE link_pull_request — remove the delivery recorded between a work item and a pull request. A delivery is a row, so re-linking the right card ADDS rather than corrects; this removes exactly the one pair you name and leaves every other delivery alone.

Tool: unlink_work_items
What it does: Remove an edge, given the same relationship used to create it.

Tool: update_work_item
What it does: Edit any subset of an item's fields, including the explanation body create cannot set.

Archive work items

work_item:archive

Tool	What it does
`archive_work_item`	Soft-remove an item: it leaves the ready set and search, and stays fully restorable.
`unarchive_work_item`	Restore an archived item — the inverse of archive.

Tool: archive_work_item
What it does: Soft-remove an item: it leaves the ready set and search, and stays fully restorable.

Tool: unarchive_work_item
What it does: Restore an archived item — the inverse of archive.

Delete work items

work_item:deleteoff by default

Tool	What it does
`delete_work_item`	Permanently delete an item and its whole subtree. Irreversible, and off by default.

Tool: delete_work_item
What it does: Permanently delete an item and its whole subtree. Irreversible, and off by default.

Add comments

comment:add

Tool	What it does
`add_comment`	Post a Markdown comment as the token owner. Mentions notify the member named.

Tool: add_comment
What it does: Post a Markdown comment as the token owner. Mentions notify the member named.

Manage sprints

sprint:manage

Tool	What it does
`complete_sprint`	Complete the active sprint.
`create_sprint`	Create a planned sprint on a project, with an optional name, goal and planned window.
`delete_sprint`	Delete a planned or complete sprint.
`move_to_backlog`	Move items out of their sprint and back to the backlog.
`move_to_sprint`	Add items to a sprint in one atomic move, appended in the order given.
`start_sprint`	Start a planned sprint, making it the project's active one.
`update_sprint`	Rename a sprint, change its goal, or adjust its planned window.

Tool: complete_sprint
What it does: Complete the active sprint.

Tool: create_sprint
What it does: Create a planned sprint on a project, with an optional name, goal and planned window.

Tool: delete_sprint
What it does: Delete a planned or complete sprint.

Tool: move_to_backlog
What it does: Move items out of their sprint and back to the backlog.

Tool: move_to_sprint
What it does: Add items to a sprint in one atomic move, appended in the order given.

Tool: start_sprint
What it does: Start a planned sprint, making it the project's active one.

Tool: update_sprint
What it does: Rename a sprint, change its goal, or adjust its planned window.

Run AI planning

ai:plan

Tool	What it does
`append_plan_turn`	Add one turn to a project's planning conversation — what you want changed about the plan.
`expand_item`	Submit an AI expansion of one container item. Spends the owner's credits; proposals await approval.
`open_plan_session`	Open — or resume — a project's planning conversation, and read its thread.
`submit_plan_session`	Send the conversation's accumulated intent to the planner as one change set.

Tool: append_plan_turn
What it does: Add one turn to a project's planning conversation — what you want changed about the plan.

Tool: expand_item
What it does: Submit an AI expansion of one container item. Spends the owner's credits; proposals await approval.

Tool: open_plan_session
What it does: Open — or resume — a project's planning conversation, and read its thread.

Tool: submit_plan_session
What it does: Send the conversation's accumulated intent to the planner as one change set.

Author AI plans

ai:view_plan

Tool	What it does
`add_plan_items`	Append proposals to a plan — or close it with an empty final batch; ids come back in order, so the next batch can hang children off them.
`update_plan_item`	Fill in a proposal you appended — the deepen turn, while the plan is still being written.
`update_plan_proposal`	Correct a proposal — including its parent, its dependency edges and its repo pin (name and role) — even after the plan is in review.
`withdraw_plan_proposal`	Take one proposal off a plan, instead of asking a reviewer to decline the whole thing.

Tool: add_plan_items
What it does: Append proposals to a plan — or close it with an empty final batch; ids come back in order, so the next batch can hang children off them.

Tool: update_plan_item
What it does: Fill in a proposal you appended — the deepen turn, while the plan is still being written.

Tool: update_plan_proposal
What it does: Correct a proposal — including its parent, its dependency edges and its repo pin (name and role) — even after the plan is in review.

Tool: withdraw_plan_proposal
What it does: Take one proposal off a plan, instead of asking a reviewer to decline the whole thing.