issue_update write
Change an issue's title, description, status, priority, assignee, due date, labels, type, links or place in the project's manual order, or restore one that was soft-deleted. Omitted fields are left alone; issue_move changes the project or the milestone, and this tool changes neither. A link names another issue this one implements, supersedes, relates to or derives from; a link orders nothing, blocks nothing and may cross projects. relations replaces the whole visible set: send the links you are keeping alongside the one you are adding, pass an empty array to remove them all, and leave it out to change nothing. Only an entry with confirm: true re-confirms a stale link, and setting it says you have read the linked issue as it now stands. A change setting done or canceled is governed by the project's agent_done policy: under review it is refused with agent_done_not_allowed, and set in_review instead, the status a person reads; under allowed it goes through; under proof it fails with proof_required unless the change carries a proof object. Any token may attach proof, and the proof object's summary says what was done. An issue whose type is a document, such as spec, cannot be set done through a token under any policy: a person approves documents. Say which it was: done is for work that is finished, canceled for work that is abandoned, and comment_add leaves the reasoning where the next reader finds it. restore stands alone: call it first, then edit. A document's description follows the editing model: its owner edits a draft directly and everyone else is refused with invalid_argument and told to call proposal_create; in review the text is frozen, and once approved every change is a proposal. note records a sentence with the change, such as the reason a reviewer sent the issue back.
Arguments
| Name | Type | Description |
|---|---|---|
assignee_id | null | string | ULID of a user; read roadmap://users for the assignable ones |
clear_assignee | boolean | unassign the issue; omitting assignee_id leaves it unchanged, so removing one needs this flag |
clear_target_date | boolean | remove the due date; omitting target_date leaves it unchanged |
description | null | string | a new body |
issue required | string | an issue key like ENG-142, or a ULID |
labels | null | array | replace the labels with this set; omit to leave them alone, pass an empty array to remove them all |
note | string | a sentence recorded with this change on its event, at most 2000 characters: a send-back reason, what still needs doing, why a link was re-confirmed. A note alone is a valid update, an event holding only the note |
position | null | integer | move the issue to this place in its project's manual order, counting from 1; a value outside the range clamps to the nearest end |
priority | null | integer | how urgent the issue is: 0=none, 1=low, 2=medium, 3=high, 4=urgent One of 0, 1, 2, 3, 4. |
proof | null | object | evidence a token attaches when it finishes work under the proof policy. summary is required; links and checks are optional. Anyone may attach proof; only a token change under the proof policy is required to |
relations | null | array | replace this issue's links to other issues with this set; omit to leave them alone, pass an empty array to remove them all. A link you send again unchanged keeps its confirmation, so a stale link stays stale until its entry sets confirm. Links to deleted issues are kept and cannot be named |
restore | boolean | undo a soft delete; cannot be combined with any other change |
status | null | string | the issue's workflow state, one of: backlog, todo, in_progress, in_review, done, canceled. done and canceled are both terminal One of backlog, todo, in_progress, in_review, done, canceled. |
target_date | null | string | a new due date as YYYY-MM-DD |
title | null | string | a new one-line summary |
type | null | string | retype the issue, by key such as spec or by ULID; read roadmap://types. Every issue has exactly one type, so there is nothing to clear |
Input schema
Exactly what tools/list serves.
{
"additionalproperties": false,
"properties": {
"assignee_id": {
"description": "ULID of a user; read roadmap://users for the assignable ones",
"type": [
"null",
"string"
]
},
"clear_assignee": {
"description": "unassign the issue; omitting assignee_id leaves it unchanged, so removing one needs this flag",
"type": "boolean"
},
"clear_target_date": {
"description": "remove the due date; omitting target_date leaves it unchanged",
"type": "boolean"
},
"description": {
"description": "a new body",
"type": [
"null",
"string"
]
},
"issue": {
"description": "an issue key like ENG-142, or a ULID",
"type": "string"
},
"labels": {
"description": "replace the labels with this set; omit to leave them alone, pass an empty array to remove them all",
"items": {
"type": "string"
},
"type": [
"null",
"array"
]
},
"note": {
"description": "a sentence recorded with this change on its event, at most 2000 characters: a send-back reason, what still needs doing, why a link was re-confirmed. A note alone is a valid update, an event holding only the note",
"type": "string"
},
"position": {
"description": "move the issue to this place in its project's manual order, counting from 1; a value outside the range clamps to the nearest end",
"type": [
"null",
"integer"
]
},
"priority": {
"description": "how urgent the issue is: 0=none, 1=low, 2=medium, 3=high, 4=urgent",
"enum": [
0,
1,
2,
3,
4
],
"type": [
"null",
"integer"
]
},
"proof": {
"additionalproperties": false,
"description": "evidence a token attaches when it finishes work under the proof policy. summary is required; links and checks are optional. Anyone may attach proof; only a token change under the proof policy is required to",
"properties": {
"checks": {
"description": "checks that were run, with their results",
"items": {
"type": "string"
},
"type": [
"null",
"array"
]
},
"links": {
"description": "links to evidence; never fetched, evidence for a person to spot-check",
"items": {
"type": "string"
},
"type": [
"null",
"array"
]
},
"summary": {
"description": "a short summary of what was done; required",
"type": "string"
}
},
"required": [
"summary"
],
"type": [
"null",
"object"
]
},
"relations": {
"description": "replace this issue's links to other issues with this set; omit to leave them alone, pass an empty array to remove them all. A link you send again unchanged keeps its confirmation, so a stale link stays stale until its entry sets confirm. Links to deleted issues are kept and cannot be named",
"items": {
"additionalproperties": false,
"properties": {
"confirm": {
"description": "true to confirm that you read the linked issue as it is now, which clears a stale link. Only this does; issue_get never returns it, so writing links_out back confirms nothing",
"type": "boolean"
},
"issue": {
"description": "the issue this one links to: a key like ENG-142, or a ULID. It may be in another project",
"type": "string"
},
"kind": {
"description": "what this issue is to the linked one, one of: implements, supersedes, relates, derives_from. implements points a piece of work at the document it carries out; supersedes replaces an older document; relates is anything else; derives_from names a document's provenance - the PRD a spec enumerates, the spec a task's list comes from. No kind blocks, orders or nests issues",
"enum": [
"implements",
"supersedes",
"relates",
"derives_from"
],
"type": "string"
}
},
"required": [
"issue",
"kind"
],
"type": "object"
},
"type": [
"null",
"array"
]
},
"restore": {
"description": "undo a soft delete; cannot be combined with any other change",
"type": "boolean"
},
"status": {
"description": "the issue's workflow state, one of: backlog, todo, in_progress, in_review, done, canceled. done and canceled are both terminal",
"enum": [
"backlog",
"todo",
"in_progress",
"in_review",
"done",
"canceled"
],
"type": [
"null",
"string"
]
},
"target_date": {
"description": "a new due date as YYYY-MM-DD",
"type": [
"null",
"string"
]
},
"title": {
"description": "a new one-line summary",
"type": [
"null",
"string"
]
},
"type": {
"description": "retype the issue, by key such as spec or by ULID; read roadmap://types. Every issue has exactly one type, so there is nothing to clear",
"type": [
"null",
"string"
]
}
},
"required": [
"issue"
],
"type": "object"
}