update_use_case
Changes a use case in part, replaces its steps when a list is sent and moves it where the lifecycle allows by hand.
Change a use case by use_case_id with any of title, actor_persona_id, secondary_actors (replaces the list), goal, trigger, preconditions, postconditions (HTML), frequency, priority, steps and status. A field left out keeps its value; a field sent as null is cleared. steps replaces the list in order: a row with an id keeps and changes that step, a row without one is new, and a step left out goes. The change goes through the same action the Use Cases page runs and writes a version; use_case.updated goes out. A status goes through its own move: deprecated or back to draft are moves a person may make by hand, and use_case.status_changed goes out. in_review and approved are reached through submit_for_review and the approvers, and any move is refused while an approval request is open. A staff token with use-case:update on the project is needed.
Requires ability
The token behind the MCP session must hold it, or the call is refused with TOKEN_MISSING_ABILITY.
Runs the same actions as
The REST endpoint and this tool share one action, so validation, permissions and events are identical.
Fires events
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
use_case_id*stringUUID of the use case.
titlestringoptionalWhat the use case is called, 3 to 200 characters.
actor_persona_idstringoptionalUUID of the persona who acts.
secondary_actorsstring[]optionalThe other actors in the room, in words; the list replaces the current one.
goalstringoptionalWhat the actor is trying to achieve.
triggerstringoptionalWhat starts it.
preconditionsstringoptionalWhat must be true before, as HTML.
postconditionsstringoptionalWhat is true after, as HTML.
frequencystringoptionalHow often it happens.
prioritystringoptionalIts MoSCoW priority; should by default.
mustshouldcouldwontstepsarrayoptionalThe steps replacing the list, in order: objects with actor_action (required), system_response, flow (main, alternate, exception), flow_label and branches_from; a row with an id keeps that step.
statusstringoptionalA move the lifecycle allows by hand; the review states go through submit_for_review.
draftin_reviewapproveddeprecatedWhat it returns
{ "data": { "id": "e5f6a7b8-c9d0-4e1f-8a2b-3c4d5e6f7a8b", "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13", "number": 2, "reference": "SCL-UC-2", "title": "Book a pickup", "actor_persona_id": "6f7a8b9c-0d1e-4f2a-8b3c-4d5e6f7a8b9c", "actor_persona_name": "Busy parent", "secondary_actors": ["Driver"], "goal": "Have the laundry collected from home", "trigger": "The customer has an order ready to hand over", "preconditions": "<p>The order is paid.</p>", "postconditions": "<p>A pickup slot is held and the driver's route includes the address.</p>", "frequency": "Daily", "priority": "must", "status": "draft", "steps": [ { "id": "f6a7b8c9-d0e1-4f2a-8b3c-4d5e6f7a8b9c", "use_case_id": "e5f6a7b8-c9d0-4e1f-8a2b-3c4d5e6f7a8b", "position": 1, "flow": "main", "flow_label": null, "actor_action": "Chooses a pickup slot and confirms", "system_response": "Holds the slot and sends the confirmation", "branches_from": null } ], "position": 2, "version": 2, "approved_at": null, "approved_revision_id": null, "created_at": "2026-10-28T10:50:00+00:00", "updated_at": "2026-10-28T13:15:00+00:00" }}How it fails
VALIDATION_FAILEDa field outside its limits, a priority outside MoSCoW, a persona that is not the project's, a step without an actor action, a flow outside the three, a branch from a step that does not exist, a status of in_review or approved (the message says to submit the use case for review), a move the lifecycle does not allow, or a move while a request is open.
RESOURCE_NOT_FOUNDunknown use_case_id, or a use case outside the token's scope or the person's visibility.
FORBIDDENthe token is a client guest's, or the holder's role on the project does not carry use-case:update.
TOKEN_MISSING_ABILITYtoken lacks use-case:update.
How is this guide?
Last updated on