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
Section titled “Connect and discover”Connect an authenticated MCP client. Call tools/list to confirm this tool is available to the current credential. Provider, workspace, and agent grants remain separate access checks.
Input fields
Section titled “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
Section titled “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
Section titled “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
Section titled “Complete input contract”Download the JSON schema for action-specific unions, nested fields, and validation constraints. This schema is generated from the same released definitions as the MCP endpoint. Browse tools.