> ## Documentation Index
> Fetch the complete documentation index at: https://subtext.fullstory.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Reference for Subtext Verify's comment MCP tools — comment-add, comment-list, comment-reply, and comment-resolve — for agent-and-human collaboration on a session or live trace.

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

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`](/docs/verify/skills).

Comments are keyed by **`trace_id`** — the 12-char base62 ID returned by [`live-connect`](/docs/verify/live-tools#connection-views) and by [`review-open`](/docs/session-review/tools-reference#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`.

<Note>
  Pair comments with [`live-signal`](/docs/verify/live-tools#signals) to build a responsive loop: poll for new operator signals, then reply and resolve as you address them.
</Note>

***

### `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.                                     |

```json theme={null}
// 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.                    |

```json theme={null}
// 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. |

```json theme={null}
// 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. |

```json theme={null}
// Tool call
{
  "tool": "comment-resolve",
  "comment_id": "cmt_456"
}
```