Comment Tools: Agent-and-Human Collaboration on a Trace

These are Verify beta features, available to the closed beta cohort only. They may change or move out of the core MCP without notice.

Comments turn a trace into a shared workspace. Your agent can leave observations anchored to a page, timestamp, or component; a human can reply; and either side can resolve a thread once it’s addressed. Load the catalog into your agent with /subtext-verify:subtext-comments. Comments are keyed by trace_id — the 12-char base62 ID returned by live-connect and by review-open. Pass that trace_id to anchor a comment to the right trace. A legacy session_id in deviceId:sessionId form is still accepted, but prefer trace_id.

Pair comments with live-signal to build a responsive loop: poll for new operator signals, then reply and resolve as you address them.

`comment-add`

Add a comment to a trace, optionally tied to a page, timestamp, or component. Only text is required. Parameters:

Parameter	Type	Description
`text`	string	The comment. Supports Markdown — bold, italic, lists, links, code spans, and code blocks.
`trace_id`	string	Trace ID to attach the comment to. Preferred.
`session_id`	string	Optional legacy alternative to `trace_id`, in `deviceId:sessionId` form.
`page_id`	string	Optional. Page or tab ID to anchor the comment to.
`timestamp`	number	Optional. Milliseconds relative to session start.
`component_selector`	string	Optional. CSS selector for the related component.
`intent`	string	Optional. The comment’s intent — e.g. `bug`, `tweak`, `ask`, `looks-good`.
`screenshot_url`	string	Optional. URL of a pre-captured screenshot to attach.

// Tool call — flag a bug at a specific moment
{
  "tool": "comment-add",
  "trace_id": "aB3dE6gH9jK2",
  "text": "**Validation error** fires before the card field is touched.",
  "timestamp": 62400,
  "intent": "bug"
}

`comment-list`

List comments for a trace, optionally filtered by page or by parent comment (to fetch a thread’s replies). Parameters:

Parameter	Type	Description
`trace_id`	string	Trace ID to list comments for. Preferred.
`session_id`	string	Optional legacy alternative to `trace_id`, in `deviceId:sessionId` form.
`page_id`	string	Optional. Filter to comments on a single page.
`parent_id`	string	Optional. Filter to replies under a specific comment.

// Tool call
{
  "tool": "comment-list",
  "trace_id": "aB3dE6gH9jK2"
}

`comment-reply`

Reply to an existing comment, forming a thread. Identify the comment by its ID and the trace it belongs to. Parameters:

Parameter	Type	Description
`comment_id`	string	ID of the comment to reply to.
`text`	string	The reply. Supports Markdown.
`trace_id`	string	Trace the parent comment belongs to. Preferred.
`session_id`	string	Optional legacy alternative to `trace_id`, in `deviceId:sessionId` form.

// Tool call
{
  "tool": "comment-reply",
  "comment_id": "cmt_456",
  "trace_id": "aB3dE6gH9jK2",
  "text": "Confirmed — filed as issue #1042."
}

`comment-resolve`

Resolve a comment to mark it as addressed. Takes only the comment ID. Parameters:

Parameter	Type	Description
`comment_id`	string	ID of the comment to resolve.

// Tool call
{
  "tool": "comment-resolve",
  "comment_id": "cmt_456"
}

Overview

Tools Reference

Tunnel

Comment Tools: Agent-and-Human Collaboration on a Trace

`comment-add`

`comment-list`

`comment-reply`

`comment-resolve`

​comment-add

​comment-list

​comment-reply

​comment-resolve

`comment-add`

`comment-list`

`comment-reply`

`comment-resolve`