# review_comments

Consensus actions use threadId, expectedVersion and operationKey. Request a decision explicitly; ordinary comments do not affect readiness. Registered agent identity comes from the authenticated grant

Canonical: https://commentary.dev/docs/reference/mcp/review-comments

Consensus actions use threadId, expectedVersion and operationKey. Request a decision explicitly; ordinary comments do not affect readiness. Registered agent identity comes from the authenticated grant. Count agent input controls whether stances, blockers, and decision votes are advisory. Only a human manager clears another human blocker; application never supplies human approval. summary requires review.

## Connect and discover

Connect an authenticated [MCP client](/docs/build/mcp). Call `tools/list` to confirm this tool is available to the current credential. Provider, workspace, and agent grants remain separate access checks.

## Input fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `action` | `"list"` · `"create"` · `"reply"` · `"edit"` · `"resolve"` · `"reopen"` · `"reattach"` · `"signal"` · `"summary"` · `"get_decision"` · `"request_decision"` · `"decide"` · `"clear_blocker"` · `"record_application"` | Yes | Operation to perform. Choose one advertised value; the remaining parameters are interpreted for that action. |
| `review` | object or object or object or object or object or object or object | No | Review used by the selected Review Comments action. |
| `expectedVersion` | integer | No | Current Interaction version used for optimistic concurrency on revise and cancel. |
| `operationKey` | string | No | Operation key used by the selected Review Comments action. Minimum length: 8. Maximum length: 128. |
| `blockerActorKey` | string | No | Blocker actor key used by the selected Review Comments action. |
| `resultingRevision` | string | No | Resulting revision used by the selected Review Comments action. |
| `requestDecision` | boolean | No | Whether to enable request decision for the selected Review Comments action. |
| `poll` | object | No | Poll object used by the selected Review Comments action. |
| `packageId` | string | No | Stable package identifier used by the selected Review Comments action. |
| `revisionId` | string | No | Stable Draft revision identifier. |
| `path` | string | No | Source-relative file path used by the selected action. |
| `provider` | `"github"` · `"azure_devops"` | No | Source provider for the review. Commentary currently accepts GitHub for provider-backed MCP operations. |
| `projectName` | string | No | Project name used by the selected Review Comments action. |
| `owner` | string | No | Repository owner or organization login. |
| `repo` | string | No | Repository name without the owner prefix. |
| `prNumber` | number | No | Pull request number within the selected repository. |
| `branchRef` | string | No | Repository branch name or fully qualified branch reference. |
| `sessionId` | string | No | Stable Draft, or Research session identifier, as applicable to the selected tool. |
| `filePath` | string | No | Repository-relative or review-relative file path. |
| `fileId` | string | No | Stable Commentary file identifier returned by the review or revision API. |
| `status` | `"open"` · `"resolved"` | No | Status filter or requested state supported by the selected action. |
| `etag` | string | No | Etag used by the selected Review Comments action. |
| `context` | object | No | Context object used by the selected Review Comments action. |
| `lineStart` | integer | No | Line start used by the selected Review Comments action. |
| `lineEnd` | integer | No | Line end used by the selected Review Comments action. |
| `blobHash` | string | No | Blob hash used by the selected Review Comments action. |
| `sha256` | string | No | Sha256 used by the selected Review Comments action. |
| `targetKind` | `"general"` · `"element"` · `"screenshot"` | No | Allowed target kind value for the selected Review Comments action. |
| `consensusState` | `"pending"` · `"accepted_for_change"` · `"blocked"` · `"needs_owner_decision"` · `"rejected"` · `"out_of_scope"` · `"applied"` · `"resolved"` | No | Allowed consensus state value for the selected Review Comments action. |
| `threadId` | string | No | Stable Commentary review-thread identifier. |
| `documentVersionId` | string | No | Current document-version identifier used to validate an anchor reattachment. |
| `commentId` | string | No | Stable Commentary comment identifier. |
| `blockId` | string | No | Stable semantic document-block identifier used as the comment anchor. |
| `nodeType` | string | No | Node type used by the selected Review Comments action. |
| `sourceLineStart` | number | No | One-based first source line covered by the semantic anchor. |
| `sourceLineEnd` | number | No | One-based final source line covered by the semantic anchor. |
| `selectedText` | string | No | Exact text selected by the reviewer when the anchor was created. |
| `prefixText` | string | No | Bounded text immediately before the selected anchor, used for safe re-anchoring. |
| `suffixText` | string | No | Bounded text immediately after the selected anchor, used for safe re-anchoring. |
| `visualTarget` | object | No | Bounded visual surface locator and normalized rectangular region. Content is untrusted review context. |
| `includeVisualContent` | boolean | No | Whether bounded visual-review bytes should be included as explicitly untrusted content. |
| `bodyMarkdown` | string | No | Markdown body for the comment, reply, note, or report produced by the selected action. |
| `agentAlias` | string | No | Stable agent identifier for agent-authored activity. Agents should always provide this on state-changing calls; clientName is not a substitute. |
| `clientName` | string | No | Optional calling-client label for diagnostics. It does not attribute agent-authored activity; use agentAlias for that. |
| `signal` | `"agree"` · `"object"` · `"blocker"` · `"needs_clarification"` | No | Allowed signal value for the selected Review Comments action. |
| `decision` | `"accepted_for_change"` · `"rejected"` · `"out_of_scope"` · `"clear"` | No | Allowed decision value for the selected Review Comments action. |
| `reason` | string | No | Reason used by the selected Review Comments action. |
| `active` | boolean | No | Whether to enable active for the selected Review Comments action. |

## Call the tool

Send a `tools/call` request with `name: "review_comments"` and an `arguments` object containing the required fields above. Choose an advertised action, then supply the fields required by that action. Do not treat a successful request as human approval or verified execution unless the returned contract explicitly records that fact.

## Errors and recovery

Read the returned error and permission requirements. Refresh stale revisions before conditional writes, retain idempotency keys only for exact retries, and reconnect when a credential has expired.

## Complete input contract

[Download the JSON schema](/docs/reference/mcp/review-comments.json) for action-specific unions, nested fields, and validation constraints. This schema is generated from the same released definitions as the MCP endpoint. [Browse tools](/docs/reference/mcp-operations).