> ## 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 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, proof docs, and Sightmap tools, see the [Verify (Beta) reference](/docs/verify/overview).
***
### `review-list-sessions`
Find reviewable sessions. Returns a numbered list of available sessions with their URLs and timestamps — giving your agent a map of what's available before it commits to opening anything.
Call this first. Your agent needs to know which session IDs exist before it can call `review-open`. The list is ordered so your agent can pick the most recent session, a specific URL, or the session closest to a known incident time.
**Returns:** numbered list of sessions, each with a session ID, the URL that was active when recording started, and a timestamp.
```json theme={null}
// Tool call
{
"tool": "review-list-sessions"
}
```
```json theme={null}
// Example response (abbreviated)
{
"sessions": [
{ "index": 1, "session_id": "abc123", "url": "https://app.example.com/checkout", "recorded_at": "2025-06-10T14:32:00Z" },
{ "index": 2, "session_id": "def456", "url": "https://app.example.com/dashboard", "recorded_at": "2025-06-10T13:15:00Z" }
]
}
```
***
### `review-open`
Open a session for review. Returns a session handle, 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:**
| Parameter | Type | Description |
| ------------ | ------ | -------------------------------------------------- |
| `session_id` | string | The session ID returned by `review-list-sessions`. |
**Returns:** session handle, event map, digest rollup, and (if sightmap configured) `sightmap_upload_url`.
```json theme={null}
// Tool call
{
"tool": "review-open",
"session_id": "abc123"
}
```
```json theme={null}
// Example response (abbreviated)
{
"handle": "hdl_xyz789",
"event_map": { "...": "..." },
"digest": "User landed on /checkout, attempted payment twice, encountered a form validation error on the second attempt, then abandoned.",
"sightmap_upload_url": "https://upload.subtext.fullstory.com/sightmap/abc123?token=..."
}
```
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. Think of it as a frozen, pre-computed overview — useful as a cheap first read before you start zooming into specifics.
The summary doesn't change between calls; it's a fixed representation of the session computed when the recording was processed. Use it when you want a quick orientation without configuring a time window.
**Parameters:**
| Parameter | Type | Description |
| --------- | ------ | --------------------------------------------- |
| `handle` | string | The session handle returned by `review-open`. |
**Returns:** a static summary of the session — events, page transitions, and notable signals at default resolution.
```json theme={null}
// Tool call
{
"tool": "review-summary",
"handle": "hdl_xyz789"
}
```
`review-summary` is static. If you need higher-fidelity signal over a specific interval, use `review-zoom` instead.
***
### `review-zoom`
The live lens — zoom into 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 session.
Set the resolution to control how granularly the signal stream is sampled, and set the time window to focus on the interval that matters. A higher resolution over a narrower window gives your agent the most detail; a lower resolution over the full session gives a coarser but cheaper overview.
**Parameters:**
| Parameter | Type | Description |
| ------------ | ------ | ---------------------------------------------------------------------------- |
| `handle` | string | The session handle returned by `review-open`. |
| `start_ms` | number | Start of the time window in milliseconds from session start. |
| `end_ms` | number | End of the time window in milliseconds from session start. |
| `resolution` | string | Signal sampling resolution. Higher values return more granular event detail. |
**Returns:** a high-fidelity slice of the signal stream over the requested window at the requested resolution.
```json theme={null}
// Tool call — zoom into the 30-second window around a suspected error
{
"tool": "review-zoom",
"handle": "hdl_xyz789",
"start_ms": 45000,
"end_ms": 75000,
"resolution": "high"
}
```
Start with a wide window and low resolution to get your bearings, then narrow the window and raise the resolution once you know where the interesting events are. This keeps token usage predictable.
***
### `review-snapshot`
Capture the screen at a specific moment — returns a screenshot, the component tree with element UIDs, and bounding boxes for every visible element.
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 UIDs it can reference in other tools; 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 |
| -------------- | ------ | ---------------------------------------------------------------------------------- |
| `handle` | string | The session handle returned by `review-open`. |
| `timestamp_ms` | number | The timestamp in milliseconds from session start at which to capture the snapshot. |
**Returns:** screenshot (base64 or URL), component tree with element UIDs, and bounding boxes. When 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",
"handle": "hdl_xyz789",
"timestamp_ms": 62400
}
```
```json theme={null}
// Example response (abbreviated)
{
"screenshot_url": "https://...",
"component_tree": [
{
"uid": "el_001",
"tag": "form",
"component": "CheckoutForm",
"source": "src/components/CheckoutForm.tsx",
"visible": true,
"interactive": true,
"bounds": { "x": 120, "y": 84, "width": 480, "height": 620 }
}
]
}
```
***
### `review-close`
Close the session and record structured feedback. Call this when your agent has finished its investigation.
Closing the session keeps the MCP server clean and ensures the investigation is logged with a conclusion. The feedback you record here creates an audit trail — useful if you want to trace which sessions were reviewed, what the agent concluded, and what action was taken.
**Parameters:**
| Parameter | Type | Description |
| ---------- | ------ | --------------------------------------------------------------------------------- |
| `handle` | string | The session handle returned by `review-open`. |
| `feedback` | string | A short summary of what the agent found and what action was taken or recommended. |
**Returns:** confirmation that the session was closed and feedback was recorded.
```json theme={null}
// Tool call
{
"tool": "review-close",
"handle": "hdl_xyz789",
"feedback": "Identified a form validation error in CheckoutForm triggered when the card expiry field was left empty. Filed issue #1042."
}
```
Always close sessions when you're done. Leaving sessions open doesn't block further reviews, but recording feedback ensures your team has a log of what was 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.
Open the session. Read the event map and digest before doing anything else.
Get the static overview if you want a quick orientation without configuring a window.
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-snapshot` when you need visual evidence or a precise component tree.