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
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 |
"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
Section titled “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
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.