# interaction

Create, get, list, revise, cancel, or poll durable Commentary Interactions with no held connection; retrieve immutable human Decision receipts but cannot create or modify Decisions; append or read sel

Canonical: https://commentary.dev/docs/reference/mcp/interaction

Create, get, list, revise, cancel, or poll durable Commentary Interactions with no held connection; retrieve immutable human Decision receipts but cannot create or modify Decisions; append or read self-reported Fulfillment; and use guidance_list or guidance_ack for future-facing human guidance. Guidance acknowledgment never claims the instruction was learned or applied.

## 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` | `"create"` · `"get"` · `"list"` · `"revise"` · `"message"` · `"cancel"` · `"status"` · `"decision_get"` · `"decision_wait"` · `"fulfillment_report"` · `"fulfillment_get"` · `"guidance_list"` · `"guidance_ack"` | Yes | Operation to perform. Choose one advertised value; the remaining parameters are interpreted for that action. |
| `body` | string | No | Reply text. Assigned investigation recipients use the project_review.investigation_response.v1 JSON envelope; outcomes remain agent-reported. Minimum length: 1. Maximum length: 16384. |
| `handle` | string | No | Stable opaque Interaction handle returned by create, get, list, or status. Minimum length: 1. Maximum length: 256. |
| `decisionId` | string | No | Stable decision identifier used by the selected Commentary Interaction action. Minimum length: 1. Maximum length: 256. |
| `revisionId` | string | No | Stable Draft revision identifier. Minimum length: 1. Maximum length: 256. |
| `actionId` | string | No | Stable action identifier used by the selected Commentary Interaction action. Minimum length: 1. Maximum length: 256. |
| `guidanceId` | string | No | Stable guidance identifier used by the selected Commentary Interaction action. Minimum length: 1. Maximum length: 256. |
| `proposalFingerprint` | string | No | Proposal fingerprint used by the selected Commentary Interaction action. |
| `status` | `"received"` · `"started"` · `"completed"` · `"failed"` · `"unknown"` | No | Status filter or requested state supported by the selected action. |
| `evidence` | object | No | Evidence object used by the selected Commentary Interaction action. |
| `after` | string | No | After used by the selected Commentary Interaction action. Minimum length: 1. Maximum length: 256. |
| `waitMs` | integer | No | Wait ms used by the selected Commentary Interaction action. |
| `resource` | object | No | Resource object used by the selected Commentary Interaction action. |
| `content` | object | No | Full literal UTF-8 file content. Commentary never resolves a local path or fetches a URL for this field. |
| `initialState` | `"draft"` · `"active"` | No | Allowed initial state value for the selected Commentary Interaction action. |
| `interactionType` | `"request"` · `"notification"` · `"decision_request"` | No | Registered-agent Interaction type. Current owner policy is enforced for new requests. |
| `priority` | `"low"` · `"normal"` · `"high"` · `"urgent"` | No | Requested attention priority. It may not exceed the registered agent ceiling. |
| `expectedVersion` | integer | No | Current Interaction version used for optimistic concurrency on revise and cancel. |
| `idempotencyKey` | string | No | Caller-generated retry key. Reuse it only for an identical create, revise, or cancel request. Minimum length: 1. Maximum length: 200. |
| `limit` | integer | No | Maximum number of records to return. Server-side bounds still apply. |
| `cursor` | string | No | Opaque pagination cursor returned by a previous call. |
| `state` | `"draft"` · `"active"` · `"waiting_for_human"` · `"waiting_for_agent"` · `"completed"` · `"rejected"` · `"canceled"` · `"expired"` | No | State filter supported by the selected action. |
| `resourceType` | `"repository"` · `"pull_request"` · `"document"` · `"draft_review"` · `"form"` · `"research_study"` · `"knowledge_brain"` · `"web_app_review"` · `"project_review_session"` | No | Allowed resource type value for the selected Commentary Interaction action. |

## Call the tool

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