# commentary_research

Research workflow capability version 2. Discover and observe linear Content, Activity, and Form steps without UI scraping. Start with action=discover_capabilities. Read actions are list_studies, get_s

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

Research workflow capability version 2. Discover and observe linear Content, Activity, and Form steps without UI scraping. Start with action=discover_capabilities. Read actions are list_studies, get_study, list_sessions, get_session, list_steps, get_step, list_step_telemetry, list_events, list_comments, and list_responses.

## 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` | `"discover_capabilities"` · `"list_studies"` · `"get_study"` · `"list_sessions"` · `"get_session"` · `"list_steps"` · `"get_step"` · `"list_step_telemetry"` · `"list_events"` · `"list_comments"` · `"list_responses"` · `"reply_comment"` · `"ask_follow_up"` | Yes | Operation to perform. Choose one advertised value; the remaining parameters are interpreted for that action. |
| `studyId` | string | No | Stable Research Study identifier. |
| `researchStudyId` | string | No | Stable Research Study identifier; accepted as an explicit alias of studyId. |
| `sessionId` | string | No | Stable Draft, or Research session identifier, as applicable to the selected tool. |
| `researchSessionId` | string | No | Stable Research participant-session identifier; accepted as an explicit alias of sessionId. |
| `parentCommentId` | string | No | Comment identifier that the new reply or follow-up belongs beneath. |
| `commentId` | string | No | Stable Commentary comment identifier. |
| `interventionId` | string | No | Stable intervention identifier used by the selected Commentary Research action. |
| `actionId` | string | No | Stable action identifier used by the selected Commentary Research action. |
| `status` | `"requested"` · `"completed"` · `"failed"` · `"cancelled"` | No | Status filter or requested state supported by the selected action. |
| `target` | object | No | Explicit source or repository destination used by the selected action. |
| `format` | `"json"` · `"markdown"` | No | Allowed format value for the selected Commentary Research 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. |
| `statusNote` | string | No | Status note used by the selected Commentary Research action. |
| `errorMessage` | string | No | Error message used by the selected Commentary Research action. |
| `bodyMarkdown` | string | No | Markdown body for the comment, reply, note, or report produced by the selected action. |
| `body` | string | No | Plain-text body accepted by actions that support a non-Markdown alias. |
| `question` | string or object | No | Question used by the selected Commentary Research action. |
| `title` | string | No | Human-readable title for the created or updated artifact. |
| `questionText` | string | No | Question text used by the selected Commentary Research action. |
| `note` | string | No | Note used by the selected Commentary Research action. |
| `noteMarkdown` | string | No | Note markdown used by the selected Commentary Research action. |
| `notesMarkdown` | string | No | Notes markdown used by the selected Commentary Research action. |
| `summary` | string | No | Concise human-readable summary produced or stored by the selected action. |
| `severity` | `"info"` · `"low"` · `"medium"` · `"high"` · `"critical"` | No | Allowed severity value for the selected Commentary Research action. |
| `confidence` | `"low"` · `"medium"` · `"high"` | No | Allowed confidence value for the selected Commentary Research action. |
| `finding` | object | No | Finding object used by the selected Commentary Research action. |
| `evidenceIds` | array of string | No | Evidence ids values used by the selected Commentary Research action. |
| `kind` | `"participant_comment"` · `"form_response"` · `"researcher_note"` · `"activity_outcome"` · `"behavior_signal"` | No | Allowed kind value for the selected Commentary Research action. |
| `reviewStatus` | `"unreviewed"` · `"in_review"` · `"reviewed"` | No | Allowed review status value for the selected Commentary Research action. |
| `durabilityState` | `"not_selected"` · `"pending"` · `"syncing"` · `"synced"` · `"conflict"` · `"failed"` · `"restricted"` · `"withdrawn"` | No | Allowed durability state value for the selected Commentary Research action. |
| `revision` | number | No | Revision used by the selected Commentary Research action. |
| `segment` | string | No | Segment used by the selected Commentary Research action. |
| `report` | object | No | Report object used by the selected Commentary Research action. |
| `markdown` | string | No | Markdown used by the selected Commentary Research action. |
| `sections` | object | No | Sections object used by the selected Commentary Research action. |
| `evidenceReferences` | array of object | No | Evidence references values used by the selected Commentary Research action. |
| `formId` | string | No | Stable Commentary Form identifier. |
| `questionId` | string | No | Stable Form question identifier. |
| `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. |
| `sessionStatus` | `"active"` · `"completed"` · `"abandoned"` | No | Allowed session status value for the selected Commentary Research action. |
| `stepId` | string | No | Stable Research workflow step identifier. Write actions must target the current step. |
| `eventType` | string | No | Event type used by the selected Commentary Research 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_research"` 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-research.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).