> ## Documentation Index
> Fetch the complete documentation index at: https://subtext.fullstory.com.pgm.c5nprx.cc/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Subtext Session Review: Complete MCP Tools Reference
> Complete reference for all Subtext session review MCP tools: review-list-sessions, review-open, review-summary, review-zoom, review-snapshot, review-close.
Subtext exposes session review as a set of MCP tools your agent calls directly. Each tool has a single, focused responsibility: list sessions, open one, summarize it, zoom into a time window, snapshot a moment, or close the session. This page documents every tool — what it does, what it returns, and how to call it.
These tools are part of the core Subtext MCP server and are available to all users. For live browser, comments, proof docs, and Sightmap tools, see the [Verify (Beta) reference](/docs/verify/overview).
***
### `review-list-sessions`
Find reviewable sessions. With no arguments it returns the most recent sessions for your org — newest first — as session URLs you can pass straight to `review-open`. Pass `email_address` or `user_uid` and it returns one user's sessions instead.
Call this first. Your agent needs to know which sessions exist before it can open one. Ask for as many as you need with `limit`, then pick the most recent, a specific URL, or the session closest to a known incident time.
**Parameters:**
| Parameter | Type | Description |
| --------------- | ------ | ------------------------------------------------------------------------------------------------------------- |
| `limit` | number | Optional. Maximum sessions to return, newest first. Default 10, max 50. |
| `email_address` | string | Optional. Scope the list to the sessions of one identified user. |
| `user_uid` | string | Optional. Same, keyed on the customer-assigned user ID passed at identification. |
| `before` | string | Optional. RFC3339 timestamp — return only sessions created before it. Requires `email_address` or `user_uid`. |
**Returns:** a list of session URLs, newest first. Charges 1 credit.
```json theme={null}
// Tool call
{
"tool": "review-list-sessions",
"limit": 10
}
```
The response is formatted text, not JSON:
```text theme={null}
Found 5 session(s):
1. https://app.fullstory.com.pgm.c5nprx.cc/ui/o-1A2B3C-na1/session/6543210987654321:1234567890 (created 2026-07-21T17:15:08Z)
2. https://app.fullstory.com.pgm.c5nprx.cc/ui/o-1A2B3C-na1/session/6543210987654321:0987654321 (created 2026-07-20T23:07:41Z)
Pass any URL above to review-open as the session_url parameter.
```
#### Finding one user's sessions
Pass the identity you have — an email address from a support ticket, or the `uid` your app sends at identification:
```json theme={null}
// Tool call
{
"tool": "review-list-sessions",
"user_uid": "u-7f3a91"
}
```
The identity-scoped response leads with who that identity resolved to, then reports the creation-time range it covered and whether more history exists before it:
```text theme={null}
User: Jane Doe (uid u-7f3a91)
User properties: {plan=pro, seats=5}
Found 3 session(s) for user uid u-7f3a91:
1. https://app.fullstory.com.pgm.c5nprx.cc/ui/o-1A2B3C-na1/session/6543210987654321:1234567890 (created 2026-08-06T17:23:00Z)
2. https://app.fullstory.com.pgm.c5nprx.cc/ui/o-1A2B3C-na1/session/6543210987654321:0987654321 (created 2026-08-06T15:06:45Z)
3. https://app.fullstory.com.pgm.c5nprx.cc/ui/o-1A2B3C-na1/session/6543210987654321:5432109876 (created 2026-08-06T02:58:09Z)
newest: 2026-08-06T17:23:00Z
oldest: 2026-08-06T02:58:09Z
More sessions exist before this range — call review-list-sessions again with before: 2026-08-06T02:58:09Z
Pass any URL above to review-open to inspect it, or review-summary to compare several before choosing one.
```
To page further back, feed that `oldest` value into `before`. You can also set `before` directly to scope the list to a time window — the afternoon a bug was reported, for example.
`review-open` and `review-summary` also accept `email_address` and `user_uid`, but they jump straight to that user's *most recent* session. Use `review-list-sessions` when you need to see more than one, or when the session you're after isn't the latest.
**Ticket triage.** Given a report against a known user, the three tools compose into a search: list that user's sessions, `review-summary` the candidates to find the one matching the report, then `review-open` the match and investigate.
***
### `review-open`
Open a session for review. Returns a `client_id` for follow-on calls, a `trace_id`, the event map, and a digest rollup of what happened.
The event map is the skeletal outline of the session — pages visited, significant events, rough timestamps — without the full signal detail. Your agent should read the map before zooming in, so it can plan where to spend resolution budget. The digest rollup is a short prose summary of the session arc.
If a sightmap is configured for your project, `review-open` also returns a `sightmap_upload_url`. The Subtext plugin pushes your local `.sightmap/` files to that URL before the first snapshot, so every subsequent `review-snapshot` call is enriched with semantic component names, source paths, visibility, and interactivity instead of raw CSS selectors.
**Parameters:** provide exactly one identifier.
| Parameter | Type | Description |
| ---------------------------- | ------ | ------------------------------------------------------------------------------------------------- |
| `session_url` | string | A Fullstory session URL — e.g. one returned by `review-list-sessions`, or a customer-shared link. |
| `trace_id` | string | A 12-char base62 trace ID from a prior `review-open` or live-tool response. |
| `trace_url` | string | A full trace URL. |
| `device_id` + `session_id` | string | Raw device and session IDs, passed together. |
| `email_address` / `user_uid` | string | Look up the identified user's most recent session. |
**Returns:** `client_id` (for `review-zoom`, `review-snapshot`, `review-close`), `trace_id` (for trace-keyed surfaces like [comments](/docs/verify/comment-tools)), the session's start time and identified user, the event map, the digest rollup, and — if a sightmap is configured — `sightmap_upload_url`.
```json theme={null}
// Tool call
{
"tool": "review-open",
"session_url": "https://app.fullstory.com.pgm.c5nprx.cc/ui/o-1A2B3C/session/6543210987654321:1234567890"
}
```
The response is formatted text, not JSON — a preamble (client ID, session identity, who the user was, sightmap upload URL) followed by the event map:
```text theme={null}
Client ID: a70fd938-67b7-4088-beee-f06fd9e71c9a
Org: o-1A2B3C-na1 | Device: 6543210987654321 | Session: 1234567890
Session start: 2026-08-06T17:23:00 UTC
User: Jane Doe (uid u-7f3a91)
User properties: {plan=pro, seats=5}
sightmap_upload_url: https://st.fullstory.com.pgm.c5nprx.cc/subtext/sightmap?token=...&affinity_key=...
### Session Events
## Map · 42 signals · 0.0s–86s · 2 page(s)
flow: /cart ▸ /checkout
kinds:
navigation 4
interaction 12
network 24 (1 err)
console 2 (1 err)
tags:
error:2
```
The `User:` and `User properties:` lines carry whatever your app sent at identification — display name, email, `uid`, and custom user properties — so your agent can say whose session it's reading instead of quoting a device ID. Both lines are omitted when the session was never identified; individual fields are omitted when unset. `review-summary` and the identity-scoped form of `review-list-sessions` render the same block.
Always read the event map before calling `review-zoom`. The map tells your agent where the interesting moments are, so it doesn't waste resolution budget on quiet periods.
***
### `review-summary`
Get a static "what happened" summary of the session at the default zoom level. It's the cheapest call and completely stateless — it takes a session identifier directly, so you can call it *before* `review-open` (or without opening at all) as a quick first read.
Because it creates no `client_id`, a summary can't be followed by `review-zoom` or `review-snapshot`. When you need higher-fidelity signal over a specific interval, open the session and zoom instead.
**Parameters:** provide exactly one identifier — the same set `review-open` accepts.
| Parameter | Type | Description |
| ---------------------------- | ------ | -------------------------------------------------- |
| `session_url` | string | A Fullstory session URL. |
| `trace_id` / `trace_url` | string | A trace ID or full trace URL. |
| `device_id` + `session_id` | string | Raw device and session IDs, passed together. |
| `email_address` / `user_uid` | string | Look up the identified user's most recent session. |
**Returns:** the same session-identity and `User:` preamble `review-open` renders — minus the client ID and sightmap upload URL, which a summary doesn't mint — followed by a static, one-shot event-stream summary at default resolution. Charges 1 credit; creates no `client_id`.
```json theme={null}
// Tool call
{
"tool": "review-summary",
"session_url": "https://app.fullstory.com.pgm.c5nprx.cc/ui/o-1A2B3C/session/6543210987654321:1234567890"
}
```
`review-summary` is static and stateless. If you need higher-fidelity signal over a specific interval, use `review-open` + `review-zoom` instead.
***
### `review-zoom`
The live lens — zoom into an open session over a specific time window with configurable resolution. Where `review-summary` gives you the frozen overview, `review-zoom` lets you dial up detail over any slice of the signal stream.
`resolution` is an allow-list mapping scopes, kinds, or tags to a grain. Omit it to get every kind at `standard`; provide it and unlisted kinds are excluded from the slice. Overlaps resolve finest-wins, so `{ "network": "standard", "error": "detail" }` reads network normally but expands every error to its full payload.
**Parameters:**
| Parameter | Type | Description |
| ------------ | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `client_id` | string | The client ID returned by `review-open`. |
| `t0_ms` | number | Start of the window, in session-relative milliseconds (inclusive). Both `t0_ms` and `t1_ms` at `0` = full session. |
| `t1_ms` | number | End of the window, in session-relative milliseconds (exclusive). |
| `resolution` | object | Optional. Allow-list mapping a scope (`navigation`, `interaction`, `network`, `console`), a kind (`click`, `network`, `exception`, …), or a tag (`error`, `warn`, `exception`) to a grain: `digest`, `standard`, `machine`, or `detail`. |
The grain ladder, coarse → fine: `digest` (one rollup line per section × kind), `standard` (readable transcript, the default), `machine` (every signal, nothing merged), `detail` (every signal plus payloads — headers, bodies, stack traces).
**Returns:** the selected signals as a transcript over the requested window at the requested grains.
```json theme={null}
// Tool call — the 30-second window around a suspected error, errors at full detail
{
"tool": "review-zoom",
"client_id": "cli_xyz789",
"t0_ms": 45000,
"t1_ms": 75000,
"resolution": { "network": "standard", "error": "detail" }
}
```
Start with the full range and no `resolution` (everything at `standard`) to get your bearings, then narrow the window and raise the grain on the kinds that matter. This keeps token usage predictable.
***
### `review-snapshot`
Capture the screen at a specific moment — returns any of a screenshot, the component tree with component IDs, and per-element bounding boxes. The foreground page is resolved automatically from the timestamp.
This is how your agent sees the UI. The screenshot shows the visual state; the component tree gives it structured access to every element on screen, including `component_id`s it can feed back to root a later snapshot; bounding boxes tell it where things are spatially.
If a sightmap is configured, each matched element in the component tree is annotated with its semantic component name, source file path, visibility flag, and interactivity flag — so your agent reasons about `CheckoutForm (src/components/CheckoutForm.tsx)` rather than `form#cc-form`.
**Parameters:**
| Parameter | Type | Description |
| -------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `client_id` | string | The client ID returned by `review-open`. |
| `timestamp` | number | Session-relative timestamp in milliseconds at which to capture. |
| `component_id` | string | Optional. Roots both the screenshot clip and the returned tree at a single element from a previous snapshot. |
| `lens` | string | Optional. `visible` (default), `interactive` (clickable/typeable elements only), or `full` (every element plus CSS selectors — for sightmap authoring). |
| `include` | array | Optional. Any of `image`, `tree`, `boxes`. Default `[image, tree]`. |
| `expand_pct` | number | Optional (0–100). Grows the `component_id` clip outward for surrounding context. |
| `upload` | boolean | Optional. Store the screenshot as an artifact and return a signed URL. |
**Returns:** screenshot (base64 or URL), component tree with component IDs, and bounding boxes. When a sightmap is configured, each element is also annotated with component name, source path, visibility, and interactivity.
```json theme={null}
// Tool call — snapshot at the moment of the payment error
{
"tool": "review-snapshot",
"client_id": "cli_xyz789",
"timestamp": 62400
}
```
The component tree is returned as an indented text outline. Each node carries a component ID (e.g. `fs-201`), its role or Sightmap component name, and flags like `interactive`:
```text theme={null}
### Snapshot
[root ]
[form fs-201] "CheckoutForm" interactive
[textbox fs-204] "Card number" interactive
[textbox fs-207] "Expiry" interactive
[button fs-210] "Pay now" interactive
```
Pass a node's ID back as `component_id` to root a follow-up snapshot at that element. Add `boxes` to `include` for per-element bounding boxes, or `image` for the screenshot.
***
### `review-close`
Close the session and record structured feedback. Call this when your agent has finished its investigation.
Closing the session frees server resources and logs the review with a conclusion — an audit trail of which sessions were reviewed, what use case drove them, and whether the review helped.
**Parameters:**
| Parameter | Type | Description |
| ------------- | ------- | ---------------------------------------------------------------------------------------------- |
| `client_id` | string | The client ID returned by `review-open`. |
| `use_case` | string | What the session was used for: `bug_diagnosis`, `ux_review`, `support`, `testing`, or `other`. |
| `was_helpful` | boolean | Whether reviewing the session helped you understand the issue. |
**Returns:** confirmation that the session was closed and feedback was recorded.
```json theme={null}
// Tool call
{
"tool": "review-close",
"client_id": "cli_xyz789",
"use_case": "bug_diagnosis",
"was_helpful": true
}
```
Always close sessions when you're done. Recording the use case and whether the review helped keeps a clean log of what your agent investigated.
***
## Tool call order
The tools are designed to be used in sequence. A typical investigation follows this order:
List available sessions and pick the one to investigate.
Cheap, stateless first read — pass a session identifier for a static overview before you commit to opening.
Open the session. Read the event map and digest before doing anything else.
Zoom into the intervals that look interesting. Repeat as needed with progressively narrower windows.
Capture visual snapshots at key timestamps to see exactly what the user saw.
Record your conclusion and close the session.
You don't have to use every tool in every investigation. `review-list-sessions` → `review-open` → `review-zoom` → `review-close` is often enough. Reach for `review-summary` when you want a cheap orientation before opening, and `review-snapshot` when you need visual evidence or a precise component tree.