# MCP server tools

Every tool the Brizz MCP server exposes — name, what it does, required scope, and full arguments — in one page.

The complete tool reference for the Brizz MCP server. To connect your agent in the first place, see [MCP server](/docs/integrations/mcp-server/overview.md).

## How your agent finds a tool

Every Brizz tool is listed directly — there is no discovery step. Your agent
picks a tool by name from its own tool list and calls it:

```json
{ "tool": "brizz_search_sessions", "arguments": { "limit": 20 } }
```

Modern clients (Claude Code, Claude Desktop, VS Code Copilot) load tool
definitions on demand and search them by name, description, and argument
names, so a long list costs no context until a tool is actually used.

Reach for `brizz_ask_agent` only when no typed tool answers the question — open-ended diagnostics like *"why are users frustrated?"* or *"what's regressing?"*, or when someone explicitly asks for the analyst. For a known object, a filtered search, or a raw metric series, the typed tools are faster and cheaper.

Not sure where to start on an open-ended investigation? Call `brizz_list_skills` for the runbooks this server ships (diagnose a session, root-cause an issue, triage a service, analyze tool failures, chase a cost spike, reproduce a user complaint), then `brizz_get_skill` to load one.

## All tools at a glance

All 34 tools. Tools marked **write** need the `mcp:write` scope; everything else needs `mcp:read`. A token without `mcp:write` is not shown the write tools at all.

| Tool | What it does | Scope |
| --- | --- | --- |
| `brizz_ask_agent` | Ask the analytics agent an open-ended question. | **write** |
| `brizz_list_skills` | The investigation runbooks this server ships, with when to use each. | read |
| `brizz_get_skill` | One runbook's full step-by-step instructions. | read |
| `brizz_whoami` | The user, tenant, scopes, and visible services behind the current token. | read |
| `brizz_describe_schema` | What's filterable in this tenant: metric catalog, issue enums, intent labels, property names. | read |
| `brizz_list_services` | The monitored services for your tenant, default first. | read |
| `brizz_list_session_filters` | The fields you can filter sessions by, and the operators each accepts. | read |
| `brizz_list_custom_properties` | Service-defined property keys such as `plan_tier` or `account_id`. | read |
| `brizz_search_sessions` | Find sessions by time window, organization, or filter conditions. | read |
| `brizz_get_session` | One session's metadata by id — no transcript. | read |
| `brizz_get_conversation` | One session's full transcript: messages and tool calls. | read |
| `brizz_get_session_spans` | One session's raw OTel spans — attributes, status, timing — for deep loop/error reconstruction. | read |
| `brizz_get_conversation_item` | One conversation turn's complete content: message, tool input/result, reasoning, error detail, span attributes. | read |
| `brizz_get_session_tool_schemas` | The tool definitions a session's calls resolved to, as the model saw them at call time. | read |
| `brizz_aggregated_data_for_sessions` | Count, average, and median duration over every session matching a filter. | read |
| `brizz_aggregate_sessions` | Grouped distribution (count or custom metrics) over sessions matching a filter, partitioned by one or more dimensions. | read |
| `brizz_aggregate_tool_calls` | Grouped distribution over individual tool calls — rank tools by call volume, or compute a per-call success rate. | read |
| `brizz_list_event_names` | The custom event names a service emits, with occurrence counts. | read |
| `brizz_get_sessions_events` | Event payloads for a set of known session ids. | read |
| `brizz_get_sessions_first_user_messages` | The opening user message for a set of known session ids. | read |
| `brizz_get_session_errors` | The errors recorded across a set of known session ids, in one query. | read |
| `brizz_search_issues` | Find issues by status, priority, severity, org, journey, or user. | read |
| `brizz_get_issue` | One issue's detail, evidence sessions, and activity log. | read |
| `brizz_investigate_issue` | The curated "Fix with your agent" handoff document — concept guidance, agent setup, whether a system prompt was captured, per-finding evidence, and windowed conversation snippets. | read |
| `brizz_get_issue_findings` | The per-finding evidence rows behind an issue: reasoning, error type, analyzer metadata, session/span pointers. | read |
| `brizz_get_issue_prompt` | The full captured system prompt(s) for an issue, one per agent. | read |
| `brizz_update_issue` | Change an issue's status, priority, assignee, or title. | **write** |
| `brizz_query_metric` | A time-bucketed series for cost, sessions, active users, errors, or issues. | read |
| `brizz_list_organizations` | Organizations ranked by activity, with usage counters. | read |
| `brizz_get_organization_overview` | A consolidated brief for one organization, or tenant-wide. | read |
| `brizz_get_user_usage` | One user's sessions, active dates, durations, journeys, and opening prompts. | read |
| `brizz_continue_agent_conversation` | Start or continue an analyst conversation across turns. | **write** |
| `brizz_list_reports` | The CSV/JSON report exports a user has saved for a service. | read |
| `brizz_download_report` | One saved report's contents, inline and bounded. | read |

## Scopes

Every tool requires either `mcp:read` or `mcp:write`. Read tools are available to any connected token; write tools are only listed to a token that carries `mcp:write`, and are refused at call time without it.

Three tools require `mcp:write`: `brizz_update_issue`, `brizz_ask_agent`, and `brizz_continue_agent_conversation`. A read-only token never sees them in its tool list — so an agent connected read-only can browse and analyze your data but cannot change it or spend an analyst turn.

## Service scoping

Most tools accept an optional `service_name`. Leave it out and the server resolves it for you — your configured default service, your only service, or the most recently active one. Pass it explicitly only when you want a specific one, and call `brizz_list_services` when the server reports a "multiple services" ambiguity or you want to compare across services.

## Working with ids

Session, trace, span, issue, cluster, journey, and label ids are opaque. Pass them back verbatim — never abbreviate, truncate, or reconstruct one. They're fixed width: session and trace ids are 32 hex characters, span ids are 16, and issue/cluster/journey/label ids are 36-character UUIDs.

## Identity and schema

Two orientation tools. Both are cheap — they run no heavy queries — and both are worth calling once at the start of a session so the agent works from real values instead of guesses.

### `brizz_whoami`

Returns the identity behind the current token: user, tenant (workspace), granted scopes, and the services the token can see. Takes no arguments.

```json
{ "tool": "brizz_whoami", "arguments": {} }
```

### `brizz_describe_schema`

Describes what's available for filtering, grouping, and querying in the tenant: the metric catalog, issue priority/severity/status enums, the top intent labels in use, available custom-property names with sample values, the resolved organization-identifier property, journeys, and example queries.

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `service_name` | string | No | Scope custom-property samples and intents to one service. |

## Sessions and conversations

Finding conversation sessions and reading what happened inside them. The usual path is discover filters, search, then drill in:

`brizz_list_session_filters` → `brizz_search_sessions` → `brizz_get_conversation`

### `brizz_list_services`

Lists the telemetry services (apps) monitored for the tenant. Returns each service's id, name, `is_default`, `last_event_at`, and `session_count_7d`, default service first. Takes no arguments.

Call this only when the server returns a "multiple services" ambiguity error, or when someone wants to compare services.

### `brizz_list_session_filters`

Lists the fields you can filter sessions by, with the operators and value shape each accepts — tool calls, user, journey, metrics, intents, issues, labels, cohorts, and more.

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `service_name` | string | No | Scope to one service so per-service dynamic filters (e.g. system-event values) are included. |

### `brizz_list_custom_properties`

Lists the custom-property keys attached to a service's sessions — e.g. `plan_tier`, `account_id`, `environment`. These are service-defined, so the list is dynamic and paginated.

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `service_name` | string | No | Defaults to the resolved service. |
| `limit` | integer | No | Keys per page. Default 100, max 500. |
| `offset` | integer | No | Pagination offset, default 0. The response reports the next offset when more keys remain. |

To filter by a returned key, pass it as a condition `field` to `brizz_search_sessions` with `filter_type` set to `custom_properties`.

### `brizz_search_sessions`

Searches conversation sessions for one service. Returns a paginated, sorted list with high-level metadata — no transcripts.

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `service_name` | string | No | Defaults to the resolved service. |
| `organization_id` | string | No | Restrict to one organization. Uses a dedicated endpoint and **cannot be combined with `filters`**. |
| `filters` | array | No | Filter conditions, all AND-ed together. See the condition shape below. |
| `session_ids` | array of strings | No | Restrict the search to a known set of session ids, verbatim. Bounds content scans. Max 500. |
| `time_range` | string | No | Shorthand window like `24h`, `7d`, `30d`. Default `7d`, max `90d`. Overridden by `start`/`end`. |
| `start` | string | No | Inclusive RFC3339 start. Overrides `time_range`. |
| `end` | string | No | Exclusive RFC3339 end. Overrides `time_range`. |
| `limit` | integer | No | Default 50, max 200. |
| `offset` | integer | No | Default 0. |
| `order_by` | string | No | `start` (default), `end`, or `duration`. |
| `order_dir` | string | No | `asc` or `desc`. Default `desc`. |
| `response_format` | string | No | `concise` (default, top 10), `detailed` (up to `limit`), or `raw` (structured content only). |

#### Filter conditions

Each entry in `filters` is an object:

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `field` | string | Yes | A field from `brizz_list_session_filters`, e.g. `toolName`, `userId`, `journeyId`. |
| `operator` | string | Yes | An operator that field accepts, e.g. `equals`, `contains`, `contains_all`, `contains_any`, `gt`, `exists`. |
| `value` | any | No | Multi-value operators (`contains_all`, `contains_any`, `include`, `exclude`) take a comma-separated string such as `"bash,read_file"`. `contains`/`not_contains` take a string or array of strings. Other operators take a single scalar. Ignored for `exists`. |
| `filter_type` | string | No | Copied verbatim from the field's `filterType` column. Required for custom-property fields — set it to `custom_properties`. Omit for builtin fields. |

```json
{
  "tool": "brizz_search_sessions",
  "arguments": {
    "time_range": "7d",
    "limit": 20,
    "filters": [
      { "field": "toolName", "operator": "contains_any", "value": "bash,read_file" },
      { "field": "plan_tier", "operator": "equals", "value": "enterprise", "filter_type": "custom_properties" }
    ]
  }
}
```

### `brizz_get_session`

Fetches metadata for one session by id: start/end, user, journey, model, cost, outcome. No transcript.

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `service_name` | string | No | Defaults to the resolved service. |
| `session_id` | string | Yes | Full session id, verbatim as returned by `brizz_search_sessions`. |

### `brizz_get_conversation`

Fetches the full transcript for one session — user and assistant messages plus tool calls. Applies the same smart-display filter as the dashboard: prefers display variants over raw items, drops internal tool-call bookkeeping, and keeps interrupts and errors. Conversation content is escaped before rendering, so adversarial session text can't inject formatting.

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `service_name` | string | No | Defaults to the resolved service. |
| `session_id` | string | Yes | Full session id, verbatim. |
| `limit` | integer | No | Max turns. Default 200, max 200. |
| `offset` | integer | No | Pagination offset for long transcripts. |

### `brizz_get_session_spans`

Returns one session's **raw spans** as structured JSON — the underlying OpenTelemetry records, not the filtered conversation items `brizz_get_conversation` returns. Each span carries its attributes (tool-call arguments and results, model metadata), status code and message, span kind, parent id, and timing. Use it when you need to reconstruct exactly what happened inside a session — a loop that never terminated, a tool that kept erroring — where the smart-display transcript drops the evidence. A span's attributes are bounded (50 keys, 2000 characters per value), so a very large tool payload may be truncated.

Each call returns one 50-span page in ingestion order. Walk a long session by paging with `offset` (0, 50, 100, …) until the `returned` count drops below 50, and sort a page by `timestamp` to reconstruct execution sequence — ingestion order is not wall-clock order.

Note: OpenTelemetry span events, such as exception stack traces, are not included; the status code, status message, and span attributes cover most error cases.

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `service_name` | string | No | Defaults to the resolved service. |
| `session_id` | string | Yes | Full session id, verbatim. |
| `offset` | integer | No | Pagination offset; page in 50-span windows until fewer than 50 come back. |

## Session events and cohorts

These work on top of a set of sessions you've already found: quantify the cohort, or pull per-session detail for known ids.

### `brizz_aggregated_data_for_sessions`

Returns aggregate statistics over the **full** set of sessions matching a filter — session count, average duration, and median duration. Use it to answer "how many sessions match X" without fetching every row.

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `service_name` | string | No | Defaults to the resolved service. |
| `filters` | array | No | Same condition shape as `brizz_search_sessions`. |
| `time_range` | string | No | Shorthand like `24h`, `7d`, `30d`. Default `7d`, max `90d`. Overridden by `start`/`end`. |
| `start` | string | No | Inclusive RFC3339 start. |
| `end` | string | No | Exclusive RFC3339 end. |

Because it aggregates server-side, the count reflects every matching session — not just the page `brizz_search_sessions` returned.

### `brizz_aggregate_sessions`

Returns a grouped distribution over the sessions matching a filter: partition by one or more dimensions and get a count — or custom metrics — per group. Use it to answer "what's the distribution of X across these sessions" (for example, count of sessions by model, scoped to an issue) in one call.

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `service_name` | string | No | Defaults to the resolved service. |
| `filters` | array | No | Same condition shape as `brizz_search_sessions` — e.g. scope to an issue. |
| `group_by` | array of strings | Yes | Dimensions to partition by: `model`, `date`, `hour`, `day`, `week`, `month`, `hasError`, `toolName`, `toolFailed`, `hasToolError`, `terminalErrorClass`, `repeatedToolSignature`, `distinctToolCount`, and more. |
| `metrics` | array | No | Metric aggregations, each `{function, field, alias?}`. Defaults to session count. Functions: `count`, `sum`, `avg`, `min`, `max`, `p50`, `p90`, `p95`, `p99`. Fields: `cost`, `duration`, `durationSeconds`, `totalTokens`, `promptTokens`, `completionTokens`, `spanCount`, `traceCount`, or `*` for count. |
| `having` | array | No | Post-aggregation filters on a metric alias, each `{metric, operator, value}`. Operators: `gt`, `gte`, `lt`, `lte`, `equals`. |
| `order_by` | string | No | Metric alias or group dimension to sort by. Defaults to the session count. |
| `order_dir` | string | No | `asc` or `desc`. Default `desc`. |
| `limit` | integer | No | Max groups. Default 100, max 1000. |
| `time_range` | string | No | Shorthand like `24h`, `7d`, `30d`. Default `7d`, max `90d`. Overridden by `start`/`end`. |
| `start` | string | No | Inclusive RFC3339 start. |
| `end` | string | No | Exclusive RFC3339 end. |

It aggregates server-side, so it answers "distribution across all matching sessions" without paging through rows. Example: count sessions by model within one issue.

```json
{
  "tool": "brizz_aggregate_sessions",
  "arguments": {
    "group_by": ["model"],
    "filters": [{ "field": "issue", "operator": "equals", "value": "<issueId>" }]
  }
}
```

Returns one row per group, e.g. `[{model, count}, ...]`.

Every row counts **sessions**, so a session that called one tool five times counts once. To count the calls themselves, use `brizz_aggregate_tool_calls`.

For a per-tool failure rate, group by `toolName` and `toolFailed` — `toolFailed` says whether *that* tool failed in that session. `hasToolError` is session-wide ("failed at something, anywhere"), so `["toolName", "hasToolError"]` answers the different question "sessions that called X **and** failed at anything" and overcounts X's failures.

### `brizz_aggregate_tool_calls`

The per-call counterpart to `brizz_aggregate_sessions`: it returns a grouped distribution over **individual tool calls**. Use it to rank an agent's tools by call volume, compute a real per-call success or error rate, or reconcile a tool-call count with another system.

Counts are tool *executions*. The request rows some SDKs emit alongside an execution are excluded, so nothing is double-counted — pass a `callType` filter selecting `assistant_tool_call` to opt back in.

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `service_name` | string | No | Defaults to the resolved service. |
| `filters` | array | No | Conditions on `toolName`, `toolOutcome`, `errorCategory`, `agentName`, `callType`, `sessionId`, `skillKey`. Operators: `equals`, `not_equals`, `contains`, `not_contains`. Omit `filter_type` or set it to `tool_calls` — custom-property filters are rejected on this source. |
| `group_by` | array of strings | Yes | Dimensions to partition by. Time: `date`, `hour`, `day`, `week`, `month`, `days:N`. Call: `toolName`, `toolOutcome`, `errorCategory`, `agentName`, `callType`, `skillKey`. Dynamic: `customProperty:<key>`. `sessionId` is filter-only. |
| `metrics` | array | No | Each `{function, field, alias?}`. Defaults to a call count. Fields: `*` (count), `duration` (nanoseconds), `durationSeconds`. `toolCount` takes function `distinct` and returns distinct tool names. |
| `having` | array | No | Post-aggregation filters on a metric alias, each `{metric, operator, value}`. |
| `order_by` | string | No | Metric alias or group dimension. Defaults to the call count. |
| `order_dir` | string | No | `asc` or `desc`. Default `desc`. |
| `limit` | integer | No | Max groups. Default 100, max 1000. |
| `time_range` | string | No | Shorthand like `24h`, `7d`, `30d`. Default `7d`, max `90d`. Overridden by `start`/`end`. |
| `start` | string | No | Inclusive RFC3339 start. |
| `end` | string | No | Exclusive RFC3339 end. |

Grouped by `toolOutcome` you get three buckets: `success`, `error`, and `unknown` — the last meaning the SDK emitted no outcome marker. Treat `unknown` as unmeasured rather than folding it into either side.

`unknown` is a **group-by bucket only**, synthesized from an empty stored value. As a *filter* value it matches nothing and returns zero rows without an error, so filter on `success` or `error` and read the `unknown` share off a group-by instead.

```json
{
  "tool": "brizz_aggregate_tool_calls",
  "arguments": {
    "group_by": ["toolName", "toolOutcome"],
    "time_range": "30d"
  }
}
```

This ranks and counts. To read the actual failure messages behind a slice, take the sessions behind it (`brizz_search_sessions` with a `toolName` filter) into `brizz_get_session_errors`.

Note a detection change on 2026-07-27: tool errors recorded before that date are substantially under-counted, so a window straddling it shows a jump that reflects improved detection, not a regression.

### `brizz_list_event_names`

Lists the event names a service emits — custom signals like onboarding, integration, or feedback events — with occurrence counts.

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `service_name` | string | No | Defaults to the resolved service. |
| `limit` | integer | No | Default 100, max 500. |

### `brizz_get_sessions_events`

Fetches named event payloads for a set of known session ids. Returns a map of session id to `{event_name: latest_payload}`.

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `service_name` | string | No | Defaults to the resolved service. |
| `session_ids` | array of strings | Yes | Session ids, verbatim. Must not be empty. |
| `event_names` | array of strings | No | Specific names from `brizz_list_event_names`. Pass `["*"]` or omit for all events. |

```json
{
  "tool": "brizz_get_sessions_events",
  "arguments": {
    "session_ids": ["3023b8d4917218792959925606c29f37"],
    "event_names": ["feedback"]
  }
}
```

### `brizz_get_sessions_first_user_messages`

Fetches the opening user message for a set of known session ids. Returns a map of session id to message text.

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `service_name` | string | No | Defaults to the resolved service. |
| `session_ids` | array of strings | Yes | Session ids, verbatim. Must not be empty. |

### `brizz_get_session_errors`

Fetches every error recorded across a set of known session ids — up to 50 per call, in one query. Use it to check whether a cohort shares a failure instead of pulling each session's transcript; one call costs about what a single `brizz_get_conversation` fetch does.

Two surfaces carry a failure, and they barely overlap, so both are returned and tagged with `source`:

- `error_item` — a standalone error recorded on the session.
- `tool_call` — a tool call whose outcome was an error.

Each error carries its type, category, message, stacktrace, span name, and the tool names called just before it (`preceding_tools`). Sessions with no errors come back listed as checked-and-clean, so "clean" never reads as "not checked".

Two flags mark what a response cannot tell you, rather than letting an absence stand in for an answer:

- `truncated` — the session ran past the per-session cap. It has further errors, and `preceding_tools` may be incomplete, so an empty list here does not mean nothing preceded the failure. Narrow the window or read the session directly.
- `no_detail_recorded` — the failure is real but no error text was stored for it. Failed tool calls from before Brizz recorded tool exceptions separately look like this.

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `service_name` | string | No | Defaults to the resolved service. |
| `session_ids` | array of strings | Yes | Session ids, verbatim. 1–50 per call. |
| `start` | string | No | RFC3339. The time window is the only thing that narrows this scan — pass it whenever you have one. |
| `end` | string | No | RFC3339. |
| `offset` | integer | No | Byte offset into each message and stacktrace, for paging a long value. |
| `max_bytes` | integer | No | Bytes of each message and stacktrace to return (default 2000, max 200000). |

For one session's failures in full turn context, use `brizz_get_conversation` with `filter: "errors"` instead.

## Issues

Issues are aggregated quality problems detected across sessions. These tools mirror the dashboard's Issues page.

### `brizz_search_issues`

Searches issues for a service with the same filters available in the dashboard. Returns issues ranked by priority.

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `service_name` | string | No | Defaults to the resolved service. |
| `search` | string | No | Free-text across issue titles and descriptions. |
| `organization_id` | string | No | Restrict to one organization. |
| `journey_id` | string | No | Restrict to one journey. |
| `user_id` | string | No | Restrict to one end-user. |
| `statuses` | array of strings | No | `open`, `tracked`, `closed`. |
| `priorities` | array of strings | No | `critical`, `high`, `medium`, `low`. |
| `severity_levels` | array of strings | No | Filter by severity level. |
| `time_range` | string | No | Shorthand like `7d`, `30d`. Default `7d`, max `90d`. |
| `start` | string | No | Inclusive RFC3339 start. |
| `end` | string | No | Exclusive RFC3339 end. |
| `order_by` | string | No | Sort field, e.g. `priority`, `last_seen`, `occurrence_count`. |
| `order_dir` | string | No | `asc` or `desc`. |
| `limit` | integer | No | Default 50, max 200. |
| `offset` | integer | No | Pagination offset. |
| `response_format` | string | No | `concise` (default, top 10), `detailed`, or `raw`. |

### `brizz_get_issue`

Fetches one issue's full detail: metadata, the evidence sessions where it was detected, and the activity log when available.

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `service_name` | string | No | Defaults to the resolved service. |
| `issue_id` | string | Yes | Full issue id, verbatim as returned by `brizz_search_issues`. |

From here you can follow an evidence session into `brizz_get_conversation` to see what actually happened.

### `brizz_investigate_issue`

The curated "Fix with your agent" handoff document for one issue: concept guidance for its issue type, the agent's setup (model, params, tools), whether a system prompt was captured (the text itself is not inline — `brizz_get_issue_prompt` returns it), per-finding evidence, conversation snippets windowed around the flagged turns, and a follow-up funnel phrased as `brizz_*` tool calls. A shortcut for starting from one curated document rather than assembling the picture read by read; it is one heavy read, so fall back to the `investigate-issue` runbook if it fails.

The returned markdown is the whole answer and is not truncated by the server: the export applies its own ~40,000-character budget with truncation footnotes and reports the true size in `char_count`, so treat it as self-bounding rather than a capped preview.

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `service_name` | string | No | Defaults to the resolved service. |
| `issue_id` | string | Yes | Full issue id, verbatim as returned by `brizz_search_issues`. |
| `notes` | string | No | Free-text context to steer the investigation — a user complaint, a hypothesis, what you already ruled out. Max 4000 characters. |

```json
{
  "tool": "brizz_investigate_issue",
  "arguments": {
    "issue_id": "550e8400-e29b-41d4-a716-446655440000",
    "notes": "the user says checkout silently fails on the last step"
  }
}
```

Drill into what it points at with `brizz_get_issue_findings` (more evidence rows) and `brizz_get_issue_prompt` (the full captured system prompt).

### `brizz_get_issue_findings`

The per-finding evidence rows behind one issue: reasoning, error type, analyzer metadata, and session/span pointers.

- `brizz_investigate_issue` truncates each finding to 2000 characters and points here for more detail.
- `brizz_get_issue_findings` renders a Markdown table in `content[0].text`, where each Reasoning cell is shortened to the first line and 120 characters.
- `brizz_get_issue_findings` also returns `structuredContent.findings[].reasoning`, which preserves the full reasoning and is referenced by a note below the table whenever the rendered cell is shortened.

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `service_name` | string | No | Defaults to the resolved service. |
| `issue_id` | string | Yes | Full issue id, verbatim. |
| `error_type` | string | No | Restrict to findings tagged with exactly this error type. One value only. |
| `search` | string | No | Substring match against a finding's `description` field. |
| `session_id` | string | No | Restrict to findings from one session id. |
| `limit` | integer | No | Default 50, max 50 — a page this size stays inside the response budget for all but the densest issues; page the rest with `offset`. |
| `offset` | integer | No | Pagination offset. |
| `response_format` | string | No | `concise` (default, top 10), `detailed`, or `raw`. |
| `fields` | array of strings | No | Only these keys on each finding in the structured payload. `finding_id` is always included. Unknown names are reported in `_warnings`, not rejected. |

Pass `fields` on the first call rather than after a truncated one. Each finding's `metadata` is typically about two thirds of the response's bytes, so asking for only the columns you need — say `["session_id", "reasoning", "error_type"]` — usually keeps a dense issue inside the byte budget instead of shedding. `metadata` is also the first thing dropped when a page does exceed the budget; a narrower `fields`, a smaller `limit`, or an added filter brings it back.

### `brizz_get_issue_prompt`

The full captured system prompt(s) for one issue, one entry per agent — the root agent first, then agents owning a finding (alphabetical), then every other agent (alphabetical); an unnamed subagent renders as "Subagent" — nothing else on this server returns system-prompt text. A prompt commonly runs to tens of thousands of characters, so this tool windows it explicitly rather than truncating it silently: each entry reports `{text, length, offset, truncated}`, exactly like `brizz_get_conversation_item`, and you page the rest by re-calling with a larger `offset`.

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `service_name` | string | No | Defaults to the resolved service. |
| `issue_id` | string | Yes | Full issue id, verbatim. |
| `agent_name` | string | No | Restrict to one agent's prompt instead of the whole roster — match a previous call's `agent_name`, or `"root"` for the root agent. |
| `offset` | integer | No | Byte offset into each agent's prompt text. |
| `max_bytes` | integer | No | Bytes of each prompt to return, from `offset`. Default 20000, max 200000. |

Errors clearly when the issue never captured a system prompt, or captured one that came back empty. Paging an individual prompt's `offset` past its true length returns an explicit `offset_past_end` marker rather than a blank result.

### `brizz_update_issue`

Mutates one or more fields on an existing issue. Applies whichever fields are provided and skips the rest. **Partial success is reported** — a failure on one field does not abort the others. Requires `mcp:write`.

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `service_name` | string | No | Defaults to the resolved service. |
| `issue_id` | string | Yes | Issue to update. |
| `status` | string | No | `open`, `tracked`, `ignored`, or `resolved`. |
| `priority` | string | No | `critical`, `high`, `medium`, or `low`. |
| `assignee_id` | string | No | User UUID of the new assignee, who must be a tenant member. |
| `unassign` | boolean | No | Set true to clear the assignee. Mutually exclusive with `assignee_id`. |
| `title` | string | No | New title, 1–500 characters. |
| `response_format` | string | No | `concise` (default), `detailed`, or `raw`. |

```json
{
  "tool": "brizz_update_issue",
  "arguments": {
    "issue_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "tracked",
    "priority": "high"
  }
}
```

Note that the status values accepted by `brizz_update_issue` (`open`, `tracked`, `ignored`, `resolved`) differ from the ones `brizz_search_issues` filters on (`open`, `tracked`, `closed`).

## Metrics

### `brizz_query_metric`

Returns the raw time-bucketed series for **one** activity metric, one row per bucket. Use it when you need the underlying series itself — to plot a chart, sum a total, or feed a calculation.

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `service_name` | string | No | Defaults to the resolved service. |
| `metric` | string | Yes | One of `cost`, `sessions`, `active_users`, `errors`, `issues`. |
| `time_range` | string | No | Shorthand like `24h`, `7d`, `30d`. Default `7d`, max `90d`. |
| `start` | string | No | Inclusive RFC3339 start. |
| `end` | string | No | Exclusive RFC3339 end. |
| `granularity` | string | No | Bucket size: `hour` or `day`. The backend picks a heuristic default if omitted. |
| `organization_id` | string | No | Scope the metric to one organization. |

The result carries the metric name, service, `from`/`to` bounds, a `unit`, and a `points` array of `{timestamp, value}`.

```json
{
  "tool": "brizz_query_metric",
  "arguments": { "metric": "cost", "time_range": "30d", "granularity": "day" }
}
```

## Organizations

Organizations are your end-customers.

### `brizz_list_organizations`

Lists organizations for one service, ranked by activity. Returns a paginated list with usage counters — sessions, users, issues, cost — and lifecycle status.

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `service_name` | string | No | Defaults to the resolved service. |
| `search` | string | No | Free-text across org name and id. |
| `time_range` | string | No | Shorthand like `7d`, `30d`. Default `7d`, max `90d`. Overridden by `start`/`end`. |
| `start` | string | No | Inclusive RFC3339 start. |
| `end` | string | No | Exclusive RFC3339 end. |
| `limit` | integer | No | Default 50, max 200. |
| `offset` | integer | No | Pagination offset. |
| `order_by` | string | No | `lastSeen` (default), `sessionCount`, `userCount`, `totalCostUSD`, `issueCount`, or `activity`. |
| `order_dir` | string | No | `asc` or `desc`. Default `desc`. |

### `brizz_get_organization_overview`

The headline analytics surface. Behaviour depends on whether you pass `organization`:

- **With `organization`** — a single-organization brief: usage counters, quality metrics, top users, top journeys, top issues, and recent sessions, mirroring the dashboard's organization details drawer.
- **Without `organization`** — a tenant-wide overview: top organizations by activity, global totals, and pointers to drill into specifics.

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `service_name` | string | No | Defaults to the resolved service. |
| `organization` | string | No | Organization id, exact name, fuzzy name, or domain. Omit for the tenant-wide overview. |
| `time_range` | string | No | Shorthand like `7d`, `30d`. Default `7d`. |
| `start` | string | No | Inclusive RFC3339 start. |
| `end` | string | No | Exclusive RFC3339 end. |
| `response_format` | string | No | `concise` (default), `detailed`, or `raw`. |

Because `organization` accepts a fuzzy name, multiple matches are possible. In that case the response comes back with `status: ambiguous` and a candidate list so you can pick the right id and call again.

## User usage

### `brizz_get_user_usage`

Fetches a usage rollup for a single end-user: total session count, first and last active dates, average and median session duration, the journeys they engaged with and how many times, and a deduplicated list of their opening prompts.

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `service_name` | string | No | Defaults to the resolved service. |
| `filters` | array | **Yes** | One or more conditions identifying the user. Same condition shape as `brizz_search_sessions`. |
| `time_range` | string | No | Shorthand like `24h`, `7d`, `30d`. Default `30d`, max `90d`. Overridden by `start`/`end`. |
| `start` | string | No | Inclusive RFC3339 start. |
| `end` | string | No | Exclusive RFC3339 end. |

Unlike most tools here, `filters` is required — it's how you say which user you mean.

```json
{
  "tool": "brizz_get_user_usage",
  "arguments": {
    "filters": [{ "field": "userId", "operator": "equals", "value": "u-123" }]
  }
}
```

Or by a custom property such as email — note the `filter_type`:

```json
{
  "filters": [
    {
      "field": "email",
      "operator": "equals",
      "value": "x@example.com",
      "filter_type": "custom_properties"
    }
  ]
}
```

Call `brizz_list_session_filters` first to find the correct field name for your service — user identity is instrumented differently across services. Note the default window here is `30d`, wider than the `7d` used by most other tools.

## Analytics agent

The analytics agent answers questions no single typed tool can. It runs a full agent turn on the Brizz side, so it costs more and takes longer than a typed tool.

Good reasons to use it: open-ended diagnostics like *"why are users frustrated?"* or *"what's regressing this week?"*, questions needing cross-tool orchestration, or when someone explicitly asks for the analyst. Bad reasons: fetching a known object, running a filtered search, or pulling a metric series.

### `brizz_ask_agent`

Sends a single question and returns the analyst's answer. Requires `mcp:write`; without that scope, the tool is omitted from `tools/list` and direct calls are rejected.

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `message` | string | Yes | The natural-language question. |
| `service_id` | string | No | Service UUID. Omit to use the resolved default service. |
| `service_name` | string | No | Service slug. Omit to use the resolved default service. |

Any id you reference in `message` must be passed in full and verbatim as a tool returned it. Ids are fixed width: session and trace ids are 32 hex characters (e.g. `3023b8d4917218792959925606c29f37`), span ids are 16, and issue/cluster/journey/label ids are 36-character UUIDs (e.g. `550e8400-e29b-41d4-a716-446655440000`).

```json
{
  "tool": "brizz_ask_agent",
  "arguments": { "message": "Why did cost spike last Tuesday?" }
}
```

### `brizz_continue_agent_conversation`

Holds a multi-turn conversation with the analyst, so context carries across messages. Requires `mcp:write`. Use it when the question is likely to need clarification or chained follow-ups; for a one-shot question, `brizz_ask_agent` is simpler.

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `method` | string | Yes | `start` to open a new conversation, `send` to post a follow-up. |
| `service_id` | string | No | Service UUID, for `method=start`. Ignored for `send`. |
| `service_name` | string | No | Service slug, for `method=start`. Ignored for `send`. |
| `title` | string | No | Optional title, for `method=start`. |
| `conversation_id` | string | Required for `send` | The conversation to continue. |
| `message` | string | Required for `send` | Follow-up message text. |

```json
{
  "tool": "brizz_continue_agent_conversation",
  "arguments": { "method": "start", "title": "Cost investigation" }
}
```

Then follow up with the returned id:

```json
{
  "tool": "brizz_continue_agent_conversation",
  "arguments": {
    "method": "send",
    "conversation_id": "<id from start>",
    "message": "Break that down by organization."
  }
}
```

## See also

- [MCP server](/docs/integrations/mcp-server/overview.md) — connecting Claude Code, Cursor, Codex, and other clients to Brizz.
- [MCP (auto-instrument your server)](/docs/sdks/mcp.md) — adding Brizz observability to an MCP server you operate.