# commentary_forms

Validate, fill, submit, list, read, and inspect source-backed Commentary Forms without UI scraping.

Canonical: https://commentary.dev/docs/reference/mcp/commentary-forms

Validate, fill, submit, list, read, and inspect source-backed Commentary Forms without UI scraping.

## 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"` · `"list_result_collections"` · `"list_fillout_links"` · `"create_fillout_link"` · `"revoke_fillout_link"` · `"submit_fillout_link"` · `"list_fillout_results"` · `"create_adaptive_transition"` · `"list_adaptive_transitions"` · `"claim_adaptive_transition"` · `"complete_adaptive_transition"` · `"fail_adaptive_transition"` · `"get"` · `"validate_contract"` · `"validate_answers"` · `"create_submission"` · `"save_draft"` · `"submit"` · `"list_submissions"` · `"get_submission"` · `"export_submission"` · `"list_embedded_answers"` · `"destinations"` · `"writeback_status"` · `"git_result_sync_status"` · `"preview_result_writeback"` · `"writeback_form"` · `"writeback_submission"` · `"list_git_results"` · `"import_git_results"` | Yes | Operation to perform. Choose one advertised value; the remaining parameters are interpreted for that action. |
| `formId` | string | No | Stable Commentary Form identifier. |
| `linkId` | string | No | Stable link identifier used by the selected Commentary Forms action. |
| `filloutLinkId` | string | No | Stable fillout link identifier used by the selected Commentary Forms action. |
| `token` | string | No | Opaque response-link token. Treat it as a secret and send it only to Commentary. |
| `shareToken` | string | No | Opaque share token. Treat it as a secret and send it only to Commentary. |
| `submissionId` | string | No | Stable Form submission identifier. |
| `transitionRecordId` | string | No | Stable transition record identifier used by the selected Commentary Forms action. |
| `adaptiveTransitionId` | string | No | Stable adaptive transition identifier used by the selected Commentary Forms action. |
| `transitionId` | string | No | Stable transition identifier used by the selected Commentary Forms action. |
| `configTransitionId` | string | No | Stable config transition identifier used by the selected Commentary Forms action. |
| `transitionKey` | string | No | Transition key used by the selected Commentary Forms action. |
| `sectionId` | string | No | Stable section identifier used by the selected Commentary Forms action. |
| `state` | `"pending"` · `"claimed"` · `"completed"` · `"failed"` · `"timeout"` · `"fallback"` · `"all"` | No | State filter supported by the selected action. |
| `resultAction` | `"show_section"` · `"complete"` · `"fallback"` | No | Allowed result action value for the selected Commentary Forms action. |
| `completionAction` | `"show_section"` · `"complete"` · `"fallback"` | No | Allowed completion action value for the selected Commentary Forms action. |
| `adaptiveAction` | `"show_section"` · `"complete"` · `"fallback"` | No | Allowed adaptive action value for the selected Commentary Forms action. |
| `section` | object | No | Section object used by the selected Commentary Forms action. |
| `generatedSection` | object | No | Generated section object used by the selected Commentary Forms action. |
| `submissionIds` | array of string | No | Form submission identifiers to process together; at most 50 are accepted. |
| `referenceId` | string | No | Stable reference identifier used by the selected Commentary Forms action. |
| `title` | string | No | Human-readable title for the created or updated artifact. |
| `description` | string | No | Human-readable description for the created or updated artifact. |
| `visibility` | `"private"` · `"shared"` · `"public_placeholder"` | No | Allowed visibility value for the selected Commentary Forms action. |
| `sourceType` | `"commentary"` · `"github"` · `"embedded"` · `"custom"` | No | Origin classification for the created or resolved source artifact. |
| `contract` | object | No | Parsed Commentary Form Contract object to validate or use. |
| `contractSource` | string | No | Literal JSON or YAML Form Contract source to parse and validate. |
| `sourceFormat` | `"json"` · `"yaml"` · `"auto"` | No | Serialization format of the supplied source contract. |
| `sourceMetadata` | object | No | Source metadata object used by the selected Commentary Forms action. |
| `destinationConfig` | object | No | Destination config object used by the selected Commentary Forms action. |
| `target` | object | No | Explicit source or repository destination used by the selected action. |
| `format` | `"json"` · `"yaml"` · `"csv"` | No | Allowed format value for the selected Commentary Forms action. |
| `commitMessage` | string | No | Commit message for an explicit Git writeback operation. |
| `openPullRequest` | boolean | No | Whether an eligible Git writeback action should also open a pull request. |
| `pullRequestTitle` | string | No | Title for the pull request opened by an explicit writeback operation. |
| `pullRequestBody` | string | No | Markdown body for the pull request opened by an explicit writeback operation. |
| `paths` | array of string | No | Source-relative paths used by the selected action. |
| `values` | object | No | Question-id to answer-value object for Form validation or submission. |
| `sourceContext` | object | No | Source identity returned by Commentary and passed back unchanged to scope embedded Form operations. |
| `sourceReviewHref` | string | No | Canonical Commentary review URL associated with the source artifact. |
| `renderer` | object | No | Renderer object used by the selected Commentary Forms action. |
| `shareMode` | `"specific_user"` · `"authenticated"` · `"anonymous"` | No | Allowed share mode value for the selected Commentary Forms action. |
| `replyMode` | `"identified"` · `"anonymous"` | No | Allowed reply mode value for the selected Commentary Forms action. |
| `repeatSubmissions` | boolean | No | Whether to enable repeat submissions for the selected Commentary Forms action. |
| `recipient` | object | No | User identity or recipient descriptor used by an explicitly selected sharing action. |
| `submissionOrigin` | `"api"` · `"mcp"` · `"cli"` · `"agent_api"` | No | Allowed submission origin value for the selected Commentary Forms 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. |

## Call the tool

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