commentDiscuss on a node. action = add | update | resolve (mark a thread settled) | delete (soft tombstone; replies are preserved). Replies are one level deep: reply to a top-level comment only. Read a node's comments with list(what="comments").
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||
| Name | Required | Description | Default |
|---|---|---|---|
| data | Yes | The action-specific result returned by Stele. | |
| action | Yes | The action that produced this result. |
Changes observed during successful MCP inspections.
Input schema / anyOfPrevious value: -[
- {
- "additionalProperties": false,
- "description": "action=\"add\": Leave a comment on any node — the human↔agent steering channel; the next agent that reads the node sees it flagged unseen. Reply by passing parent_comment_id (replies are one level deep). Pass `anchor` to attach to a quoted span (inline comment); omit for node-level. Commenting watches the node, so future comments on it show as unread to you.",
- "properties": {
- "action": {
- "const": "add",
- "type": "string"
- },
- "anchor": {
- "additionalProperties": false,
- "description": "(add only) Attach the comment to a quoted span of the node's body (per-line / inline comment). Omit for a node-level comment. Anchored to TEXT, never line numbers: on a later edit the quote is relocated; if it vanishes the comment goes 'outdated' (never deleted).",
- "properties": {
- "node_version": {
- "description": "The node `version` the quote was taken from, as returned when you fetched the node.",
- "exclusiveMinimum": 0,
- "type": "integer"
- },
- "offset": {
- "description": "Rough char offset to disambiguate a repeated quote.",
- "minimum": 0,
- "type": "integer"
- },
- "quote": {
- "description": "The exact quoted substring to attach the comment to.",
- "minLength": 1,
- "type": "string"
- }
- },
- "required": [
- "node_version",
- "quote"
- ],
- "type": "object"
- },
- "body": {
- "description": "REQUIRED for add/update — comment text (markdown).",
- "minLength": 1,
- "type": "string"
- },
- "node_id": {
- "description": "REQUIRED for add — the node to comment on (any node type).",
- "type": "string"
- },
- "parent_comment_id": {
- "description": "(add only) Reply target — the comment_id of a TOP-LEVEL comment. Replies are one level deep; replying to a reply is rejected.",
- "format": "uuid",
- "type": "string"
- },
- "privacy_bypass": {
- "description": "true writes despite a privacy flag. Only meaningful after a flag; the user decides whether the content can be written.",
- "type": "boolean"
- },
- "privacy_false_positive": {
- "description": "With privacy_bypass: true reports the privacy flag as wrong.",
- "type": "boolean"
- },
- "privacy_judgement_id": {
- "description": "With privacy_bypass: the judgement_id the privacy flag returned.",
- "type": "string"
- },
- "privacy_note": {
- "description": "With privacy_bypass: an optional short reason, kept with the bypass.",
- "maxLength": 500,
- "type": "string"
- },
- "project_slug": {
- "description": "Project slug, e.g. \"acme-app\" — list(what=\"projects\") returns yours.",
- "minLength": 1,
- "type": "string"
- }
- },
- "required": [
- "action",
- "project_slug",
- "node_id",
- "body"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "description": "action=\"update\": Edit the body of a comment you authored. AUTHOR-ONLY. Sets the 'edited' marker and does not re-flag the comment unread for others.",
- "properties": {
- "action": {
- "const": "update",
- "type": "string"
- },
- "body": {
- "description": "New comment text.",
- "minLength": 1,
- "type": "string"
- },
- "comment_id": {
- "description": "REQUIRED for update/resolve/delete — the comment_id to act on.",
- "format": "uuid",
- "type": "string"
- },
- "privacy_bypass": {
- "description": "true writes despite a privacy flag. Only meaningful after a flag; the user decides whether the content can be written.",
- "type": "boolean"
- },
- "privacy_false_positive": {
- "description": "With privacy_bypass: true reports the privacy flag as wrong.",
- "type": "boolean"
- },
- "privacy_judgement_id": {
- "description": "With privacy_bypass: the judgement_id the privacy flag returned.",
- "type": "string"
- },
- "privacy_note": {
- "description": "With privacy_bypass: an optional short reason, kept with the bypass.",
- "maxLength": 500,
- "type": "string"
- },
- "project_slug": {
- "description": "Project slug, e.g. \"acme-app\" — list(what=\"projects\") returns yours.",
- "minLength": 1,
- "type": "string"
- }
- },
- "required": [
- "action",
- "project_slug",
- "comment_id",
- "body"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "description": "action=\"resolve\": Resolve (or reopen) a comment thread. ANY project member may do this, not just the author. Resolve a steering comment once addressed so it stops nagging the next agent — resolved threads drop out of the [N comments, M unread] marker. Applies to the whole thread (resolving a reply resolves its parent).",
- "properties": {
- "action": {
- "const": "resolve",
- "type": "string"
- },
- "comment_id": {
- "description": "A comment_id in the thread (top-level or a reply).",
- "format": "uuid",
- "type": "string"
- },
- "project_slug": {
- "description": "Project slug, e.g. \"acme-app\" — list(what=\"projects\") returns yours.",
- "minLength": 1,
- "type": "string"
- },
- "resolved": {
- "description": "REQUIRED for resolve — true to resolve the thread, false to reopen it.",
- "type": "boolean"
- }
- },
- "required": [
- "action",
- "project_slug",
- "comment_id",
- "resolved"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "description": "action=\"delete\": Soft-delete a comment you authored — the row stays as a tombstone and replies remain intact (never orphaned). AUTHOR-ONLY; there is no hard delete.",
- "properties": {
- "action": {
- "const": "delete",
- "type": "string"
- },
- "comment_id": {
- "description": "The comment_id to delete.",
- "format": "uuid",
- "type": "string"
- },
- "project_slug": {
- "description": "Project slug, e.g. \"acme-app\" — list(what=\"projects\") returns yours.",
- "minLength": 1,
- "type": "string"
- }
- },
- "required": [
- "action",
- "project_slug",
- "comment_id"
- ],
- "type": "object"
- }
-]New value: +[
+ {
+ "additionalProperties": false,
+ "description": "comment action \"add\".",
+ "properties": {
+ "action": {
+ "const": "add",
+ "description": "Run the add action.",
+ "type": "string"
+ },
+ "anchor": {
+ "additionalProperties": false,
+ "description": "(add only) Attach the comment to a quoted span of the node's body (per-line / inline comment). Omit for a node-level comment. Anchored to TEXT, never line numbers: on a later edit the quote is relocated; if it vanishes the comment goes 'outdated' (never deleted).",
+ "properties": {
+ "node_version": {
+ "description": "The node `version` the quote was taken from, as returned when you fetched the node.",
+ "exclusiveMinimum": 0,
+ "type": "integer"
+ },
+ "offset": {
+ "description": "Rough char offset to disambiguate a repeated quote.",
+ "minimum": 0,
+ "type": "integer"
+ },
+ "quote": {
+ "description": "The exact quoted substring to attach the comment to.",
+ "minLength": 1,
+ "type": "string"
+ }
+ },
+ "required": [
+ "node_version",
+ "quote"
+ ],
+ "type": "object"
+ },
+ "body": {
+ "description": "REQUIRED for add/update — comment text (markdown).",
+ "minLength": 1,
+ "type": "string"
+ },
+ "node_id": {
+ "description": "REQUIRED for add — the node to comment on (any node type).",
+ "type": "string"
+ },
+ "parent_comment_id": {
+ "description": "(add only) Reply target — the comment_id of a TOP-LEVEL comment. Replies are one level deep; replying to a reply is rejected.",
+ "format": "uuid",
+ "type": "string"
+ },
+ "privacy_bypass": {
+ "description": "true writes despite a privacy flag. Only meaningful after a flag; the user decides whether the content can be written.",
+ "type": "boolean"
+ },
+ "privacy_false_positive": {
+ "description": "With privacy_bypass: true reports the privacy flag as wrong.",
+ "type": "boolean"
+ },
+ "privacy_judgement_id": {
+ "description": "With privacy_bypass: the judgement_id the privacy flag returned.",
+ "type": "string"
+ },
+ "privacy_note": {
+ "description": "With privacy_bypass: an optional short reason, kept with the bypass.",
+ "maxLength": 500,
+ "type": "string"
+ },
+ "project_slug": {
+ "description": "Project slug, e.g. \"acme-app\" — list(what=\"projects\") returns yours.",
+ "minLength": 1,
+ "type": "string"
+ }
+ },
+ "required": [
+ "action",
+ "project_slug",
+ "node_id",
+ "body"
+ ],
+ "type": "object"
+ },
+ {
+ "additionalProperties": false,
+ "description": "comment action \"update\".",
+ "properties": {
+ "action": {
+ "const": "update",
+ "description": "Run the update action.",
+ "type": "string"
+ },
+ "body": {
+ "description": "New comment text.",
+ "minLength": 1,
+ "type": "string"
+ },
+ "comment_id": {
+ "description": "REQUIRED for update/resolve/delete — the comment_id to act on.",
+ "format": "uuid",
+ "type": "string"
+ },
+ "privacy_bypass": {
+ "description": "true writes despite a privacy flag. Only meaningful after a flag; the user decides whether the content can be written.",
+ "type": "boolean"
+ },
+ "privacy_false_positive": {
+ "description": "With privacy_bypass: true reports the privacy flag as wrong.",
+ "type": "boolean"
+ },
+ "privacy_judgement_id": {
+ "description": "With privacy_bypass: the judgement_id the privacy flag returned.",
+ "type": "string"
+ },
+ "privacy_note": {
+ "description": "With privacy_bypass: an optional short reason, kept with the bypass.",
+ "maxLength": 500,
+ "type": "string"
+ },
+ "project_slug": {
+ "description": "Project slug, e.g. \"acme-app\" — list(what=\"projects\") returns yours.",
+ "minLength": 1,
+ "type": "string"
+ }
+ },
+ "required": [
+ "action",
+ "project_slug",
+ "comment_id",
+ "body"
+ ],
+ "type": "object"
+ },
+ {
+ "additionalProperties": false,
+ "description": "comment action \"resolve\".",
+ "properties": {
+ "action": {
+ "const": "resolve",
+ "description": "Run the resolve action.",
+ "type": "string"
+ },
+ "comment_id": {
+ "description": "A comment_id in the thread (top-level or a reply).",
+ "format": "uuid",
+ "type": "string"
+ },
+ "project_slug": {
+ "description": "Project slug, e.g. \"acme-app\" — list(what=\"projects\") returns yours.",
+ "minLength": 1,
+ "type": "string"
+ },
+ "resolved": {
+ "description": "REQUIRED for resolve — true to resolve the thread, false to reopen it.",
+ "type": "boolean"
+ }
+ },
+ "required": [
+ "action",
+ "project_slug",
+ "comment_id",
+ "resolved"
+ ],
+ "type": "object"
+ },
+ {
+ "additionalProperties": false,
+ "description": "comment action \"delete\".",
+ "properties": {
+ "action": {
+ "const": "delete",
+ "description": "Run the delete action.",
+ "type": "string"
+ },
+ "comment_id": {
+ "description": "The comment_id to delete.",
+ "format": "uuid",
+ "type": "string"
+ },
+ "project_slug": {
+ "description": "Project slug, e.g. \"acme-app\" — list(what=\"projects\") returns yours.",
+ "minLength": 1,
+ "type": "string"
+ }
+ },
+ "required": [
+ "action",
+ "project_slug",
+ "comment_id"
+ ],
+ "type": "object"
+ }
+]Input schema / anyOfPrevious value: -[
- {
- "additionalProperties": false,
- "description": "action=\"add\": Leave a comment on any node — the human↔agent steering channel; the next agent that reads the node sees it flagged unseen. Reply by passing parent_comment_id (replies are one level deep). Pass `anchor` to attach to a quoted span (inline comment); omit for node-level. Commenting watches the node, so future comments on it show as unread to you.",
- "properties": {
- "action": {
- "const": "add",
- "type": "string"
- },
- "anchor": {
- "additionalProperties": false,
- "description": "(add only) Attach the comment to a quoted span of the node's body (per-line / inline comment). Omit for a node-level comment. Anchored to TEXT, never line numbers: on a later edit the quote is relocated; if it vanishes the comment goes 'outdated' (never deleted).",
- "properties": {
- "node_version": {
- "description": "The node `version` the quote was taken from, as returned when you fetched the node.",
- "exclusiveMinimum": 0,
- "type": "integer"
- },
- "offset": {
- "description": "Rough char offset to disambiguate a repeated quote.",
- "minimum": 0,
- "type": "integer"
- },
- "quote": {
- "description": "The exact quoted substring to attach the comment to.",
- "minLength": 1,
- "type": "string"
- }
- },
- "required": [
- "node_version",
- "quote"
- ],
- "type": "object"
- },
- "body": {
- "description": "REQUIRED for add/update — comment text (markdown).",
- "minLength": 1,
- "type": "string"
- },
- "node_id": {
- "description": "REQUIRED for add — the node to comment on (any node type).",
- "type": "string"
- },
- "parent_comment_id": {
- "description": "(add only) Reply target — the comment_id of a TOP-LEVEL comment. Replies are one level deep; replying to a reply is rejected.",
- "format": "uuid",
- "type": "string"
- },
- "privacy_bypass": {
- "description": "true writes despite a privacy flag on a public project. Only meaningful after a flag; the user decides whether the content can be public.",
- "type": "boolean"
- },
- "privacy_false_positive": {
- "description": "With privacy_bypass: true reports the privacy flag as wrong.",
- "type": "boolean"
- },
- "privacy_judgement_id": {
- "description": "With privacy_bypass: the judgement_id the privacy flag returned.",
- "type": "string"
- },
- "privacy_note": {
- "description": "With privacy_bypass: an optional short reason, kept with the bypass.",
- "maxLength": 500,
- "type": "string"
- },
- "project_slug": {
- "description": "Project slug, e.g. \"acme-app\" — list(what=\"projects\") returns yours.",
- "minLength": 1,
- "type": "string"
- }
- },
- "required": [
- "action",
- "project_slug",
- "node_id",
- "body"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "description": "action=\"update\": Edit the body of a comment you authored. AUTHOR-ONLY. Sets the 'edited' marker and does not re-flag the comment unread for others.",
- "properties": {
- "action": {
- "const": "update",
- "type": "string"
- },
- "body": {
- "description": "New comment text.",
- "minLength": 1,
- "type": "string"
- },
- "comment_id": {
- "description": "REQUIRED for update/resolve/delete — the comment_id to act on.",
- "format": "uuid",
- "type": "string"
- },
- "privacy_bypass": {
- "description": "true writes despite a privacy flag on a public project. Only meaningful after a flag; the user decides whether the content can be public.",
- "type": "boolean"
- },
- "privacy_false_positive": {
- "description": "With privacy_bypass: true reports the privacy flag as wrong.",
- "type": "boolean"
- },
- "privacy_judgement_id": {
- "description": "With privacy_bypass: the judgement_id the privacy flag returned.",
- "type": "string"
- },
- "privacy_note": {
- "description": "With privacy_bypass: an optional short reason, kept with the bypass.",
- "maxLength": 500,
- "type": "string"
- },
- "project_slug": {
- "description": "Project slug, e.g. \"acme-app\" — list(what=\"projects\") returns yours.",
- "minLength": 1,
- "type": "string"
- }
- },
- "required": [
- "action",
- "project_slug",
- "comment_id",
- "body"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "description": "action=\"resolve\": Resolve (or reopen) a comment thread. ANY project member may do this, not just the author. Resolve a steering comment once addressed so it stops nagging the next agent — resolved threads drop out of the [N comments, M unread] marker. Applies to the whole thread (resolving a reply resolves its parent).",
- "properties": {
- "action": {
- "const": "resolve",
- "type": "string"
- },
- "comment_id": {
- "description": "A comment_id in the thread (top-level or a reply).",
- "format": "uuid",
- "type": "string"
- },
- "project_slug": {
- "description": "Project slug, e.g. \"acme-app\" — list(what=\"projects\") returns yours.",
- "minLength": 1,
- "type": "string"
- },
- "resolved": {
- "description": "REQUIRED for resolve — true to resolve the thread, false to reopen it.",
- "type": "boolean"
- }
- },
- "required": [
- "action",
- "project_slug",
- "comment_id",
- "resolved"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "description": "action=\"delete\": Soft-delete a comment you authored — the row stays as a tombstone and replies remain intact (never orphaned). AUTHOR-ONLY; there is no hard delete.",
- "properties": {
- "action": {
- "const": "delete",
- "type": "string"
- },
- "comment_id": {
- "description": "The comment_id to delete.",
- "format": "uuid",
- "type": "string"
- },
- "project_slug": {
- "description": "Project slug, e.g. \"acme-app\" — list(what=\"projects\") returns yours.",
- "minLength": 1,
- "type": "string"
- }
- },
- "required": [
- "action",
- "project_slug",
- "comment_id"
- ],
- "type": "object"
- }
-]New value: +[
+ {
+ "additionalProperties": false,
+ "description": "action=\"add\": Leave a comment on any node — the human↔agent steering channel; the next agent that reads the node sees it flagged unseen. Reply by passing parent_comment_id (replies are one level deep). Pass `anchor` to attach to a quoted span (inline comment); omit for node-level. Commenting watches the node, so future comments on it show as unread to you.",
+ "properties": {
+ "action": {
+ "const": "add",
+ "type": "string"
+ },
+ "anchor": {
+ "additionalProperties": false,
+ "description": "(add only) Attach the comment to a quoted span of the node's body (per-line / inline comment). Omit for a node-level comment. Anchored to TEXT, never line numbers: on a later edit the quote is relocated; if it vanishes the comment goes 'outdated' (never deleted).",
+ "properties": {
+ "node_version": {
+ "description": "The node `version` the quote was taken from, as returned when you fetched the node.",
+ "exclusiveMinimum": 0,
+ "type": "integer"
+ },
+ "offset": {
+ "description": "Rough char offset to disambiguate a repeated quote.",
+ "minimum": 0,
+ "type": "integer"
+ },
+ "quote": {
+ "description": "The exact quoted substring to attach the comment to.",
+ "minLength": 1,
+ "type": "string"
+ }
+ },
+ "required": [
+ "node_version",
+ "quote"
+ ],
+ "type": "object"
+ },
+ "body": {
+ "description": "REQUIRED for add/update — comment text (markdown).",
+ "minLength": 1,
+ "type": "string"
+ },
+ "node_id": {
+ "description": "REQUIRED for add — the node to comment on (any node type).",
+ "type": "string"
+ },
+ "parent_comment_id": {
+ "description": "(add only) Reply target — the comment_id of a TOP-LEVEL comment. Replies are one level deep; replying to a reply is rejected.",
+ "format": "uuid",
+ "type": "string"
+ },
+ "privacy_bypass": {
+ "description": "true writes despite a privacy flag. Only meaningful after a flag; the user decides whether the content can be written.",
+ "type": "boolean"
+ },
+ "privacy_false_positive": {
+ "description": "With privacy_bypass: true reports the privacy flag as wrong.",
+ "type": "boolean"
+ },
+ "privacy_judgement_id": {
+ "description": "With privacy_bypass: the judgement_id the privacy flag returned.",
+ "type": "string"
+ },
+ "privacy_note": {
+ "description": "With privacy_bypass: an optional short reason, kept with the bypass.",
+ "maxLength": 500,
+ "type": "string"
+ },
+ "project_slug": {
+ "description": "Project slug, e.g. \"acme-app\" — list(what=\"projects\") returns yours.",
+ "minLength": 1,
+ "type": "string"
+ }
+ },
+ "required": [
+ "action",
+ "project_slug",
+ "node_id",
+ "body"
+ ],
+ "type": "object"
+ },
+ {
+ "additionalProperties": false,
+ "description": "action=\"update\": Edit the body of a comment you authored. AUTHOR-ONLY. Sets the 'edited' marker and does not re-flag the comment unread for others.",
+ "properties": {
+ "action": {
+ "const": "update",
+ "type": "string"
+ },
+ "body": {
+ "description": "New comment text.",
+ "minLength": 1,
+ "type": "string"
+ },
+ "comment_id": {
+ "description": "REQUIRED for update/resolve/delete — the comment_id to act on.",
+ "format": "uuid",
+ "type": "string"
+ },
+ "privacy_bypass": {
+ "description": "true writes despite a privacy flag. Only meaningful after a flag; the user decides whether the content can be written.",
+ "type": "boolean"
+ },
+ "privacy_false_positive": {
+ "description": "With privacy_bypass: true reports the privacy flag as wrong.",
+ "type": "boolean"
+ },
+ "privacy_judgement_id": {
+ "description": "With privacy_bypass: the judgement_id the privacy flag returned.",
+ "type": "string"
+ },
+ "privacy_note": {
+ "description": "With privacy_bypass: an optional short reason, kept with the bypass.",
+ "maxLength": 500,
+ "type": "string"
+ },
+ "project_slug": {
+ "description": "Project slug, e.g. \"acme-app\" — list(what=\"projects\") returns yours.",
+ "minLength": 1,
+ "type": "string"
+ }
+ },
+ "required": [
+ "action",
+ "project_slug",
+ "comment_id",
+ "body"
+ ],
+ "type": "object"
+ },
+ {
+ "additionalProperties": false,
+ "description": "action=\"resolve\": Resolve (or reopen) a comment thread. ANY project member may do this, not just the author. Resolve a steering comment once addressed so it stops nagging the next agent — resolved threads drop out of the [N comments, M unread] marker. Applies to the whole thread (resolving a reply resolves its parent).",
+ "properties": {
+ "action": {
+ "const": "resolve",
+ "type": "string"
+ },
+ "comment_id": {
+ "description": "A comment_id in the thread (top-level or a reply).",
+ "format": "uuid",
+ "type": "string"
+ },
+ "project_slug": {
+ "description": "Project slug, e.g. \"acme-app\" — list(what=\"projects\") returns yours.",
+ "minLength": 1,
+ "type": "string"
+ },
+ "resolved": {
+ "description": "REQUIRED for resolve — true to resolve the thread, false to reopen it.",
+ "type": "boolean"
+ }
+ },
+ "required": [
+ "action",
+ "project_slug",
+ "comment_id",
+ "resolved"
+ ],
+ "type": "object"
+ },
+ {
+ "additionalProperties": false,
+ "description": "action=\"delete\": Soft-delete a comment you authored — the row stays as a tombstone and replies remain intact (never orphaned). AUTHOR-ONLY; there is no hard delete.",
+ "properties": {
+ "action": {
+ "const": "delete",
+ "type": "string"
+ },
+ "comment_id": {
+ "description": "The comment_id to delete.",
+ "format": "uuid",
+ "type": "string"
+ },
+ "project_slug": {
+ "description": "Project slug, e.g. \"acme-app\" — list(what=\"projects\") returns yours.",
+ "minLength": 1,
+ "type": "string"
+ }
+ },
+ "required": [
+ "action",
+ "project_slug",
+ "comment_id"
+ ],
+ "type": "object"
+ }
+]Input schema / anyOfPrevious value: -[
- {
- "additionalProperties": false,
- "description": "action=\"add\": Leave a comment on any node — the human↔agent steering channel; the next agent that reads the node sees it flagged unseen. Reply by passing parent_comment_id (replies are one level deep). Pass `anchor` to attach to a quoted span (inline comment); omit for node-level. Commenting watches the node, so future comments on it show as unread to you.",
- "properties": {
- "action": {
- "const": "add",
- "type": "string"
- },
- "anchor": {
- "additionalProperties": false,
- "description": "(add only) Attach the comment to a quoted span of the node's body (per-line / inline comment). Omit for a node-level comment. Anchored to TEXT, never line numbers: on a later edit the quote is relocated; if it vanishes the comment goes 'outdated' (never deleted).",
- "properties": {
- "node_version": {
- "description": "The node `version` the quote was taken from, as returned when you fetched the node.",
- "exclusiveMinimum": 0,
- "type": "integer"
- },
- "offset": {
- "description": "Rough char offset to disambiguate a repeated quote.",
- "minimum": 0,
- "type": "integer"
- },
- "quote": {
- "description": "The exact quoted substring to attach the comment to.",
- "minLength": 1,
- "type": "string"
- }
- },
- "required": [
- "node_version",
- "quote"
- ],
- "type": "object"
- },
- "body": {
- "description": "REQUIRED for add/update — comment text (markdown).",
- "minLength": 1,
- "type": "string"
- },
- "node_id": {
- "description": "REQUIRED for add — the node to comment on (any node type).",
- "type": "string"
- },
- "parent_comment_id": {
- "description": "(add only) Reply target — the comment_id of a TOP-LEVEL comment. Replies are one level deep; replying to a reply is rejected.",
- "format": "uuid",
- "type": "string"
- },
- "project_slug": {
- "description": "Project slug, e.g. \"acme-app\" — list(what=\"projects\") returns yours.",
- "minLength": 1,
- "type": "string"
- }
- },
- "required": [
- "action",
- "project_slug",
- "node_id",
- "body"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "description": "action=\"update\": Edit the body of a comment you authored. AUTHOR-ONLY. Sets the 'edited' marker and does not re-flag the comment unread for others.",
- "properties": {
- "action": {
- "const": "update",
- "type": "string"
- },
- "body": {
- "description": "New comment text.",
- "minLength": 1,
- "type": "string"
- },
- "comment_id": {
- "description": "REQUIRED for update/resolve/delete — the comment_id to act on.",
- "format": "uuid",
- "type": "string"
- },
- "project_slug": {
- "description": "Project slug, e.g. \"acme-app\" — list(what=\"projects\") returns yours.",
- "minLength": 1,
- "type": "string"
- }
- },
- "required": [
- "action",
- "project_slug",
- "comment_id",
- "body"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "description": "action=\"resolve\": Resolve (or reopen) a comment thread. ANY project member may do this, not just the author. Resolve a steering comment once addressed so it stops nagging the next agent — resolved threads drop out of the [N comments, M unread] marker. Applies to the whole thread (resolving a reply resolves its parent).",
- "properties": {
- "action": {
- "const": "resolve",
- "type": "string"
- },
- "comment_id": {
- "description": "A comment_id in the thread (top-level or a reply).",
- "format": "uuid",
- "type": "string"
- },
- "project_slug": {
- "description": "Project slug, e.g. \"acme-app\" — list(what=\"projects\") returns yours.",
- "minLength": 1,
- "type": "string"
- },
- "resolved": {
- "description": "REQUIRED for resolve — true to resolve the thread, false to reopen it.",
- "type": "boolean"
- }
- },
- "required": [
- "action",
- "project_slug",
- "comment_id",
- "resolved"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "description": "action=\"delete\": Soft-delete a comment you authored — the row stays as a tombstone and replies remain intact (never orphaned). AUTHOR-ONLY; there is no hard delete.",
- "properties": {
- "action": {
- "const": "delete",
- "type": "string"
- },
- "comment_id": {
- "description": "The comment_id to delete.",
- "format": "uuid",
- "type": "string"
- },
- "project_slug": {
- "description": "Project slug, e.g. \"acme-app\" — list(what=\"projects\") returns yours.",
- "minLength": 1,
- "type": "string"
- }
- },
- "required": [
- "action",
- "project_slug",
- "comment_id"
- ],
- "type": "object"
- }
-]New value: +[
+ {
+ "additionalProperties": false,
+ "description": "action=\"add\": Leave a comment on any node — the human↔agent steering channel; the next agent that reads the node sees it flagged unseen. Reply by passing parent_comment_id (replies are one level deep). Pass `anchor` to attach to a quoted span (inline comment); omit for node-level. Commenting watches the node, so future comments on it show as unread to you.",
+ "properties": {
+ "action": {
+ "const": "add",
+ "type": "string"
+ },
+ "anchor": {
+ "additionalProperties": false,
+ "description": "(add only) Attach the comment to a quoted span of the node's body (per-line / inline comment). Omit for a node-level comment. Anchored to TEXT, never line numbers: on a later edit the quote is relocated; if it vanishes the comment goes 'outdated' (never deleted).",
+ "properties": {
+ "node_version": {
+ "description": "The node `version` the quote was taken from, as returned when you fetched the node.",
+ "exclusiveMinimum": 0,
+ "type": "integer"
+ },
+ "offset": {
+ "description": "Rough char offset to disambiguate a repeated quote.",
+ "minimum": 0,
+ "type": "integer"
+ },
+ "quote": {
+ "description": "The exact quoted substring to attach the comment to.",
+ "minLength": 1,
+ "type": "string"
+ }
+ },
+ "required": [
+ "node_version",
+ "quote"
+ ],
+ "type": "object"
+ },
+ "body": {
+ "description": "REQUIRED for add/update — comment text (markdown).",
+ "minLength": 1,
+ "type": "string"
+ },
+ "node_id": {
+ "description": "REQUIRED for add — the node to comment on (any node type).",
+ "type": "string"
+ },
+ "parent_comment_id": {
+ "description": "(add only) Reply target — the comment_id of a TOP-LEVEL comment. Replies are one level deep; replying to a reply is rejected.",
+ "format": "uuid",
+ "type": "string"
+ },
+ "privacy_bypass": {
+ "description": "true writes despite a privacy flag on a public project. Only meaningful after a flag; the user decides whether the content can be public.",
+ "type": "boolean"
+ },
+ "privacy_false_positive": {
+ "description": "With privacy_bypass: true reports the privacy flag as wrong.",
+ "type": "boolean"
+ },
+ "privacy_judgement_id": {
+ "description": "With privacy_bypass: the judgement_id the privacy flag returned.",
+ "type": "string"
+ },
+ "privacy_note": {
+ "description": "With privacy_bypass: an optional short reason, kept with the bypass.",
+ "maxLength": 500,
+ "type": "string"
+ },
+ "project_slug": {
+ "description": "Project slug, e.g. \"acme-app\" — list(what=\"projects\") returns yours.",
+ "minLength": 1,
+ "type": "string"
+ }
+ },
+ "required": [
+ "action",
+ "project_slug",
+ "node_id",
+ "body"
+ ],
+ "type": "object"
+ },
+ {
+ "additionalProperties": false,
+ "description": "action=\"update\": Edit the body of a comment you authored. AUTHOR-ONLY. Sets the 'edited' marker and does not re-flag the comment unread for others.",
+ "properties": {
+ "action": {
+ "const": "update",
+ "type": "string"
+ },
+ "body": {
+ "description": "New comment text.",
+ "minLength": 1,
+ "type": "string"
+ },
+ "comment_id": {
+ "description": "REQUIRED for update/resolve/delete — the comment_id to act on.",
+ "format": "uuid",
+ "type": "string"
+ },
+ "privacy_bypass": {
+ "description": "true writes despite a privacy flag on a public project. Only meaningful after a flag; the user decides whether the content can be public.",
+ "type": "boolean"
+ },
+ "privacy_false_positive": {
+ "description": "With privacy_bypass: true reports the privacy flag as wrong.",
+ "type": "boolean"
+ },
+ "privacy_judgement_id": {
+ "description": "With privacy_bypass: the judgement_id the privacy flag returned.",
+ "type": "string"
+ },
+ "privacy_note": {
+ "description": "With privacy_bypass: an optional short reason, kept with the bypass.",
+ "maxLength": 500,
+ "type": "string"
+ },
+ "project_slug": {
+ "description": "Project slug, e.g. \"acme-app\" — list(what=\"projects\") returns yours.",
+ "minLength": 1,
+ "type": "string"
+ }
+ },
+ "required": [
+ "action",
+ "project_slug",
+ "comment_id",
+ "body"
+ ],
+ "type": "object"
+ },
+ {
+ "additionalProperties": false,
+ "description": "action=\"resolve\": Resolve (or reopen) a comment thread. ANY project member may do this, not just the author. Resolve a steering comment once addressed so it stops nagging the next agent — resolved threads drop out of the [N comments, M unread] marker. Applies to the whole thread (resolving a reply resolves its parent).",
+ "properties": {
+ "action": {
+ "const": "resolve",
+ "type": "string"
+ },
+ "comment_id": {
+ "description": "A comment_id in the thread (top-level or a reply).",
+ "format": "uuid",
+ "type": "string"
+ },
+ "project_slug": {
+ "description": "Project slug, e.g. \"acme-app\" — list(what=\"projects\") returns yours.",
+ "minLength": 1,
+ "type": "string"
+ },
+ "resolved": {
+ "description": "REQUIRED for resolve — true to resolve the thread, false to reopen it.",
+ "type": "boolean"
+ }
+ },
+ "required": [
+ "action",
+ "project_slug",
+ "comment_id",
+ "resolved"
+ ],
+ "type": "object"
+ },
+ {
+ "additionalProperties": false,
+ "description": "action=\"delete\": Soft-delete a comment you authored — the row stays as a tombstone and replies remain intact (never orphaned). AUTHOR-ONLY; there is no hard delete.",
+ "properties": {
+ "action": {
+ "const": "delete",
+ "type": "string"
+ },
+ "comment_id": {
+ "description": "The comment_id to delete.",
+ "format": "uuid",
+ "type": "string"
+ },
+ "project_slug": {
+ "description": "Project slug, e.g. \"acme-app\" — list(what=\"projects\") returns yours.",
+ "minLength": 1,
+ "type": "string"
+ }
+ },
+ "required": [
+ "action",
+ "project_slug",
+ "comment_id"
+ ],
+ "type": "object"
+ }
+]Input schema / anyOfPrevious value: -[
- {
- "additionalProperties": false,
- "description": "comment action \"add\".",
- "properties": {
- "action": {
- "const": "add",
- "description": "Run the add action.",
- "type": "string"
- },
- "anchor": {
- "additionalProperties": false,
- "description": "(add only) Attach the comment to a quoted span of the node's body (per-line / inline comment). Omit for a node-level comment. Anchored to TEXT, never line numbers: on a later edit the quote is relocated; if it vanishes the comment goes 'outdated' (never deleted).",
- "properties": {
- "node_version": {
- "description": "The node `version` the quote was taken from (from get_node).",
- "exclusiveMinimum": 0,
- "type": "integer"
- },
- "offset": {
- "description": "Rough char offset to disambiguate a repeated quote.",
- "minimum": 0,
- "type": "integer"
- },
- "quote": {
- "description": "The exact quoted substring to attach the comment to.",
- "minLength": 1,
- "type": "string"
- }
- },
- "required": [
- "node_version",
- "quote"
- ],
- "type": "object"
- },
- "body": {
- "description": "REQUIRED for add/update — comment text (markdown).",
- "minLength": 1,
- "type": "string"
- },
- "node_id": {
- "description": "REQUIRED for add — the node to comment on (any node type).",
- "type": "string"
- },
- "parent_comment_id": {
- "description": "(add only) Reply target — the comment_id of a TOP-LEVEL comment. Replies are one level deep; replying to a reply is rejected.",
- "format": "uuid",
- "type": "string"
- },
- "project_slug": {
- "description": "Project slug, e.g. \"acme-app\" — list(what=\"projects\") returns yours.",
- "minLength": 1,
- "type": "string"
- }
- },
- "required": [
- "action",
- "project_slug",
- "node_id",
- "body"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "description": "comment action \"update\".",
- "properties": {
- "action": {
- "const": "update",
- "description": "Run the update action.",
- "type": "string"
- },
- "body": {
- "description": "New comment text.",
- "minLength": 1,
- "type": "string"
- },
- "comment_id": {
- "description": "REQUIRED for update/resolve/delete — the comment_id to act on.",
- "format": "uuid",
- "type": "string"
- },
- "project_slug": {
- "description": "Project slug, e.g. \"acme-app\" — list(what=\"projects\") returns yours.",
- "minLength": 1,
- "type": "string"
- }
- },
- "required": [
- "action",
- "project_slug",
- "comment_id",
- "body"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "description": "comment action \"resolve\".",
- "properties": {
- "action": {
- "const": "resolve",
- "description": "Run the resolve action.",
- "type": "string"
- },
- "comment_id": {
- "description": "A comment_id in the thread (top-level or a reply).",
- "format": "uuid",
- "type": "string"
- },
- "project_slug": {
- "description": "Project slug, e.g. \"acme-app\" — list(what=\"projects\") returns yours.",
- "minLength": 1,
- "type": "string"
- },
- "resolved": {
- "description": "REQUIRED for resolve — true to resolve the thread, false to reopen it.",
- "type": "boolean"
- }
- },
- "required": [
- "action",
- "project_slug",
- "comment_id",
- "resolved"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "description": "comment action \"delete\".",
- "properties": {
- "action": {
- "const": "delete",
- "description": "Run the delete action.",
- "type": "string"
- },
- "comment_id": {
- "description": "The comment_id to delete.",
- "format": "uuid",
- "type": "string"
- },
- "project_slug": {
- "description": "Project slug, e.g. \"acme-app\" — list(what=\"projects\") returns yours.",
- "minLength": 1,
- "type": "string"
- }
- },
- "required": [
- "action",
- "project_slug",
- "comment_id"
- ],
- "type": "object"
- }
-]New value: +[
+ {
+ "additionalProperties": false,
+ "description": "action=\"add\": Leave a comment on any node — the human↔agent steering channel; the next agent that reads the node sees it flagged unseen. Reply by passing parent_comment_id (replies are one level deep). Pass `anchor` to attach to a quoted span (inline comment); omit for node-level. Commenting watches the node, so future comments on it show as unread to you.",
+ "properties": {
+ "action": {
+ "const": "add",
+ "type": "string"
+ },
+ "anchor": {
+ "additionalProperties": false,
+ "description": "(add only) Attach the comment to a quoted span of the node's body (per-line / inline comment). Omit for a node-level comment. Anchored to TEXT, never line numbers: on a later edit the quote is relocated; if it vanishes the comment goes 'outdated' (never deleted).",
+ "properties": {
+ "node_version": {
+ "description": "The node `version` the quote was taken from, as returned when you fetched the node.",
+ "exclusiveMinimum": 0,
+ "type": "integer"
+ },
+ "offset": {
+ "description": "Rough char offset to disambiguate a repeated quote.",
+ "minimum": 0,
+ "type": "integer"
+ },
+ "quote": {
+ "description": "The exact quoted substring to attach the comment to.",
+ "minLength": 1,
+ "type": "string"
+ }
+ },
+ "required": [
+ "node_version",
+ "quote"
+ ],
+ "type": "object"
+ },
+ "body": {
+ "description": "REQUIRED for add/update — comment text (markdown).",
+ "minLength": 1,
+ "type": "string"
+ },
+ "node_id": {
+ "description": "REQUIRED for add — the node to comment on (any node type).",
+ "type": "string"
+ },
+ "parent_comment_id": {
+ "description": "(add only) Reply target — the comment_id of a TOP-LEVEL comment. Replies are one level deep; replying to a reply is rejected.",
+ "format": "uuid",
+ "type": "string"
+ },
+ "project_slug": {
+ "description": "Project slug, e.g. \"acme-app\" — list(what=\"projects\") returns yours.",
+ "minLength": 1,
+ "type": "string"
+ }
+ },
+ "required": [
+ "action",
+ "project_slug",
+ "node_id",
+ "body"
+ ],
+ "type": "object"
+ },
+ {
+ "additionalProperties": false,
+ "description": "action=\"update\": Edit the body of a comment you authored. AUTHOR-ONLY. Sets the 'edited' marker and does not re-flag the comment unread for others.",
+ "properties": {
+ "action": {
+ "const": "update",
+ "type": "string"
+ },
+ "body": {
+ "description": "New comment text.",
+ "minLength": 1,
+ "type": "string"
+ },
+ "comment_id": {
+ "description": "REQUIRED for update/resolve/delete — the comment_id to act on.",
+ "format": "uuid",
+ "type": "string"
+ },
+ "project_slug": {
+ "description": "Project slug, e.g. \"acme-app\" — list(what=\"projects\") returns yours.",
+ "minLength": 1,
+ "type": "string"
+ }
+ },
+ "required": [
+ "action",
+ "project_slug",
+ "comment_id",
+ "body"
+ ],
+ "type": "object"
+ },
+ {
+ "additionalProperties": false,
+ "description": "action=\"resolve\": Resolve (or reopen) a comment thread. ANY project member may do this, not just the author. Resolve a steering comment once addressed so it stops nagging the next agent — resolved threads drop out of the [N comments, M unread] marker. Applies to the whole thread (resolving a reply resolves its parent).",
+ "properties": {
+ "action": {
+ "const": "resolve",
+ "type": "string"
+ },
+ "comment_id": {
+ "description": "A comment_id in the thread (top-level or a reply).",
+ "format": "uuid",
+ "type": "string"
+ },
+ "project_slug": {
+ "description": "Project slug, e.g. \"acme-app\" — list(what=\"projects\") returns yours.",
+ "minLength": 1,
+ "type": "string"
+ },
+ "resolved": {
+ "description": "REQUIRED for resolve — true to resolve the thread, false to reopen it.",
+ "type": "boolean"
+ }
+ },
+ "required": [
+ "action",
+ "project_slug",
+ "comment_id",
+ "resolved"
+ ],
+ "type": "object"
+ },
+ {
+ "additionalProperties": false,
+ "description": "action=\"delete\": Soft-delete a comment you authored — the row stays as a tombstone and replies remain intact (never orphaned). AUTHOR-ONLY; there is no hard delete.",
+ "properties": {
+ "action": {
+ "const": "delete",
+ "type": "string"
+ },
+ "comment_id": {
+ "description": "The comment_id to delete.",
+ "format": "uuid",
+ "type": "string"
+ },
+ "project_slug": {
+ "description": "Project slug, e.g. \"acme-app\" — list(what=\"projects\") returns yours.",
+ "minLength": 1,
+ "type": "string"
+ }
+ },
+ "required": [
+ "action",
+ "project_slug",
+ "comment_id"
+ ],
+ "type": "object"
+ }
+]Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, and the description adds real behavioral detail beyond them: delete is a soft tombstone with replies preserved, and replies are one level deep so replying to a reply is rejected. It does not mention the privacy-bypass write path, which lives only in the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, zero filler, and the core purpose plus action list is front-loaded before the two constraints. Every clause carries information the agent needs.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need no explanation, and the annotations cover the safety profile. For a multi-action tool the description covers the action semantics, the reply-depth restriction, and the read alternative — enough to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3, but the description genuinely adds meaning to the action enum values ('resolve' = mark thread settled, 'delete' = soft tombstone), whereas the schema only says 'Run the delete action.' That extra semantic content lifts it above baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a concrete resource (comments on a node) and enumerates the four action modes (add/update/resolve/delete), each with a short gloss. Combined with the pointer to list(what="comments") for reading, an agent can distinguish this from sibling tools without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear per-action guidance ('resolve (mark a thread settled)', 'delete (soft tombstone)') and routes reading to the alternative list(what="comments"). It also states the one-level-deep reply constraint, which is a usage rule. It stops short of saying when to comment versus other node-mutation tools, so it is clear context rather than full when/when-not coverage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.