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

# Subtext Comment Tools: Collaborate on a Session

> Reference for the Subtext comment MCP tools: comment-add, comment-list, comment-reply, and comment-resolve — for agent-and-human collaboration on a session.

Comments turn a session 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. These tools are part of the core Subtext MCP server.

Comments are keyed by **`trace_id`** — the 12-char base62 ID that `review-open` returns (also returned by the live browser tools). Pass that `trace_id` to anchor a comment to the right session. A legacy `session_id` in `deviceId:sessionId` form is still accepted, but prefer `trace_id`.

<Note>
  Get a `trace_id` from [`review-open`](/docs/session-review/tools-reference#review-open). Every comment tool below accepts it directly.
</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"
}
```