# draft_review

Manage Draft Review Sessions, including actor-bound raster uploads, with action=prepare_asset_upload, create, get, list, update_metadata, upload_revision, rebase, delete, list_revisions, get_revision,

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

Manage Draft Review Sessions, including actor-bound raster uploads, with action=prepare_asset_upload, create, get, list, update_metadata, upload_revision, rebase, delete, list_revisions, get_revision, get_content, list_events, list_shares, share, revoke_share, or remove_access.

## 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` | `"prepare_asset_upload"` · `"create"` · `"get"` · `"list"` · `"update_metadata"` · `"upload_revision"` · `"rebase"` · `"delete"` · `"list_revisions"` · `"get_revision"` · `"get_content"` · `"list_events"` · `"list_shares"` · `"share"` · `"revoke_share"` · `"remove_access"` | Yes | Operation to perform. Choose one advertised value; the remaining parameters are interpreted for that action. |
| `sessionId` | string | No | Stable Draft, or Research session identifier, as applicable to the selected tool. |
| `title` | string | No | Human-readable title for the created or updated artifact. |
| `collaboration` | object | No | Collaboration object used by the selected Draft Review action. |
| `description` | string | No | Human-readable description for the created or updated artifact. |
| `status` | `"active"` · `"archived"` | No | Status filter or requested state supported by the selected action. |
| `sourceType` | `"api"` · `"mcp"` · `"cli"` · `"agent_api"` | No | Origin classification for the created or resolved source artifact. |
| `gitBase` | object | No | Git base object used by the selected Draft Review action. |
| `base` | object | No | Base object used by the selected Draft Review action. |
| `summary` | string | No | Concise human-readable summary produced or stored by the selected action. |
| `files` | array of object | No | Files included in a Draft Review operation. |
| `fileId` | string | No | Stable Commentary file identifier returned by the review or revision API. |
| `revisionId` | string | No | Stable Draft revision identifier. |
| `revisionNumber` | number | No | Human-readable revision sequence number. |
| `path` | string | No | Source-relative file path used by the selected action. |
| `mimeType` | `"image/png"` · `"image/jpeg"` · `"image/webp"` · `"image/avif"` | No | Allowed mime type value for the selected Draft Review action. |
| `byteLength` | number | No | Byte length used by the selected Draft Review action. |
| `sha256` | string | No | Sha256 used by the selected Draft Review 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. |
| `cursor` | string | No | Opaque pagination cursor returned by a previous call. |
| `limit` | number | No | Maximum number of records to return. Server-side bounds still apply. |
| `audience` | `"anyone"` · `"user"` | No | Allowed audience value for the selected Draft Review action. |
| `recipient` | string | No | User identity or recipient descriptor used by an explicitly selected sharing action. |
| `shareLinkId` | string | No | Stable share link identifier used by the selected Draft Review action. |
| `accessGrantId` | string | No | Stable access grant identifier used by the selected Draft Review action. |

## Call the tool

Send a `tools/call` request with `name: "draft_review"` 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/draft-review.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).