# Tools reference

> Every tool of the Sypnia MCP server: what it is for, its input, and an example call with its result.

Applies to: the Sypnia engine (open source, self-hosted) and Sypnia Cloud (paid service). Status: at launch.  
Source: https://docs.sypnia.com/mcp/tools-reference/

For agents: The ten tools of the Sypnia MCP server (health, problems, problem, problem_prompt, sessions, session, search, performance, uptime, resolve_problem) with input schemas and example results, plus its resources and prompts.

**\[Engine]** **\[Cloud]** The Sypnia MCP server has ten tools. Nine only read. One writes: `resolve_problem`. The tools are the same on the remote server of Sypnia Cloud, on the one a self-hosted engine serves, and on the local `@sypnia/mcp`. Their machine-readable contract is `spec/mcp.json` in the docs repository.

Your client shows the tools under the server's name, `sypnia`. Depending on the client that reads as `sypnia.problems`, `sypnia:problems` or `mcp__sypnia__problems`. It is the same tool.

| Tool              | Use it to                                                     | Writes? |
| ----------------- | ------------------------------------------------------------- | ------- |
| `health`          | Ask «what is failing in production?»                          | No      |
| `problems`        | List problems                                                 | No      |
| `problem`         | Get one problem with everything needed to fix it              | No      |
| `problem_prompt`  | Get the ready prompt of a problem, as text                    | No      |
| `sessions`        | List the sessions a problem affected, or recent sessions      | No      |
| `session`         | Read one session, event by event                              | No      |
| `search`          | Find a problem, session, person, release or page by text      | No      |
| `performance`     | See slow pages, slow or failing API calls, and what got worse | No      |
| `uptime`          | See whether the app answers                                   | No      |
| `resolve_problem` | Mark a problem as resolved after the fix                      | **Yes** |

Rules that hold for every tool:

- **One project.** The API token belongs to one project, so no tool takes a project.
- **Production by default.** Tools that read data take `environment`; leave it out for `production`.
- **Results are JSON.** Each result comes as structured content and, for clients that only read text, as the same JSON in a text block. Fields that are null or empty are left out.
- **Size.** A result is at most 60,000 characters. A longer list is cut and says so in `truncated`.
- **Errors** come back as a tool error with the API's `code` and `message`, for example `not_found: No problem with id or slug 'pay-buton' in project 'shop'.`
- **What results never contain:** what a person typed, replay recordings, page snapshots, ingest keys or tokens.

> **Warning: Results contain text from your app**
>
> Error messages, click labels and page names come from the monitored app and from the people using it. The server tells the agent to treat that text as data and never to follow instructions found in it. See [Security](https://docs.sypnia.com/mcp/security).

### `health`

\[Engine, Cloud]

Answer «what is failing in production?» in one call. Returns the state of the app right now (`failing`, `degraded` or `ok`), the open problems that hit the most people, each told in one plain sentence, any uptime check that is down, pages that got slower, and how fresh the data is. Call this first when the user asks how production is doing, whether a deploy broke something, or what to fix next. To fix one of the problems it returns, call `problem` with its `slug`.

Calls: `GET /v1/summary`

**Input:**

- `since` (string, optional, default `24h`): How far back «now» reaches: a number and a unit (`1h`, `24h`, `7d`), or an ISO 8601 timestamp. From 1h to 7d.
- `environment` (string, optional, default `production`): The environment to look at, for example `production` or `development`.

**Call:**

```json
{
  "name": "health",
  "arguments": {}
}
```

**Result:**

```json
{
  "project": {
    "id": "prj_5k2m9x4q7w1z",
    "slug": "shop",
    "name": "Shop"
  },
  "environment": "production",
  "generated_at": "2026-03-12T10:35:00Z",
  "data_through": "2026-03-12T10:34:10Z",
  "state": "failing",
  "sentence": "1 new problem in the last 24 hours. Every uptime check is up. 1 page got slower.",
  "problems": {
    "open": 1,
    "new": 1,
    "regressed": 0,
    "top": [
      {
        "id": "prb_8f3k2m9x4q7w",
        "slug": "pay-button-does-nothing",
        "sentence": "3 people tried to pay today and could not. The Pay button does nothing since yesterday's change.",
        "title": "createPayment answered 400 in POST /api/checkout",
        "confidence": "high",
        "people": 3,
        "sessions": 3,
        "first_seen": "2026-03-12T09:12:04Z",
        "last_seen": "2026-03-12T10:31:47Z",
        "first_release": "4f2a91c",
        "regressed": false
      }
    ]
  },
  "uptime": {
    "checks": 1,
    "down": []
  },
  "performance": {
    "slower_pages": [
      {
        "route": "/search",
        "lcp_p75_ms": 3100,
        "previous_lcp_p75_ms": 1900,
        "views": 1840
      }
    ],
    "failing_api": []
  },
  "traffic": {
    "sessions": 498,
    "people": 412,
    "errors": 5
  },
  "alerts": {
    "unacknowledged": 1
  }
}
```

### `problems`

\[Engine, Cloud]

List the problems Sypnia found in the app. A problem is a group of failures with one cause (an error, a failing API call), with how many people it hit and since when. Each item has a plain sentence when Sypnia analysed it (`sentence`), else its technical title (`title`), plus `where` in the code and a `confidence` in the cause. Use it to choose what to work on, to check whether a specific failure is already known (`q`), or to see what a release broke (`release`). By default it returns open problems, latest activity first. To fix one, call `problem` with its `slug`.

Calls: `GET /v1/problems`

**Input:**

- `status` (string, optional, default `open`): `open`: happening or not yet marked fixed. `resolved`: marked fixed. `ignored`: known and accepted.
- `q` (string, up to 120 characters, optional): Words to find in the sentence, the title or the file name, for example `checkout` or `amount_required`.
- `release` (string, optional): Only problems seen in this release (the app's version, usually a short git commit such as `4f2a91c`).
- `route` (string, optional): Only problems on this page or API route, for example `/checkout` or `/api/orders/:id`.
- `since` (string, optional, default `30d`): Only problems seen after this moment: `24h`, `7d`, or an ISO 8601 timestamp.
- `sort` (string, optional, default `last_seen`): `people` puts the problems that hit the most people first. One of: `last_seen`, `first_seen`, `people`, `occurrences`.
- `environment` (string, optional, default `production`): The environment to look at.
- `limit` (integer, 1 to 50, optional, default `10`): How many problems to return.
- `cursor` (string, optional): The `next_cursor` of the previous call, to get the next page.

**Call:**

```json
{
  "name": "problems",
  "arguments": {
    "status": "open"
  }
}
```

**Result:**

```json
{
  "problems": [
    {
      "id": "prb_8f3k2m9x4q7w",
      "slug": "pay-button-does-nothing",
      "status": "open",
      "regressed": false,
      "sentence": "3 people tried to pay today and could not. The Pay button does nothing since yesterday's change.",
      "title": "createPayment answered 400 in POST /api/checkout",
      "confidence": "high",
      "where": {
        "file": "src/checkout/checkout.tsx",
        "line": 142,
        "function": "confirmPayment"
      },
      "route": "/checkout",
      "people": 3,
      "sessions": 3,
      "occurrences": 5,
      "first_seen": "2026-03-12T09:12:04Z",
      "last_seen": "2026-03-12T10:31:47Z",
      "first_release": "4f2a91c",
      "url": "https://app.sypnia.com/shop/problems/pay-button-does-nothing"
    }
  ],
  "counts": {
    "open": 1,
    "resolved": 4,
    "ignored": 1
  },
  "next_cursor": null
}
```

### `problem`

\[Engine, Cloud]

Get one problem with its full context for fixing it. Call this before you change any code. It returns: `analysis` (what happened in one sentence, who it hit, since when, the likely cause with its evidence, what to do, and a confidence level); `stack` (the frames of the failure in the project's own files, with the source lines around each; for a failure on the server it is the stack of the error the browser got); `breadcrumbs` (what the person did just before, click by click); `trace` (the failing request followed from the browser to the API to the calls behind it); `release` (the version it started in, with its commits and changed files); `impact` (how many people and sessions); and `sessions` to look at. File paths are relative to the repository root. When `analysis.status` is `not_enough_evidence` or `off`, no cause is given: find it yourself from the stack, the breadcrumbs and the release's changes, and say so to the user. Parts that are missing are listed in `missing` with the reason.

Calls: `GET /v1/problems/{problem}/context`

**Input:**

- `id` (string, required): The problem's `slug` (for example `pay-button-does-nothing`) or its `id` (`prb_…`), as returned by `problems`, `health` or `search`.
- `session` (string, optional): Build the stack, breadcrumbs and trace from this session's occurrence instead of the latest one. A session id from `sessions`.
- `breadcrumbs` (integer, 0 to 100, optional, default `30`): How many events before the failure to include.
- `source_lines` (integer, 0 to 20, optional, default `5`): Lines of source around each frame, on each side.

**Call:**

```json
{
  "name": "problem",
  "arguments": {
    "id": "pay-button-does-nothing"
  }
}
```

**Result:**

```json
{
  "problem": {
    "id": "prb_8f3k2m9x4q7w",
    "slug": "pay-button-does-nothing",
    "kind": "failed_call",
    "status": "open",
    "title": "createPayment answered 400 in POST /api/checkout",
    "route": "/checkout",
    "where": {
      "file": "src/checkout/checkout.tsx",
      "line": 142,
      "function": "confirmPayment"
    },
    "first_seen": "2026-03-12T09:12:04Z",
    "last_seen": "2026-03-12T10:31:47Z",
    "first_release": "4f2a91c",
    "occurrences": 5,
    "people": 3,
    "sessions": 3,
    "url": "https://app.sypnia.com/shop/problems/pay-button-does-nothing",
    "origin": "server"
  },
  "analysis": {
    "status": "ready",
    "sentence": "3 people tried to pay today and could not. The Pay button does nothing since yesterday's change.",
    "who": "3 people. Two of them tried again and gave up.",
    "doing": "Paying for an order, at the last step of checkout.",
    "since": "Yesterday's change, deployed at 18:40. It worked before.",
    "cause": {
      "text": "Release 4f2a91c renamed the cart's total from cart.total to cart.totalCents. The checkout still reads cart.total, so the payment goes out without an amount and the API answers 400.",
      "evidence": [
        {
          "kind": "release_change",
          "ref": "4f2a91c:src/cart/cart.ts",
          "text": "The release renames `total` to `totalCents` in the Cart type."
        },
        {
          "kind": "stack_frame",
          "ref": "src/checkout/checkout.tsx:142",
          "text": "confirmPayment() still passes `cart.total` to createPayment()."
        },
        {
          "kind": "trace",
          "ref": "7c2e9a4b1d8f4e6a9b3c5d7e1f2a4b6c",
          "text": "POST /api/checkout answered 400 with the code `amount_required`."
        },
        {
          "kind": "timing",
          "ref": "4f2a91c",
          "text": "No failure of this kind before the release went live. All 5 failures are on it."
        }
      ]
    },
    "what_to_do": "Read cart.totalCents in confirmPayment(), and show the customer a message when a payment is rejected.",
    "confidence": "high"
  },
  "stack": {
    "origin": "browser",
    "error": {
      "name": "ApiError",
      "message": "POST /api/checkout failed with 400 (amount_required)"
    },
    "symbolicated": true,
    "frames": [
      {
        "function": "createPayment",
        "file": "src/lib/api.ts",
        "line": 27,
        "in_app": true,
        "source": {
          "start_line": 25,
          "lines": [
            "  const res = await fetch('/api/checkout', { method: 'POST', body: JSON.stringify(input) });",
            "  if (!res.ok) {",
            "    throw new ApiError('POST', '/api/checkout', res.status, await errorCode(res));",
            "  }",
            "  return res.json();"
          ]
        }
      },
      {
        "function": "confirmPayment",
        "file": "src/checkout/checkout.tsx",
        "line": 142,
        "in_app": true,
        "source": {
          "start_line": 140,
          "lines": [
            "async function confirmPayment(cart: Cart) {",
            "  setPaying(true);",
            "  const payment = await createPayment({ amount: cart.total, currency: cart.currency });",
            "  router.push(`/orders/${payment.orderId}`);",
            "}"
          ]
        }
      },
      {
        "function": "onClick",
        "file": "src/checkout/pay-button.tsx",
        "line": 18,
        "in_app": true,
        "source": null
      }
    ]
  },
  "breadcrumbs": [
    {
      "offset_ms": 12412,
      "type": "page_view",
      "text": "Opened /checkout (from /cart)"
    },
    {
      "offset_ms": 27090,
      "type": "click",
      "text": "Clicked button «Pay $64.00» in «Your order»"
    },
    {
      "offset_ms": 29310,
      "type": "rage_click",
      "text": "Clicked button «Pay $64.00» 4 more times"
    },
    {
      "offset_ms": 31000,
      "type": "request",
      "text": "POST /api/checkout answered 400 amount_required after 3,870 ms",
      "trace_id": "7c2e9a4b1d8f4e6a9b3c5d7e1f2a4b6c"
    }
  ],
  "trace": {
    "id": "7c2e9a4b1d8f4e6a9b3c5d7e1f2a4b6c",
    "duration_ms": 3870,
    "status_code": 400,
    "spans": [
      {
        "name": "POST /api/checkout",
        "kind": "browser",
        "service": "browser",
        "start_offset_ms": 0,
        "duration_ms": 3870,
        "status": "error"
      },
      {
        "name": "POST /api/checkout",
        "kind": "server",
        "service": "shop-api",
        "start_offset_ms": 14,
        "duration_ms": 3842,
        "status": "error"
      },
      {
        "name": "SELECT carts",
        "kind": "db",
        "service": "shop-api",
        "start_offset_ms": 21,
        "duration_ms": 12,
        "status": "ok"
      },
      {
        "name": "createPayment",
        "kind": "http",
        "service": "shop-api",
        "start_offset_ms": 46,
        "duration_ms": 3790,
        "status": "error",
        "attributes": {
          "peer.service": "payments",
          "http.response.status_code": 400,
          "error.type": "amount_required"
        }
      }
    ]
  },
  "release": {
    "version": "4f2a91c",
    "deployed_at": "2026-03-11T18:40:00Z",
    "previous_version": "9c1e7b2",
    "changes": {
      "commits": [
        {
          "sha": "4f2a91c",
          "message": "Rename cart.total to cart.totalCents"
        }
      ],
      "files": [
        {
          "path": "src/cart/cart.ts",
          "additions": 3,
          "deletions": 3,
          "patch": "@@ -8,7 +8,7 @@ export interface Cart {\n   items: CartItem[];\n   currency: string;\n-  total: number;\n+  totalCents: number;\n }"
        },
        {
          "path": "src/cart/cart-summary.tsx",
          "additions": 2,
          "deletions": 2
        }
      ]
    }
  },
  "impact": {
    "people": 3,
    "sessions": 3,
    "occurrences": 5,
    "people_who_retried": 2,
    "last_success_before": "2026-03-11T17:52:30Z"
  },
  "sessions": [
    {
      "id": "8f3a6c1e9b2d4f07a5c3e1b8d6f4a2c0",
      "started_at": "2026-03-12T10:31:16Z",
      "has_replay": true,
      "occurrences": 1,
      "url": "https://app.sypnia.com/shop/sessions/8f3a6c1e9b2d4f07a5c3e1b8d6f4a2c0?at=31000"
    }
  ],
  "missing": []
}
```

### `problem_prompt`

\[Engine, Cloud]

Get Sypnia's ready-made prompt for fixing one problem, as plain text: what happens, where, why, what to do, how to check, followed by the evidence. It is the same text a person copies from Sypnia into a coding agent. Use it when you want a short brief to follow or to hand to another agent. If you are fixing the problem yourself and want structured data, `problem` returns the same facts as JSON, with more detail.

Calls: `GET /v1/problems/{problem}/prompt`

**Input:**

- `id` (string, required): The problem's `slug` or `id`.

**Call:**

```json
{
  "name": "problem_prompt",
  "arguments": {
    "id": "pay-button-does-nothing"
  }
}
```

**Result:**

```json
{
  "analysis_status": "ready",
  "prompt": "Fix a production bug reported by Sypnia.\n\nWhat happens: clicking Pay does nothing. 3 people hit it today (2026-03-12),\n  since release 4f2a91c (deployed 2026-03-11 18:40 UTC).\nWhere: src/checkout/checkout.tsx:142, confirmPayment()\nWhy: that release renamed cart.total to cart.totalCents, but\n  checkout.tsx still reads cart.total. The payment goes out\n  with amount undefined and the API answers 400.\n  Confidence: high.\nDo: read cart.totalCents in confirmPayment(), and show the\n  customer a message when a payment is rejected.\nCheck: session 8f3a6c1e9b2d4f07a5c3e1b8d6f4a2c0 shows the clicks.\n  Add a test that fails when the amount is missing.\n\n… (the evidence and the rules follow; the full text is on the page «The prompt»)"
}
```

### `sessions`

\[Engine, Cloud]

List sessions: visits of real people to the app. With `problem`, returns the sessions that problem affected, with how many times it happened in each and when. Without it, lists recent sessions, by default only those with trouble (an error, a rage click, a dead click or a failed request); filter by `person`, `route` or `release`. Use it to see who was affected and to pick a session to read with `session`. People are returned as the ids the app gave them, with a name or e-mail only if the app sent those.

Calls: GET /v1/problems/{problem}/sessions or GET /v1/sessions

**Input:**

- `problem` (string, optional): A problem's `slug` or `id`: return the sessions it affected.
- `person` (string, optional): Only sessions of the person with this id. Not with `problem`.
- `route` (string, optional): Only sessions that visited this page, for example `/checkout`. Not with `problem`.
- `release` (string, optional): Only sessions on this release. Not with `problem`.
- `trouble` (boolean, optional, default `true`): `false` also returns sessions where nothing went wrong. Ignored with `problem`.
- `since` (string, optional, default `7d`): Only sessions after this moment.
- `environment` (string, optional, default `production`): The environment to look at.
- `limit` (integer, 1 to 50, optional, default `10`): How many sessions to return.
- `cursor` (string, optional): The `next_cursor` of the previous call.

**Call:**

```json
{
  "name": "sessions",
  "arguments": {
    "problem": "pay-button-does-nothing"
  }
}
```

**Result:**

```json
{
  "sessions": [
    {
      "id": "8f3a6c1e9b2d4f07a5c3e1b8d6f4a2c0",
      "started_at": "2026-03-12T10:31:16Z",
      "duration_ms": 42000,
      "person": {
        "id": "u_1042",
        "name": "Ada Park"
      },
      "device": "desktop",
      "browser": "Chrome 134",
      "release": "4f2a91c",
      "errors": 1,
      "rage_clicks": 1,
      "failed_requests": 1,
      "has_replay": true,
      "occurrences": 1,
      "first_occurrence_at": "2026-03-12T10:31:47Z"
    },
    {
      "id": "2b7d9e4f1a6c4830b5d2f7e9c1a3b5d7",
      "started_at": "2026-03-12T09:47:40Z",
      "duration_ms": 82000,
      "person": {
        "id": "u_0977"
      },
      "device": "mobile",
      "browser": "Safari 18",
      "release": "4f2a91c",
      "errors": 2,
      "rage_clicks": 0,
      "failed_requests": 2,
      "has_replay": true,
      "occurrences": 2,
      "first_occurrence_at": "2026-03-12T09:48:11Z"
    },
    {
      "id": "c4e1a8f3d7b24c69a0e5d3b1f9c7a5e3",
      "started_at": "2026-03-12T09:11:26Z",
      "duration_ms": 109000,
      "person": null,
      "device": "desktop",
      "browser": "Chrome 134",
      "release": "4f2a91c",
      "errors": 2,
      "rage_clicks": 0,
      "failed_requests": 2,
      "has_replay": true,
      "occurrences": 2,
      "first_occurrence_at": "2026-03-12T09:12:04Z"
    }
  ],
  "next_cursor": null
}
```

### `session`

\[Engine, Cloud]

Read what one person did in one session, as a timeline in plain words: pages opened, things clicked (by their visible label), rage clicks, API calls that failed, errors, forms the browser refused, and custom events. This is the text form of the session's replay: it tells you the steps to reproduce a failure. It never contains what the person typed, and it does not return video or screenshots. By default only notable events are returned; set `notable` to false to also see successful API calls and performance measurements. Use `around` to read the moments before and after a failure.

Calls: `GET /v1/sessions/{session}/events`

**Input:**

- `id` (string, required): The session id, 32 hex characters, from `sessions` or from a problem's `sessions`.
- `notable` (boolean, optional, default `true`): `true`: page views, clicks, rage and dead clicks, errors, failed requests, form failures and custom events. `false`: everything.
- `around` (timestamp, optional): An ISO 8601 timestamp inside the session. Returns the events around it instead of from the start.
- `limit` (integer, 1 to 500, optional, default `100`): How many events to return.
- `cursor` (string, optional): The `next_cursor` of the previous call.

**Call:**

```json
{
  "name": "session",
  "arguments": {
    "id": "8f3a6c1e9b2d4f07a5c3e1b8d6f4a2c0"
  }
}
```

**Result:**

```json
{
  "session": {
    "id": "8f3a6c1e9b2d4f07a5c3e1b8d6f4a2c0",
    "started_at": "2026-03-12T10:31:16Z",
    "duration_ms": 42000,
    "person": {
      "id": "u_1042",
      "name": "Ada Park"
    },
    "device": "desktop",
    "browser": "Chrome 134",
    "release": "4f2a91c",
    "has_replay": true
  },
  "events": [
    {
      "offset_ms": 0,
      "type": "page_view",
      "route": "/cart",
      "text": "Opened /cart"
    },
    {
      "offset_ms": 12412,
      "type": "page_view",
      "route": "/checkout",
      "text": "Opened /checkout (from /cart)"
    },
    {
      "offset_ms": 27090,
      "type": "click",
      "route": "/checkout",
      "text": "Clicked button «Pay $64.00» in «Your order»"
    },
    {
      "offset_ms": 29310,
      "type": "rage_click",
      "route": "/checkout",
      "text": "Clicked button «Pay $64.00» 4 more times"
    },
    {
      "offset_ms": 31000,
      "type": "request",
      "route": "/checkout",
      "text": "POST /api/checkout answered 400 amount_required after 3,870 ms",
      "trace_id": "7c2e9a4b1d8f4e6a9b3c5d7e1f2a4b6c"
    },
    {
      "offset_ms": 31004,
      "type": "error",
      "route": "/checkout",
      "text": "ApiError: POST /api/checkout failed with 400 (amount_required)",
      "problem": "pay-button-does-nothing"
    },
    {
      "offset_ms": 42230,
      "type": "page_leave",
      "route": "/checkout",
      "text": "Left /checkout after 30 s"
    }
  ],
  "next_cursor": null
}
```

### `search`

\[Engine, Cloud]

Find things in Sypnia by text when you do not have an id: problems (by words of their sentence, title, file or function), sessions and traces (by id or its first 8 characters), people and accounts (by id, name or e-mail, if the app sent them), releases (by version) and pages (by route). Use it when the user describes a failure in their own words («the coupon error», «what happened to <ada@example.com>») or pastes an id from somewhere else. Results are grouped by type; follow up with `problem`, `session` or `sessions`.

Calls: `GET /v1/search`

**Input:**

- `q` (string, up to 120 characters, required): The text to look for.
- `types` (array of string, optional): What to look in. Everything when left out. One of: `problems`, `sessions`, `people`, `accounts`, `traces`, `releases`, `pages`.
- `since` (string, optional, default `30d`): Only sessions, traces and activity after this moment count.
- `environment` (string, optional, default `production`): The environment to look at.
- `limit` (integer, 1 to 25, optional, default `5`): Most results per type.

**Call:**

```json
{
  "name": "search",
  "arguments": {
    "q": "ada@example.com"
  }
}
```

**Result:**

```json
{
  "q": "ada@example.com",
  "problems": [],
  "sessions": [],
  "people": [
    {
      "id": "u_1042",
      "name": "Ada Park",
      "email": "ada@example.com",
      "account": {
        "id": "acc_77",
        "name": "Corner Café"
      },
      "last_seen": "2026-03-12T10:31:58Z",
      "sessions": 6,
      "trouble_sessions": 1,
      "latest_sessions": [
        {
          "id": "8f3a6c1e9b2d4f07a5c3e1b8d6f4a2c0",
          "started_at": "2026-03-12T10:31:16Z",
          "trouble": true
        }
      ]
    }
  ],
  "accounts": [],
  "traces": [],
  "releases": [],
  "pages": []
}
```

### `performance`

\[Engine, Cloud]

See how fast the app is for real visitors and what got worse. Without `route` it returns the app's page-load numbers (LCP, INP, CLS and TTFB at the 75th percentile), the pages that got slower against the period before, the slowest pages, API calls that are slow or failing, pages where people rage-click, and how many improvement suggestions are waiting. With `route` it returns the detail of one page: its numbers, the element behind each one (which image is the slow largest paint, which control is slow to respond), the elements people rage-click or click with no effect, and forms the browser refused. Use it when the user asks why a page is slow, what to optimise, or whether a release made things slower. Times are in milliseconds.

Calls: GET /v1/performance, or with `route`: GET /v1/performance/pages, /v1/performance/vitals, /v1/clicks and /v1/form-failures

**Input:**

- `route` (string, optional): A page route, for example `/search`. Leave it out for the whole app.
- `since` (string, optional, default `7d`): The period to measure. It is compared with the period of the same length just before.
- `device` (string, optional): Only measurements from this kind of device. All when left out. One of: `mobile`, `tablet`, `desktop`.
- `environment` (string, optional, default `production`): The environment to look at.

**Call:**

```json
{
  "name": "performance",
  "arguments": {
    "route": "/search",
    "since": "24h"
  }
}
```

**Result:**

```json
{
  "route": "/search",
  "page": {
    "views": 1840,
    "lcp_p75_ms": 3100,
    "previous_lcp_p75_ms": 1900,
    "inp_p75_ms": 180,
    "cls_p75": 0.04,
    "ttfb_p75_ms": 410,
    "poor_share": 0.21
  },
  "elements": {
    "lcp": [
      {
        "selector": "main ul.results > li:nth-child(1) img",
        "kind": "image",
        "samples": 1310,
        "p75_ms": 3200,
        "poor_share": 0.24
      }
    ],
    "inp": [
      {
        "selector": "form.filters select#sort",
        "kind": "pointer",
        "samples": 640,
        "p75_ms": 210,
        "poor_share": 0.03
      }
    ],
    "cls": [
      {
        "selector": "aside.promo",
        "samples": 480,
        "p75": 0.06,
        "poor_share": 0.02
      }
    ]
  },
  "clicks": [
    {
      "selector": "ul.results li .badge",
      "role": "text",
      "label": "Free shipping",
      "clicks": 31,
      "rage_clicks": 2,
      "dead_clicks": 9
    }
  ],
  "form_failures": [],
  "suggestions": [
    {
      "id": "sug_3h7j1k5l9p2o",
      "title": "The search page's first product image loads slowly",
      "status": "new"
    }
  ]
}
```

### `uptime`

\[Engine, Cloud]

See whether the app answers from outside. Returns every uptime check (a URL that Sypnia requests on a schedule) with its status (`up`, `down`, `paused`), since when it is down, how the latest check went and the share of checks that passed in the last 24 hours and 30 days. With `check` it also returns that check's recent incidents, each with its start, end and reason. Use it when the user asks whether the site is down, or was down, and for how long.

Calls: GET /v1/uptime/checks, and GET /v1/uptime/checks/{check_id}/results with `check`

**Input:**

- `check` (string, optional): A check's id (`chk_…`), to also get its incidents.
- `since` (string, optional, default `24h`): With `check`: how far back to look for incidents.

**Call:**

```json
{
  "name": "uptime",
  "arguments": {}
}
```

**Result:**

```json
{
  "down": 0,
  "checks": [
    {
      "id": "chk_1q9w3e7r5t2y",
      "name": "Shop home",
      "url": "https://shop.example.com/",
      "status": "up",
      "down_since": null,
      "last_checked_at": "2026-03-12T10:34:00Z",
      "last_status_code": 200,
      "last_response_ms": 184,
      "uptime_24h": 100,
      "uptime_30d": 99.98
    }
  ]
}
```

### `resolve_problem`

\[Engine, Cloud]

Mark a problem as resolved after its fix is merged or deployed. This is the only tool that changes anything in Sypnia. Call it only when the fix exists in the repository, not when you have merely proposed it, and tell the user you did. It is safe: if the failure happens again Sypnia reopens the problem by itself and alerts. Pass `release` with the version that carries the fix when you know it, so failures from people still on the old version do not reopen it. Resolving a problem that is already resolved changes nothing.

**This tool writes.**

Calls: `POST /v1/problems/{problem}/resolve`

**Input:**

- `id` (string, required): The problem's `slug` or `id`.
- `release` (string, up to 64 characters, optional): The version of the release that carries the fix, usually the short git commit of the fix once deployed.
- `note` (string, up to 500 characters, optional): One line on what fixed it, for whoever reads the problem later: the commit, the pull request, the cause.

**Call:**

```json
{
  "name": "resolve_problem",
  "arguments": {
    "id": "pay-button-does-nothing",
    "release": "5b3c8d2",
    "note": "Fixed in pull request 128."
  }
}
```

**Result:**

```json
{
  "id": "prb_8f3k2m9x4q7w",
  "slug": "pay-button-does-nothing",
  "status": "resolved",
  "resolved_at": "2026-03-12T11:20:44Z",
  "resolved_by": "mcp:Cursor",
  "resolved_in_release": "5b3c8d2",
  "note": "Fixed in pull request 128."
}
```

## Resources

For clients that let a person attach a resource to the conversation. Each returns the same data as a tool.

| Resource                       | What it is                                                                        |
| ------------------------------ | --------------------------------------------------------------------------------- |
| `sypnia://problems/open`       | The open problems in production, as `problems` returns them                       |
| `sypnia://problem/{id}`        | One problem with its context, as `problem` returns it. `id` is the slug or the id |
| `sypnia://problem/{id}/prompt` | The ready prompt of one problem, as plain text                                    |

## Prompts

Ready-made requests that MCP clients show as commands (in Claude Code, `/mcp__sypnia__fix_problem`).

| Prompt          | Arguments      | What it asks the agent to do                                                                                                                                                             |
| --------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `whats_failing` | None           | Check production with `health` and report in plain words, without changing code                                                                                                          |
| `fix_problem`   | `id`, optional | Read the problem's context, confirm the cause in the code, make the smallest fix, add a test, show the change, and call `resolve_problem` once you confirm the fix is merged or deployed |

The full text of `fix_problem`:

```text
Fix the Sypnia problem «{id}». If no id is given, call `problems` with sort `people` and take the first.
1. Call `problem` to get its context. Read the analysis, the stack and the release's changes.
2. Open the files it names and confirm the cause in the code before changing anything. If the code does not match the analysis, stop and tell me what you found.
3. Make the smallest change that fixes the cause. Do not touch unrelated code.
4. Add a test that fails without the fix and passes with it. Run the tests.
5. Show me the change. Do not merge or deploy.
6. When I confirm the fix is merged or deployed, call `resolve_problem` with a one-line note.
```
