move_work_item
Move a work item along its lifecycle, from the backlog through ready, in progress, in review and in QA to done or cancelled, with a resolution on a close.
Move a work item to a new status, following the moves the lifecycle allows from where it stands: from the backlog to ready, in progress or cancelled; from ready back to the backlog, on to in progress or cancelled; from in progress to ready, in review, in QA, done or cancelled; from in review to in progress, in QA, done or cancelled; from in QA to in progress, done or cancelled; a done item back to in progress; a cancelled one back to the backlog. A move into done resolves the item as done; a move into cancelled takes wont_do (the default), duplicate, cannot_reproduce or deferred. The first move into progress stamps when work started, a move into done stamps the finish, and the item writes a version with the reason transition; work_item.transitioned goes out with the status before and after.
Destructive in the MCP sense: it changes where someone's work stands, so read the item with get_work_item first and confirm with the person before moving an item that is not theirs. Say why in your reply; the comment that will travel with a move is not here yet. A move to the status the item is in already changes nothing.
Requires ability
The token behind the MCP session must hold it, or the call is refused with TOKEN_MISSING_ABILITY.
Runs the same action as
The REST endpoint and this tool share one action, so validation, permissions and events are identical.
Fires one event
Delivered to every endpoint subscribed to it once the change is made.
Annotations
A client that honours annotations asks a person before running it.
Arguments
work_item_id*stringUUID of the work item to move.
status*stringWhere the item goes.
backlogreadyin_progressin_reviewin_qadonecancelledresolutionstringoptionalWhy it closes, for done or cancelled.
donewont_doduplicatecannot_reproducedeferredWhat it returns
{ "data": { "id": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e", "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13", "number": 142, "reference": "CRM-142", "type": "story", "parent_id": null, "epic_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d", "title": "Tier upgrade email", "description": null, "status": "in_review", "resolution": null, "priority": "high", "assignee_id": "c3d4e5f6-a7b8-4c9d-8e0f-1a2b3c4d5e6f", "assignee_name": "Nimal Fernando", "reporter_id": "d4e5f6a7-b8c9-4d0e-9f1a-2b3c4d5e6f70", "reporter_name": "Dilani Perera", "reviewer_id": null, "qa_owner_id": null, "story_points": "5", "estimate_minutes": null, "remaining_minutes": null, "due_on": "2026-11-20", "started_at": "2026-11-02T09:00:00+00:00", "completed_at": null, "persona_id": null, "as_a": "gold member", "i_want": "to be told the day I reach platinum", "so_that": "I use the new perks straight away", "business_value_points": null, "severity": null, "environment_id": null, "component_id": null, "steps_to_reproduce": null, "expected_result": null, "actual_result": null, "reproducible": null, "timebox_minutes": null, "outcome": null, "component_ids": [], "acceptance_criteria": [], "position": 3, "version": 0, "approved_at": null, "created_at": "2026-10-28T09:20:00+00:00", "updated_at": "2026-11-04T14:00:00+00:00" }}How it fails
RESOURCE_NOT_FOUNDunknown work_item_id, or an item outside the token's scope or the person's visibility.
VALIDATION_FAILEDstatus is unknown, the lifecycle does not allow the move from where the item stands, or the resolution does not fit the status (done takes done; cancelled takes any other).
TOKEN_MISSING_ABILITYtoken lacks work-item:transition.
FORBIDDENthe token holder's role on the project does not carry work-item:transition.
How is this guide?
Last updated on