update_decision
Changes a decision in part and moves it along its lifecycle when a status is sent; accepting stamps the date decided.
Change a decision by decision_id with any of title, kind (architecture, product, process, vendor or security), context (HTML), options (replaces the rows of title, pros and cons), decision (what was decided, HTML), consequences (HTML), deciders (replaces the user ids), supersedes_id and status (proposed, accepted, rejected, superseded or deprecated; a move the lifecycle allows from where the decision stands). A field left out keeps its value; a field sent as null is cleared. The fields go through the same action the Decisions page runs and write a version; decision.updated goes out. A status goes through its own move, accepting stamps the date decided, and decision.status_changed goes out. A staff token with decision: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
decision_id*stringUUID of the decision.
titlestringoptionalWhat the decision is called, 3 to 200 characters.
kindstringoptionalThe kind of decision.
architectureproductprocessvendorsecuritycontextstringoptionalThe situation and the forces at play, as HTML.
optionsarrayoptionalThe options weighed, replacing the list: objects with title, pros and cons.
decisionstringoptionalWhat was decided, as HTML.
consequencesstringoptionalWhat follows, as HTML.
decidersstring[]optionalUUIDs of the people who decided; the list replaces the current one.
supersedes_idstringoptionalUUID of the earlier decision this one replaces.
statusstringoptionalWhere the decision stands; a move the lifecycle allows.
proposedacceptedrejectedsupersededdeprecatedWhat it returns
{ "data": { "id": "d0e1f2a3-b4c5-4d6e-8f7a-8b9c0d1e2f3a", "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13", "number": 2, "reference": "SCL-DEC-2", "kind": "architecture", "title": "Take card payments through the house gateway", "context": "<p>The shop wants card payments at placement; two gateways serve Sri Lanka.</p>", "options": [ { "title": "House gateway", "pros": "Already integrated in three projects", "cons": "Higher fee on small orders" }, { "title": "Bank gateway", "pros": "Lower fee", "cons": "No sandbox, six-week onboarding" } ], "decision": "<p>The house gateway, with the sandbox first.</p>", "consequences": "<p>Fees are passed on above a threshold; the bank gateway is revisited at volume.</p>", "status": "accepted", "decided_on": "2026-11-03", "deciders": ["3f8a1c2e-7b4d-4e5f-9a6b-1c2d3e4f5a6b"], "supersedes_id": null, "supersedes_reference": null, "position": 2, "created_at": "2026-10-28T11:10:00+00:00", "updated_at": "2026-11-03T10:00:00+00:00" }}How it fails
VALIDATION_FAILEDa field outside its limits, a kind or status outside its set, an option without a title, a decider who is not on the team, a superseded decision that is not the project's, or a move the lifecycle does not allow from where the decision stands.
RESOURCE_NOT_FOUNDunknown decision_id, or a decision 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 decision:update.
TOKEN_MISSING_ABILITYtoken lacks decision:update.
How is this guide?
Last updated on