---
title: "MCP tools reference"
description: "Every tool Faylee's MCP server offers to coding agents, with its parameters and what it returns."
canonical: https://faylee.app/docs/agents/tools
---

# MCP tools reference

Faylee's MCP server offers 13 tools. Eleven read, and two write: `add_comment` and `create_recording_link`. Each tool works as the person who connected the agent, so it sees only recordings that person can see. See [MCP server](https://faylee.app/docs/agents/mcp.md) to connect.

Results are text written for a model to read, with images where a picture helps. When a tool fails, it returns an error message the agent can act on, such as a request id that doesn't exist or a time it can't read.

## Common parameters

| Parameter | Accepts |
|---|---|
| `recording` | The Faylee link as pasted: a share, embed or dashboard URL, with or without `?t=`, or a recording id |
| Times (`at`, `from`, `to`) | `1:22`, `1:22.5`, `82s`, `82000ms` or plain milliseconds |
| `search` | Text to match, ignoring case. Only matching lines are returned. |

Every tool writes times as `1:22`, so any time an agent reads can go back into another tool.

## All tools

| Tool | Kind | What it returns |
|---|---|---|
| [`get_guide`](#get_guide) | Read | How to work through a recording, fix what it shows and report back |
| [`open_recording`](#open_recording) | Read | A briefing on the recording and an overview image. Start here. |
| [`get_moment`](#get_moment) | Read | Everything at one time: the screen, speech, clicks, console, requests, drawings and comments |
| [`get_frames`](#get_frames) | Read | Screenshots: an overview, or the screen at up to 8 times |
| [`get_transcript`](#get_transcript) | Read | What the person said, with times |
| [`get_annotations`](#get_annotations) | Read | What people drew, edited and commented, with times |
| [`get_steps`](#get_steps) | Read | Numbered steps to reproduce |
| [`get_console`](#get_console) | Read | Console output and uncaught errors, with stack traces |
| [`get_network`](#get_network) | Read | Requests with ids, status, timing and why failed ones failed, or WebSocket and EventSource traffic |
| [`get_request`](#get_request) | Read | One request in full, with a cURL command |
| [`search_recordings`](#search_recordings) | Read | Recordings in the workspace that match |
| [`add_comment`](#add_comment) | Write | Comments on the recording as the person who connected the agent |
| [`create_recording_link`](#create_recording_link) | Write | A link anyone can use to record their screen for the workspace |

## get_guide

Faylee's playbook for agents, read on demand like a skill. Without a topic, it returns the main workflow: understand what the person meant, look at the moment, find the code, fix it, report back. Call it once before your first recording.

| Parameter | Required | Description |
|---|---|---|
| `topic` | No | One of `workflow`, `moments`, `network`, `console`, `annotations`, `redaction`, `fixing`, `reporting`. Leave it out for the main workflow. |

## open_recording

The first call for any recording. It returns a briefing written for someone who has never seen the recording:

- The title, link, kind, length, date, who made it, and the browser, system and window size.
- What they were trying to do: what they wrote, and the assistant's reading of it with expected behaviour, actual behaviour and likely cause, when the assistant has read the recording.
- The pages they visited, with times.
- Key moments on one timeline: the moment a `?t=` link points at, moments the assistant noted, errors, failed requests with their `#id`, page changes, what they drew, edits they made to the page, and comments pinned to a time.
- What they said while recording, when there is a transcript.
- Comments from the team.
- Strings worth searching the code for: error messages, source locations, failing API paths, GraphQL operations, page paths and the names of elements they clicked.
- Which time to look at first.

After the briefing comes an overview image: frames spread across the recording, each labelled with its time, or the screenshot itself.

| Parameter | Required | Description |
|---|---|---|
| `recording` | Yes | The link or id |
| `overview` | No | Include the overview image. On by default. |

## get_moment

Everything at one time in a recording. The text covers what was on screen and around it: what the person said, what they drew, what they did, console output, requests, edits they made to show how it should look, and comments near that time. Then come two pictures: the screen at that time and the screen 1.5 seconds before. A screenshot gets one picture.

Speech is included from a wider stretch than the rest, five seconds either side, since people talk ahead of and behind what's on screen.

| Parameter | Required | Description |
|---|---|---|
| `recording` | Yes | The link or id |
| `at` | Yes | The time to look at |
| `window` | No | Seconds either side to include. 3 by default, at most 30. |

## get_frames

Screenshots from a recording. With no times, one overview image of frames spread through it, each labelled with its time. With `at`, the screen at up to 8 times, such as the times of errors or of something the person said. Instant replays have no video, so Faylee rebuilds the page from its recorded DOM and takes the picture from that.

| Parameter | Required | Description |
|---|---|---|
| `recording` | Yes | The link or id |
| `at` | No | Up to 8 times |
| `size` | No | `small` (360 pixels high), `medium` (720, the default) or `large` (1080). Use `large` to read small text. |
| `unmarked` | No | For a screenshot the reporter drew on, the copy without the marks |

## get_transcript

Everything the person said while recording, one line per segment with its time. It usually says what they expected and where it went wrong. If the recording has no narration, or the narration is still being transcribed, the tool says so.

| Parameter | Required | Description |
|---|---|---|
| `recording` | Yes | The link or id |
| `search` | No | Only lines containing this text |

## get_annotations

What people pointed at in a recording, with times:

- **Drawn on the screen.** Arrows, circles, boxes and notes, each with the element it points at and where it sits on the page, in pixels from the top left.
- **Edits the reporter made to show how it should be.** Changes to the page's text or styles, with the element, the value before and the value after.
- **Comments.** The team's comments, with their author and time, and where each pinned comment sits as a share of the screen.

For a screenshot someone drew on, it also says that a copy without the marks exists, which `get_frames` returns with `unmarked`.

| Parameter | Required | Description |
|---|---|---|
| `recording` | Yes | The link or id |

## get_steps

What the person did, as numbered steps to reproduce, each with its time: clicks with the element's text and selector, typing and navigation.

| Parameter | Required | Description |
|---|---|---|
| `recording` | Yes | The link or id |

## get_console

The page's console output and uncaught errors, each with its time, level and source. Stack traces point at the original source, with the code around the failing line, when the page's source maps are public.

| Parameter | Required | Description |
|---|---|---|
| `recording` | Yes | The link or id |
| `errors_only` | No | Only errors |
| `search` | No | Only lines containing this text |
| `from` | No | Only lines at or after this time |
| `to` | No | Only lines at or before this time |

## get_network

The page's requests, each starting with a `#id` to pass to `get_request`, then the method, status, duration, URL and GraphQL operation. A failed request has a second line that says why it failed, such as a CORS block or GraphQL errors.

With `sockets`, it lists WebSocket and EventSource connections instead: when each opened and closed, its close code, whether it failed, and its messages with times and direction.

| Parameter | Required | Description |
|---|---|---|
| `recording` | Yes | The link or id |
| `failed_only` | No | Only failed requests |
| `search` | No | Only requests whose URL or GraphQL operation contains this text. With `sockets`, only messages that contain it. |
| `from` | No | Only requests at or after this time |
| `to` | No | Only requests at or before this time |
| `sockets` | No | List WebSocket and EventSource connections instead of requests |

## get_request

One request in full: the method and URL, when it ran, its status and duration, why it failed, the request and response headers and bodies, and a cURL command that replays it. Long bodies are shortened.

| Parameter | Required | Description |
|---|---|---|
| `recording` | Yes | The link or id |
| `id` | Yes | The request's `#id` from `get_network`, `get_moment` or `open_recording`, with or without the `#` |

## search_recordings

Recordings in the workspace, newest first. Each line has the title, the kind, the length, the date, the number of problems when there are any, and the link.

| Parameter | Required | Description |
|---|---|---|
| `query` | No | Text in the title, description, page or transcript |
| `kind` | No | `video`, `replay` or `screenshot` |
| `problems_only` | No | Only recordings with errors or failed requests |
| `since` | No | Only recordings made after this ISO 8601 time |
| `limit` | No | How many to return. 20 by default, at most 50. When more match, the result says so. |

## add_comment

Comments on a recording as the person who connected the agent, optionally at a time, so the comment sits on the timeline. Use it to report back: what was wrong, why, and the fix or pull request, in words the reporter understands. The reporter and the team are notified as for any comment.

| Parameter | Required | Description |
|---|---|---|
| `recording` | Yes | The link or id |
| `body` | Yes | Markdown, at most 5,000 characters |
| `at` | No | The time the comment points at |

The result confirms the comment and gives the recording's link.

## create_recording_link

Creates a recording link: a page where anyone can record their screen and send it to the workspace, with no account or extension. An agent uses it to ask for a clearer repro, such as the same steps with the console open or in another browser. The recording arrives under the person who connected the agent. See [Recording links](https://faylee.app/docs/support/recording-links.md).

| Parameter | Required | Description |
|---|---|---|
| `title` | Yes | What to record, shown to the person |
| `message` | No | Instructions for the person |
| `external_ref` | No | The ticket or conversation this is for. Zendesk and Intercom tickets get a note when the recording arrives. See [Zendesk and Intercom](https://faylee.app/docs/integrations/help-desks.md). |
| `expires_in_days` | No | How many days the link works |

The result is the link to send.

## Prompts

The server also offers one prompt, `investigate_recording`, which runs the whole workflow on a link. It takes `link` and optional `notes`. See [MCP server](https://faylee.app/docs/agents/mcp#the-investigate_recording-prompt).

## Related

- [MCP server](https://faylee.app/docs/agents/mcp.md)
- [The faylee CLI](https://faylee.app/docs/agents/cli.md)