Co-dev review MCP

review_work

Destructive

Review local changes or GitLab MR/GitHub PR diffs against domain rubrics, CI checks, blast radius and tests, then draft inline comments for explicit user approval before publishing.

Instructions

request.step is one of: read, read_file, rubric, pipeline, checkout, checks, blast_radius, tests, prepare_comments, request_approval, approve, revise, view_draft, publish. Review local changes before pushing or a GitLab MR/GitHub PR. Start with step=read; it returns the diff, a per-hunk ledger and the domain rubrics to load. step=rubric returns the full text of a rubric for clients that cannot load skill files. step=pipeline reports the failing CI stages of a remote MR/PR with their cause and file:line. step=checkout puts a remote MR/PR head in a dedicated worktree. step=checks runs the repository's own compiler and linters over the change; step=blast_radius lists call sites outside the diff; step=tests runs the unit tests related to the change. Each returns a runId; prepare_comments requires the first two. The assistant examines code, explains blockers and suggestions, and can prepare French/English comments. Publishing requires the user approval of the saved draft: by default you show its preview and relay their reply with step=approve. These steps support one review; they are not separate tools.

Input Schema

Name	Required	Description	Default
`request`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv1.4.0Oct 13, 2026

changedInput schema / properties / request / anyOf

Previous value: -[
-  {
-    "additionalProperties": false,
-    "properties": {
-      "base": {
-        "default": "HEAD",
-        "description": "For local branch review use the intended comparison ref, e.g. origin/develop",
-        "type": "string"
-      },
-      "mode": {
-        "default": "working",
-        "enum": [
-          "working",
-          "staged",
-          "branch"
-        ],
-        "type": "string"
-      },
-      "page": {
-        "default": 1,
-        "maximum": 1000,
-        "minimum": 1,
-        "type": "integer"
-      },
-      "step": {
-        "const": "read",
-        "type": "string"
-      },
-      "target": {
-        "additionalProperties": false,
-        "description": "Remote MR/PR; omit to review the configured local checkout",
-        "properties": {
-          "number": {
-            "exclusiveMinimum": 0,
-            "type": "integer"
-          },
-          "project": {
-            "description": "GitLab ID/path or GitHub owner/repository; defaults to configured GitLab project",
-            "minLength": 1,
-            "type": "string"
-          },
-          "provider": {
-            "enum": [
-              "gitlab",
-              "github"
-            ],
-            "type": "string"
-          }
-        },
-        "required": [
-          "provider",
-          "number"
-        ],
-        "type": "object"
-      }
-    },
-    "required": [
-      "step"
-    ],
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "path": {
-        "minLength": 1,
-        "type": "string"
-      },
-      "ref": {
-        "description": "Head SHA from the reviewed snapshot",
-        "minLength": 1,
-        "type": "string"
-      },
-      "step": {
-        "const": "read_file",
-        "type": "string"
-      },
-      "target": {
-        "$ref": "#/properties/request/anyOf/0/properties/target"
-      }
-    },
-    "required": [
-      "step",
-      "target",
-      "path",
-      "ref"
-    ],
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "names": {
-        "description": "Rubric or repository skill names from the read result, e.g. [\"review-react-ts\", \"house-conventions\"]",
-        "items": {
-          "maxLength": 64,
-          "minLength": 1,
-          "type": "string"
-        },
-        "maxItems": 8,
-        "minItems": 1,
-        "type": "array"
-      },
-      "step": {
-        "const": "rubric",
-        "type": "string"
-      }
-    },
-    "required": [
-      "step",
-      "names"
-    ],
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "base": {
-        "default": "HEAD",
-        "type": "string"
-      },
-      "mode": {
-        "default": "working",
-        "enum": [
-          "working",
-          "staged",
-          "branch"
-        ],
-        "type": "string"
-      },
-      "only": {
-        "description": "Restrict which runners execute; omit to run every one that is available",
-        "items": {
-          "enum": [
-            "tsc",
-            "eslint",
-            "dotnet"
-          ],
-          "type": "string"
-        },
-        "type": "array"
-      },
-      "step": {
-        "const": "checks",
-        "type": "string"
-      }
-    },
-    "required": [
-      "step"
-    ],
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "base": {
-        "default": "HEAD",
-        "type": "string"
-      },
-      "mode": {
-        "default": "working",
-        "enum": [
-          "working",
-          "staged",
-          "branch"
-        ],
-        "type": "string"
-      },
-      "step": {
-        "const": "blast_radius",
-        "type": "string"
-      }
-    },
-    "required": [
-      "step"
-    ],
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "coverage": {
-        "description": "Every hunk in the diff needs exactly one verdict. The draft is rejected while any hunk is unaccounted for.",
-        "items": {
-          "additionalProperties": false,
-          "properties": {
-            "hunks": {
-              "description": "Hunk ids from the read ledger: \"7.2\", a whole file as \"7.*\", a range as \"7.2-7.5\", or a comma-separated mix",
-              "minLength": 1,
-              "type": "string"
-            },
-            "note": {
-              "description": "Required in practice for not-applicable: say why the hunk needs no judgement",
-              "maxLength": 500,
-              "type": "string"
-            },
-            "verdict": {
-              "enum": [
-                "finding",
-                "reviewed-clean",
-                "not-applicable"
-              ],
-              "type": "string"
-            }
-          },
-          "required": [
-            "hunks",
-            "verdict"
-          ],
-          "type": "object"
-        },
-        "minItems": 1,
-        "type": "array"
-      },
-      "items": {
-        "items": {
-          "additionalProperties": false,
-          "properties": {
-            "body": {
-              "description": "Exact comment text in the selected language; include impact and actionable evidence",
-              "maxLength": 30000,
-              "minLength": 1,
-              "type": "string"
-            },
-            "line": {
-              "exclusiveMinimum": 0,
-              "type": "integer"
-            },
-            "path": {
-              "minLength": 1,
-              "type": "string"
-            },
-            "severity": {
-              "enum": [
-                "blocker",
-                "major",
-                "minor",
-                "suggestion"
-              ],
-              "type": "string"
-            },
-            "side": {
-              "default": "RIGHT",
-              "enum": [
-                "LEFT",
-                "RIGHT"
-              ],
-              "type": "string"
-            }
-          },
-          "required": [
-            "body",
-            "severity"
-          ],
-          "type": "object"
-        },
-        "maxItems": 100,
-        "minItems": 1,
-        "type": "array"
-      },
-      "language": {
-        "enum": [
-          "fr",
-          "en"
-        ],
-        "type": "string"
-      },
-      "rubricsApplied": {
-        "description": "Names of the rubric skills and repository skills you actually read and applied for this review, e.g. [\"review-react-ts\", \"house-conventions\"]. An empty array is accepted and is shown to the approver as such.",
-        "items": {
-          "maxLength": 64,
-          "minLength": 1,
-          "type": "string"
-        },
-        "maxItems": 20,
-        "type": "array"
-      },
-      "step": {
-        "const": "prepare_comments",
-        "type": "string"
-      },
-      "target": {
-        "$ref": "#/properties/request/anyOf/0/properties/target"
-      }
-    },
-    "required": [
-      "step",
-      "target",
-      "language",
-      "items",
-      "coverage",
-      "rubricsApplied"
-    ],
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "draftId": {
-        "format": "uuid",
-        "type": "string"
-      },
-      "step": {
-        "const": "view_draft",
-        "type": "string"
-      }
-    },
-    "required": [
-      "step",
-      "draftId"
-    ],
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "draftId": {
-        "$ref": "#/properties/request/anyOf/6/properties/draftId"
-      },
-      "step": {
-        "const": "publish",
-        "type": "string"
-      }
-    },
-    "required": [
-      "step",
-      "draftId"
-    ],
-    "type": "object"
-  }
-]New value: +[
+  {
+    "additionalProperties": false,
+    "properties": {
+      "base": {
+        "default": "HEAD",
+        "description": "For local branch review use the intended comparison ref, e.g. origin/develop",
+        "type": "string"
+      },
+      "mode": {
+        "default": "working",
+        "enum": [
+          "working",
+          "staged",
+          "branch"
+        ],
+        "type": "string"
+      },
+      "page": {
+        "default": 1,
+        "maximum": 1000,
+        "minimum": 1,
+        "type": "integer"
+      },
+      "step": {
+        "const": "read",
+        "type": "string"
+      },
+      "target": {
+        "additionalProperties": false,
+        "description": "Remote MR/PR; omit to review the configured local checkout",
+        "properties": {
+          "number": {
+            "exclusiveMinimum": 0,
+            "type": "integer"
+          },
+          "project": {
+            "description": "GitLab ID/path or GitHub owner/repository; defaults to configured GitLab project",
+            "minLength": 1,
+            "type": "string"
+          },
+          "provider": {
+            "enum": [
+              "gitlab",
+              "github"
+            ],
+            "type": "string"
+          }
+        },
+        "required": [
+          "provider",
+          "number"
+        ],
+        "type": "object"
+      }
+    },
+    "required": [
+      "step"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "lines": {
+        "description": "Line range such as \"120-220\", \"120-\" or \"-80\"; read only what you need. Without it, files longer than 1500 lines are cut with a continuation hint",
+        "pattern": "^\\s*\\d*\\s*-?\\s*\\d*\\s*$",
+        "type": "string"
+      },
+      "path": {
+        "minLength": 1,
+        "type": "string"
+      },
+      "ref": {
+        "description": "Head SHA from the reviewed snapshot",
+        "minLength": 1,
+        "type": "string"
+      },
+      "step": {
+        "const": "read_file",
+        "type": "string"
+      },
+      "target": {
+        "$ref": "#/properties/request/anyOf/0/properties/target"
+      }
+    },
+    "required": [
+      "step",
+      "target",
+      "path",
+      "ref"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "names": {
+        "description": "Rubric or repository skill names from the read result, e.g. [\"review-react-ts\", \"house-style\"]",
+        "items": {
+          "maxLength": 64,
+          "minLength": 1,
+          "type": "string"
+        },
+        "maxItems": 8,
+        "minItems": 1,
+        "type": "array"
+      },
+      "step": {
+        "const": "rubric",
+        "type": "string"
+      }
+    },
+    "required": [
+      "step",
+      "names"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "install": {
+        "default": true,
+        "description": "Install dependencies from the lockfile (lifecycle scripts skipped) when node_modules is missing or the lockfile changed",
+        "type": "boolean"
+      },
+      "packageManager": {
+        "default": "auto",
+        "description": "auto links your checkout's node_modules when the change touches no lockfile or package.json, else installs with the lockfile's manager; link, pnpm, npm or yarn force one; none skips dependencies. Ask the user first",
+        "enum": [
+          "auto",
+          "link",
+          "pnpm",
+          "npm",
+          "yarn",
+          "none"
+        ],
+        "type": "string"
+      },
+      "step": {
+        "const": "checkout",
+        "type": "string"
+      },
+      "target": {
+        "$ref": "#/properties/request/anyOf/0/properties/target"
+      }
+    },
+    "required": [
+      "step",
+      "target"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "base": {
+        "default": "HEAD",
+        "type": "string"
+      },
+      "detail": {
+        "default": "summary",
+        "description": "summary keeps results short; full returns every finding or caller",
+        "enum": [
+          "summary",
+          "full"
+        ],
+        "type": "string"
+      },
+      "mode": {
+        "default": "working",
+        "enum": [
+          "working",
+          "staged",
+          "branch"
+        ],
+        "type": "string"
+      },
+      "only": {
+        "description": "Restrict which runners execute; omit to run every one that is available",
+        "items": {
+          "enum": [
+            "tsc",
+            "eslint",
+            "dotnet"
+          ],
+          "type": "string"
+        },
+        "type": "array"
+      },
+      "step": {
+        "const": "checks",
+        "type": "string"
+      },
+      "target": {
+        "$ref": "#/properties/request/anyOf/0/properties/target",
+        "description": "Remote MR/PR prepared with step=checkout; runs in its worktree against the review base, ignoring mode and base"
+      }
+    },
+    "required": [
+      "step"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "base": {
+        "default": "HEAD",
+        "type": "string"
+      },
+      "detail": {
+        "default": "summary",
+        "description": "summary keeps results short; full returns every finding or caller",
+        "enum": [
+          "summary",
+          "full"
+        ],
+        "type": "string"
+      },
+      "mode": {
+        "default": "working",
+        "enum": [
+          "working",
+          "staged",
+          "branch"
+        ],
+        "type": "string"
+      },
+      "step": {
+        "const": "blast_radius",
+        "type": "string"
+      },
+      "symbols": {
+        "description": "Expand every caller of these symbols only",
+        "items": {
+          "maxLength": 64,
+          "minLength": 1,
+          "type": "string"
+        },
+        "maxItems": 10,
+        "type": "array"
+      },
+      "target": {
+        "$ref": "#/properties/request/anyOf/0/properties/target",
+        "description": "Remote MR/PR prepared with step=checkout; runs in its worktree against the review base, ignoring mode and base"
+      }
+    },
+    "required": [
+      "step"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "step": {
+        "const": "pipeline",
+        "type": "string"
+      },
+      "target": {
+        "$ref": "#/properties/request/anyOf/0/properties/target"
+      }
+    },
+    "required": [
+      "step",
+      "target"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "base": {
+        "default": "HEAD",
+        "type": "string"
+      },
+      "mode": {
+        "default": "working",
+        "enum": [
+          "working",
+          "staged",
+          "branch"
+        ],
+        "type": "string"
+      },
+      "step": {
+        "const": "tests",
+        "type": "string"
+      },
+      "target": {
+        "$ref": "#/properties/request/anyOf/0/properties/target",
+        "description": "Remote MR/PR prepared with step=checkout; runs in its worktree against the review base, ignoring mode and base"
+      }
+    },
+    "required": [
+      "step"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "approval": {
+        "default": "default",
+        "description": "Where the user approves. default = conversation (REVIEW_APPROVAL). conversation: you show the preview and relay the user's reply with step=approve. in-chat: an MCP form. browser: a local page. terminal: co-dev-review approve. auto: form, then browser, then terminal",
+        "enum": [
+          "default",
+          "conversation",
+          "in-chat",
+          "browser",
+          "terminal",
+          "auto"
+        ],
+        "type": "string"
+      },
+      "coverage": {
+        "description": "Every hunk in the diff needs exactly one verdict. The draft is rejected while any hunk is unaccounted for.",
+        "items": {
+          "additionalProperties": false,
+          "properties": {
+            "hunks": {
+              "description": "Hunk ids from the read ledger: \"7.2\", a whole file as \"7.*\", a range as \"7.2-7.5\", or a comma-separated mix",
+              "minLength": 1,
+              "type": "string"
+            },
+            "note": {
+              "description": "Required in practice for not-applicable: say why the hunk needs no judgement",
+              "maxLength": 500,
+              "type": "string"
+            },
+            "verdict": {
+              "enum": [
+                "finding",
+                "reviewed-clean",
+                "not-applicable"
+              ],
+              "type": "string"
+            }
+          },
+          "required": [
+            "hunks",
+            "verdict"
+          ],
+          "type": "object"
+        },
+        "minItems": 1,
+        "type": "array"
+      },
+      "deterministic": {
+        "additionalProperties": false,
+        "description": "Proof that step=checks and step=blast_radius ran on this review head against its base, or an explicit reason each was skipped. A run on another commit or base is rejected.",
+        "properties": {
+          "blastRadius": {
+            "$ref": "#/properties/request/anyOf/8/properties/deterministic/properties/checks"
+          },
+          "checks": {
+            "anyOf": [
+              {
+                "additionalProperties": false,
+                "properties": {
+                  "runId": {
+                    "description": "runId returned by the step for this same target",
+                    "format": "uuid",
+                    "type": "string"
+                  }
+                },
+                "required": [
+                  "runId"
+                ],
+                "type": "object"
+              },
+              {
+                "additionalProperties": false,
+                "properties": {
+                  "skipped": {
+                    "description": "Why the pass could not be run; shown to the approver",
+                    "maxLength": 500,
+                    "minLength": 20,
+                    "type": "string"
+                  }
+                },
+                "required": [
+                  "skipped"
+                ],
+                "type": "object"
+              }
+            ]
+          },
+          "tests": {
+            "$ref": "#/properties/request/anyOf/8/properties/deterministic/properties/checks",
+            "description": "runId of step=tests on this head, when tests were run"
+          }
+        },
+        "required": [
+          "checks",
+          "blastRadius"
+        ],
+        "type": "object"
+      },
+      "items": {
+        "items": {
+          "additionalProperties": false,
+          "properties": {
+            "body": {
+              "description": "Exact comment text in the selected language; include impact and actionable evidence",
+              "maxLength": 30000,
+              "minLength": 1,
+              "type": "string"
+            },
+            "confidence": {
+              "description": "After trying to refute the finding: confirmed = trigger named and no protection found; likely = plausible, protection not ruled out; question = needs the author's knowledge, written as a question",
+              "enum": [
+                "confirmed",
+                "likely",
+                "question"
+              ],
+              "type": "string"
+            },
+            "line": {
+              "exclusiveMinimum": 0,
+              "type": "integer"
+            },
+            "lineText": {
+              "description": "Preferred anchor: the exact content of the added (RIGHT) or removed (LEFT) line, without its +/- prefix. The server finds its line number; do not count lines. line, when also given, only picks between identical lines",
+              "maxLength": 500,
+              "minLength": 1,
+              "type": "string"
+            },
+            "path": {
+              "minLength": 1,
+              "type": "string"
+            },
+            "severity": {
+              "enum": [
+                "blocker",
+                "major",
+                "minor",
+                "suggestion"
+              ],
+              "type": "string"
+            },
+            "side": {
+              "default": "RIGHT",
+              "enum": [
+                "LEFT",
+                "RIGHT"
+              ],
+              "type": "string"
+            }
+          },
+          "required": [
+            "body",
+            "severity",
+            "confidence"
+          ],
+          "type": "object"
+        },
+        "maxItems": 100,
+        "minItems": 1,
+        "type": "array"
+      },
+      "language": {
+        "enum": [
+          "fr",
+          "en"
+        ],
+        "type": "string"
+      },
+      "rubricsApplied": {
+        "description": "Names of the rubric skills and repository skills you actually read and applied for this review, e.g. [\"review-react-ts\", \"house-style\"]. Every rubric skill routed by read must be here or in rubricsSkipped.",
+        "items": {
+          "maxLength": 64,
+          "minLength": 1,
+          "type": "string"
+        },
+        "maxItems": 20,
+        "type": "array"
+      },
+      "rubricsSkipped": {
+        "default": [],
+        "description": "Routed rubrics you deliberately did not apply, each with a reason the approver sees",
+        "items": {
+          "additionalProperties": false,
+          "properties": {
+            "name": {
+              "maxLength": 64,
+              "minLength": 1,
+              "type": "string"
+            },
+            "reason": {
+              "maxLength": 300,
+              "minLength": 15,
+              "type": "string"
+            }
+          },
+          "required": [
+            "name",
+            "reason"
+          ],
+          "type": "object"
+        },
+        "maxItems": 20,
+        "type": "array"
+      },
+      "step": {
+        "const": "prepare_comments",
+        "type": "string"
+      },
+      "target": {
+        "$ref": "#/properties/request/anyOf/0/properties/target"
+      }
+    },
+    "required": [
+      "step",
+      "target",
+      "language",
+      "items",
+      "coverage",
+      "rubricsApplied",
+      "deterministic"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "approval": {
+        "$ref": "#/properties/request/anyOf/8/properties/approval"
+      },
+      "draftId": {
+        "format": "uuid",
+        "type": "string"
+      },
+      "step": {
+        "const": "request_approval",
+        "type": "string"
+      }
+    },
+    "required": [
+      "step",
+      "draftId"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "draftId": {
+        "$ref": "#/properties/request/anyOf/9/properties/draftId"
+      },
+      "publish": {
+        "default": true,
+        "description": "false only when the user asked to approve without posting now",
+        "type": "boolean"
+      },
+      "selectedIds": {
+        "description": "Exactly the item ids the user approved in their reply, e.g. [\"R1\",\"R3\"]",
+        "items": {
+          "pattern": "^[RT]\\d{1,3}$",
+          "type": "string"
+        },
+        "maxItems": 100,
+        "minItems": 1,
+        "type": "array"
+      },
+      "step": {
+        "const": "approve",
+        "type": "string"
+      },
+      "userWords": {
+        "description": "The user's approving reply, quoted verbatim; it is stored with the approval",
+        "maxLength": 500,
+        "minLength": 2,
+        "type": "string"
+      }
+    },
+    "required": [
+      "step",
+      "draftId",
+      "selectedIds",
+      "userWords"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "draftId": {
+        "$ref": "#/properties/request/anyOf/9/properties/draftId"
+      },
+      "itemId": {
+        "pattern": "^[RT]\\d{1,3}$",
+        "type": "string"
+      },
+      "step": {
+        "const": "revise",
+        "type": "string"
+      },
+      "text": {
+        "description": "The reworded comment (Markdown) or task description (Azure HTML) the user asked for",
+        "maxLength": 30000,
+        "minLength": 1,
+        "type": "string"
+      }
+    },
+    "required": [
+      "step",
+      "draftId",
+      "itemId",
+      "text"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "draftId": {
+        "$ref": "#/properties/request/anyOf/9/properties/draftId"
+      },
+      "step": {
+        "const": "view_draft",
+        "type": "string"
+      }
+    },
+    "required": [
+      "step",
+      "draftId"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "draftId": {
+        "$ref": "#/properties/request/anyOf/9/properties/draftId"
+      },
+      "step": {
+        "const": "publish",
+        "type": "string"
+      }
+    },
+    "required": [
+      "step",
+      "draftId"
+    ],
+    "type": "object"
+  }
+]

First observedv1.1.0Sep 14, 2026

TDQS

A3.9/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true and openWorldHint=true; the description adds non-redundant behavior, notably that step=checkout materializes a remote head in a dedicated worktree and that publish is gated on explicit user approval of a saved draft. It is less explicit about the remote write side of publish and the dependency-install side effect of checkout, which limits it below a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The definition opens with a bare enumeration of the 14 step values, which duplicates the schema's const values and pushes the actual purpose sentence into second position. The remaining sentences mostly earn their place, but the front-loading is inverted and the density is high.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 14-branch discriminated union with no output schema, the description covers what the key steps return (read: diff, ledger, rubrics; pipeline: failing stages with cause and file:line; checks/blast_radius/tests) and the approval gate. The back half of the flow (approve, revise, view_draft, publish) is only named, not described, leaving a modest gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Top-level schema coverage is reported as 0%, so the description must carry meaning, and it does: it maps each of the 14 step const values to concrete behavior that the schema's bare consts do not explain, and it states the runId chaining contract. It leaves mode, base, and most target fields entirely to the schema, so it is not exhaustive.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: "Review local changes before pushing or a GitLab MR/GitHub PR," and adds the scope-clarifying note that the steps "support one review; they are not separate tools." It does not name or differentiate itself from the siblings review_sonar or plan_ticket_tasks, so it falls short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Strong internal routing guidance: "Start with step=read," prepare_comments "requires the first two" runIds, and "Publishing requires the user approval of the saved draft." It never states when to prefer this tool over review_sonar or when not to use it, so it stops at a clear-context 4.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

review_work

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools