Maze

Get the contents of a single AI-moderated (conversational) Maze study from your workspace — study config (goal, context, plan, conversation guide, learning goals, languages) plus the list of sessions with verbatim turn-by-turn transcripts. This is the entry point for any study-level question, even when you only hold the study deeplink: read the verbatim words here via `detail="full"` — you never switch to `get_ai_moderated_session` to get quotes. Terminology: "session", "interview", and "conversation" mean the same thing here; all three surface as `sessions[]`. Speak the caller's vocabulary back to them when summarising. Use when the caller wants the sessions, transcripts, themes, takeaways, quotes, or any analysis of a known AI-moderated study. Always start at `detail="summary"` (default) — study config + session roster + a `sessionSizeEstimate`, no transcript text — to gauge how heavy the study's transcripts are and pick a read strategy, then switch to `detail="full"` for the verbatim words: page `offset`/`limit` for breadth until `hasMore` is false (any "all / themes / counts / trends" question needs every page, or you return partial data), or read one heavy session at a time with `get_ai_moderated_session`. Once on `full`, stay on `full`. Don't use for moderated (researcher-led) studies (use `get_moderated_study`) or unmoderated studies (use `get_unmoderated_study`). For the URL shapes that route to each kind, see `maze://catalog/study-types`. Inputs: `studyId` (study UUID or deeplink — see `studyId` param for the URL shapes accepted; a `/session(s)/<uuid>` suffix routes to `get_ai_moderated_session` only when the caller asks about that one session, otherwise ignore it. Names not accepted, call `search` first), `detail` (`summary` default / `full`), `includeTranscriptionSummaries` (default false; summary only), `offset` / `limit` (default 10, max 50; detail="full" pages). Returns `{ study, sessions[], hasMore, sessionSizeEstimate? }` (the estimate at `detail="summary"` only). `study` carries the operator-authored research design (goal, context, plan, conversation guide, learning goals). Each session carries `state`, `sourceLabel` (the participant's display label, paired with `sourceUrl`), `language`, `durationMs`, deeplink, and — per `detail` — `transcript.turns[]` with `{speakerName, text}` (at `detail="full"`, absent while processing / no audio) or `transcriptionSummary` (at `detail="summary"` only when `includeTranscriptionSummaries=true`). Notes: - Cite inline: never surface a quote on its own — every quote links back to its source. Attribute a direct quote or one person's view by weaving their `[sourceLabel](sourceUrl)` link into the sentence as the attribution. Never a trailing `Sources:` list, never a bare participant name, never the `participantId`. - `includeTranscriptionSummaries=true` (summary only) attaches a per-session AI `transcriptionSummary` — for surveying across many studies cheaply, not for analysing this one (page `detail="full"` for that). Omitted when a session has no summary yet. - Weight `state: COMPLETED` sessions higher in synthesis. `STOPPED` carries partial content; `IN_PROGRESS` and `NOT_STARTED` may have none. See also: use first `search` to resolve a name to a UUID; use first `get_user_details` when no team is selected; after this `get_ai_moderated_session` for a single session by UUID; prefer `get_moderated_study` or `get_unmoderated_study` for the other study kinds.

get_ai_moderated_study

Get the contents of a single moderated (researcher-led interview) study from your Maze workspace — study metadata plus the list of sessions with participant, scheduling, and verbatim turn-by-turn transcripts. This is the entry point for any study-level question, even when you only hold the study deeplink: read the verbatim words here via `detail="full"` — you never switch to `get_moderated_session` to get quotes. Terminology: "session" and "interview" mean the same thing here; the output uses `sessions[]` for parity with `get_unmoderated_study`. If the caller asks about "interviews", read from `sessions[]`. Use when the caller wants the sessions, transcripts, themes, takeaways, quotes, or any analysis of a known moderated study. Always start at `detail="summary"`, then read: - `detail="summary"` (default): the session roster + a `sessionSizeEstimate`, no transcript text. Token-cheap orientation: read it first to see the study's shape and how heavy its transcripts are, THEN choose how to pull the words — page `detail="full"` for breadth, or read one heavy session at a time with `get_moderated_session`. - `detail="full"`: the same sessions, each with its verbatim `transcript` — the source for quotes and analysis. Page `offset`/`limit` until `hasMore` is false for any "all / themes / counts / trends" question, or you return partial data. Once on `full`, stay on `full` and keep paging — don't drop back to `summary`. Don't use for unmoderated studies (use `get_unmoderated_study`) or AI-moderated / conversational studies (use `get_ai_moderated_study`). For the URL shapes that route to each kind, see `maze://catalog/study-types`. Inputs: `studyId` (UUID or Maze deeplink containing `/projects/<projectId>/interviews/<studyUuid>`; trailing segments tolerated. A bare `/interviews/<studyUuid>` URL with no `/sessions/` segment is a study and routes here, not to `get_moderated_session`. If the URL ends in `/sessions/<sessionUuid>` and the caller asks about that one session, prefer `get_moderated_session`; for study-level analysis use this tool and ignore the session suffix. Names not accepted, call `search` first), `detail` (`summary` default / `full`), `includeTranscriptionSummaries` (default false; summary only), `offset` / `limit` (default 10, max 50; detail="full" pages). Returns `{ study, sessions[], hasMore, sessionSizeEstimate? }` (the estimate at `detail="summary"` only). Each session carries participant, `sourceLabel` (the participant's display label, paired with `sourceUrl`), scheduling, deeplink, and — per `detail` — `transcript.turns[]` with `{speakerName, text}` (at `detail="full"`, absent while processing / no audio) or `transcriptionSummary` (a string, at `detail="summary"` only when `includeTranscriptionSummaries=true`). Notes: - Cite inline: never surface a quote on its own — every quote links back to its source. Attribute a direct quote or one person's view by weaving their `[sourceLabel](sourceUrl)` link into the sentence as the attribution. Never a trailing `Sources:` list, never a bare participant name, never the `participantId`. - `includeTranscriptionSummaries=true` (summary only) attaches a per-session AI `transcriptionSummary` — for surveying across many studies cheaply, not for analysing this one (page `detail="full"` for that). Omitted when a session has no summary yet. See also: use first `search` to resolve a name to a UUID; use first `get_user_details` when no team is selected; after this `get_moderated_session` for a single session by UUID; prefer `get_unmoderated_study` or `get_ai_moderated_study` for the other study kinds.

get_moderated_study

Get the authenticated user's id and the list of teams they belong to from your connected Maze workspace. No parameters — identity is read from the OAuth token. Use when the caller needs basic information about the authenticated user, or when a downstream tool requires a `teamId` and one is not already known from the conversation. Call this first whenever the user asks about "my <thing>" (my studies, my projects, my mazes, my workspaces, my reports, my results) — every per-team list tool needs a `teamId`, and this tool is the only way to discover which teams the caller belongs to. Don't use for looking up other users by id, email, or name. This tool resolves the caller behind the OAuth token only. There is no foreign-user-lookup tool today; if the user asks to find someone else, decline rather than calling this tool. Returns `{ user, teams, disambiguation }`. Picking a `teamId` when the user belongs to more than one team: - One team in `teams` — use its `id`. - Multiple — match by team name against the conversation context (user mentioning "Acme" → pick the team whose `name` matches). - "my personal team" / "my own team" — prefer the team where `isPersonalTeam` is true. - None of the above disambiguates — ask the user for drill-in tools (`get_unmoderated_study`, `get_moderated_study`, etc.) that require a single team. `search` handles multi-team natively — omit `teamId` to search across all teams without disambiguation. - `disambiguation.required === true` — present `teams` as a single-choice selection before calling team-scoped drill-in tools.

get_user_details

Get one AI-moderated (conversational) session from your Maze workspace, identified by its session UUID or a deeplink ending in `/session(s)/<sessionUuid>` — participant, conversation lifecycle (`state`, `language`, `durationMs`), and the verbatim turn-by-turn transcript of the session. A URL ending in a `/session(s)/<sessionUuid>` segment is session-scoped and routes here, not to `get_ai_moderated_study` — the study UUID earlier in the path is incidental. Use when the caller already has a single session UUID or a session deeplink — typically because `search` returned an AI-moderated session result, or because the caller is drilling into one row from `get_ai_moderated_study`. The response shape matches a single `sessions[]` entry from `get_ai_moderated_study` (plus `studyUuid`, the parent pointer that the study roster omits), so downstream reasoning is identical. Reads exactly one session. Don't use for study-level analysis — themes or takeaways across multiple sessions start at `get_ai_moderated_study`, even when you were handed a session URL. Don't pass multiple UUIDs — this tool accepts a single session at a time. Don't use for moderated (researcher-led) sessions (use `get_moderated_session`) or unmoderated sessions (use `get_unmoderated_study`). For URL shapes that route to each kind, see `maze://catalog/study-types`. Inputs: `sessionUuid` (UUID or Maze deeplink under a `/conversations/<studyUuid>/` parent — both `/session/<sessionUuid>` and `/sessions/<sessionUuid>` are accepted on input, single value). Returns `{ uuid, studyUuid, state, startedAt, participantId, sourceLabel, participantSource/Role/Anonymized, sourceUrl, language, durationMs, transcript }`. `sourceLabel` is the participant's display label; render it as the inline Markdown link `[sourceLabel](sourceUrl)` when citing. `state` is the conversation lifecycle (NOT_STARTED / IN_PROGRESS / COMPLETED / STOPPED). `language` is BCP 47. `transcript.turns[]` carries the verbatim transcript as `{speakerName, text}` when processed. Notes: - `transcript` is absent when the session is still processing, failed, or has no audio. Session metadata is still returned. - Tool errors when the session UUID points to a moderated (non-AI) session — use `get_moderated_session` for those. - Weight `state: COMPLETED` higher in synthesis; `STOPPED` carries a partial transcript. - `studyUuid` is the parent study; pass to `get_ai_moderated_study` to navigate siblings. See also: after `search` when it returned an `ai_moderated_study` result or a session URL under `/conversations/`; after `get_ai_moderated_study` when drilling into one row; use first `get_ai_moderated_study` for several sessions or when no UUID is known; prefer `get_moderated_session` for moderated (researcher-led) sessions.

get_ai_moderated_session

Get one moderated interview session from your Maze workspace, identified by its session UUID or a deeplink ending in `/sessions/<sessionUuid>` — participant, scheduling, and the verbatim turn-by-turn transcript of the session. A URL ending in `/sessions/<sessionUuid>` is session-scoped and routes here, not to `get_moderated_study` — the study UUID earlier in the path is incidental. Use when the caller already has a single session UUID or a session deeplink — typically because `search` returned a moderated-session result, or because the caller is drilling into one row from `get_moderated_study`. The response shape matches a single `sessions[]` entry from `get_moderated_study` (plus `studyUuid`, the parent pointer that the study roster omits), so downstream reasoning is identical. Reads exactly one session. Don't use for study-level analysis — themes or takeaways across multiple sessions start at `get_moderated_study`, even when you were handed a session URL. Don't pass multiple UUIDs — this tool accepts a single session at a time. Don't use for AI-moderated (conversational) sessions — use `get_ai_moderated_session`; see `maze://catalog/study-types` for the URL patterns that route to each kind. Inputs: `sessionUuid` (UUID or Maze deeplink ending in `/sessions/<sessionUuid>` — plural is the only accepted form for moderated session URLs, unlike AI-moderated which accepts both; single value). Returns `{ uuid, studyUuid, status, startedAt, participantId, sourceLabel, participantSource/Role/Anonymized, scheduledEvent, sourceUrl, transcript }`. `sourceLabel` is the participant's display label; render it as the inline Markdown link `[sourceLabel](sourceUrl)` when citing. `transcript.turns[]` carries the verbatim transcript as `{speakerName, text}`. Notes: - `transcript` is absent when the session is still processing, failed, has no audio, or has status `NO_RECORDING` / `IN_RECRUITMENT`. Session metadata is still returned. - `studyUuid` is the parent study; pass to `get_moderated_study` to navigate siblings. See also: after `search` when it returned a `moderated_session` result; after `get_moderated_study` when drilling into one row from a sessions list; use first `get_moderated_study` when the caller wants several sessions or has no UUID yet.

get_moderated_session

Get the contents of a single unmoderated Maze study from your workspace — study metadata, block definitions, per-block aggregate stats, sessions with per-participant block-by-block answers, and the Figma prototype reference when present. Three response modes selected by `detail`. Use when the caller wants block performance, the block-by-block contents, sessions, per-participant answers, themes, or takeaways from a known unmoderated study. Pick `detail` by what is needed — when in doubt, start with `summary` and only escalate when the question genuinely requires session-level data: - `detail="summary"` (default): study structure + per-block aggregate stats — `maze` + `blocks` + `blockStats` (+ `prototype` when present). Token-cheap. Call this first to discover block ids needed for filters. For any "analyse / explore / show me results" prompt where study size is unknown, start here. - `detail="sessions"`: paginated sessions only — `sessions[]` + `hasMore`. No `maze` / `blocks` / `blockStats`. Multiple-choice answers emit resolved label strings (e.g. `["Yes", "No"]`). Use for every page after the initial `summary` call. - `detail="full"`: everything in one call. Only when the caller has explicitly asked for both structure and sessions AND the study is known to be small. For non-trivial studies this re-sends the (static) structure on every page — prefer the `summary` → `sessions` chain. Don't use for standalone moderated or AI-moderated (conversational) studies — use `get_moderated_study` or `get_ai_moderated_study`. Don't use for searching/discovery — if the caller has only a name, call `search` first. Accepts a numeric Maze id or any Maze deeplink URL containing `/mazes/<mazeId>`; trailing segments are ignored. Notes: - For per-block-type answer fields, marker precedence (`skipped` / `ack` / `unsupported`), `_internalBlockRef` join semantics, prototype path/screenViews handling, variant-comparison embedding, `blockStats` aggregation rules per block kind, and the `noResponses` marker (a block flagged with it had zero responses — report that as such when it's in scope, not as data the API couldn't return, and never surface the field name; its absence is not a signal), read `maze://catalog/block-types`. - For filter grammar (24 attributes, AND-combine, block-content vs session-metadata, alias rules), read `maze://dsl/unmoderated-filters`. Block-content filters need a `blockId` from a prior `detail="summary"` call (`blocks[].id`, the underlying uuid — not `_internalBlockRef`). - Screeners are qualifying questions asked before the study begins: participants answer them up front, and only those who match the criteria are `accepted` and proceed into the study — the rest are `rejected` (screened out). In-maze and premium-recruitment screening are merged and surfaced uniformly, one entry per question text. A screener's questions group under `blocks[].questions[]`, per-session Q&A under `blockAnswers[].answers[]` (each carries the participant `answer` plus an `_internalQuestionRef` joining to its question; a per-question `outcome` appears only on a disqualifying answer), and aggregates under the top-level `screenerStats` (qualified/disqualified funnel + per-question distributions). Filter with the `screener` attribute (`questionText` + `answers`; maze-scoped, no `blockId`). - Cite inline: attribute each finding, stat, or answer at the point you use it as a Markdown link — `[sourceLabel](sourceUrl)` for a participant's answer, the block or study `sourceUrl` for an aggregate stat. Never a trailing `Sources:` list, never a bare `participantId`. - `_internalBlockRef` values (e.g. `__1__`) and session array indices (e.g. "session 0") must never appear in user-facing output — resolve refs via `blocks[]._internalBlockRef`, and cite a session by its `sourceLabel` link rather than its array position. - Page `sessions[]` with `offset` / `limit`. `limit` defaults to 50, max 100. For analytical questions ("all", "every", themes, counts, trends, whole-study synthesis), iterate until `hasMore` is false, advancing `offset` by your requested `limit` (not by `sessions.length` — see the `hasMore` field note). Stopping early returns partial data and wrong totals. Stop after one page only when the caller asked about a specific subset. - To narrow `blockAnswers[]` to specific blocks, pass `blockIds: ["<uuid>"]`. Sessions with no answer to any of those blocks are dropped from the page. - Verbatim transcripts (when present) are large — start with the default `limit` and only raise it after confirming budget headroom. See also: use first `search` to resolve a name to an id; use first `get_user_details` when no team is selected.

get_unmoderated_study

Fetch the full markdown body of one Maze MCP reference resource by slug, returning the canonical maze://<category>/<name> URI and the resource text. This is a fallback to the MCP resources/read protocol method — prefer resources/read (with resources/list) wherever the host supports it, and don't call this tool there. Use it only when the host does not expose the MCP resources protocol (some custom clients) and you need the reference text to interpret another tool's parameters or response. The body is reference documentation only — no study data, user data, or per-account state. Available slugs: `maze://catalog/block-types` (unmoderated study block kinds and the answer fields `get_unmoderated_study` returns), `maze://catalog/study-types` (the three Maze study kinds and which drill-in tool handles each), `maze://catalog/source-citations` (how to cite Maze evidence — the sourceUrl → entity mapping and evidence-linking rules), and `maze://dsl/unmoderated-filters` (the filter attributes `get_unmoderated_study` accepts). Inputs: a single resource slug (the accepted set is the `resource` parameter's enum; the slug is the URI minus the maze:// prefix, e.g. `catalog/block-types`). Returns `{ uri, content }` — the echoed maze:// URI and the resource body as markdown.

get_resource

Find entities — studies, highlights, themes, tags, interviews, sessions — across your connected Maze workspace. The primary discovery entrypoint when the caller names an entity without a UUID or URL. Use when the caller needs to find entities by keyword, topic, creator, or natural-language description across one or more entity types. Omit `teamId` to search across all teams the user belongs to — no need to call `get_user_details` first. Pass `teamId` to scope to a single team (use `get_user_details` to discover team IDs). After `search` resolves a study id, drill in with `get_unmoderated_study`, `get_moderated_study`, or `get_ai_moderated_study` — see `maze://catalog/study-types` for which drill-in fits each kind. Don't use when you already have the study or session UUID — call the drill-in tool directly with the UUID or deeplink. Don't use for open-ended research questions that need AI synthesis — this tool returns structured search results, not AI-generated answers. Don't use for fetching session-level answers or transcripts of a known study — use the matching drill-in instead. Inputs: `teamId` (optional — omit to search all teams, or pass a team ID from `get_user_details` to scope to one), `query` (natural-language keywords; pass empty string to browse with filters only), plus optional `entityTypes`, `workspaceIds`, `projectIds`, `studyIds`, `creatorIds`, `creatorNames`, date range, `detail` (`summary` / `standard` / `full`), and `cursor` (to page — see Returns). UUIDs, numeric ids, and Maze deeplink URLs are all accepted on the id filters and normalised server-side — see each parameter's description for the accepted shapes. Returns a ranked list with `type`, `id`, label, location breadcrumb, and creator. When more results remain, the response carries a `nextCursor`: call `search` again with that value as `cursor` to fetch the next page (only `limit` is honoured then — `query` and filters are ignored). Paged responses also carry a `relevanceNote`, because results are ranked and later pages are progressively less relevant. `resultsTruncated: true` means the full result set exceeds the reachable ceiling and those extra results cannot be paged to — narrow with more specific query terms or filters to surface them. Page with `nextCursor` while it is present; `resultsTruncated` is the cue to refine the search, not to stop paging. Notes: - Entity-type aliases: `highlight` covers manual highlights AND AI-generated insight highlights; `theme` covers manual tags AND AI-generated themes. Omit `entityTypes` to span every indexed type. - Don't pass URLs in `query` — the engine tokenises them literally. Put study / project / workspace URLs in the matching `*Ids` filter. A nested conversation URL (e.g. `/conversations/<uuid>/session/<sessionUuid>`) collapses to its parent study; `studyIds` does not scope at the session level. - Use `creatorIds` when you have a creator UUID or ID (e.g. from `get_user_details`). Use `creatorNames` when you have a human name. Ambiguous names (e.g. "Jeff" matches multiple) surface a structured error listing candidates — ask the user which one and retry with the full name or a creatorId. - `query` is the keyword core of the request, not the full sentence. For filter-only queries (e.g. "all studies by Jeff"), pass an empty string for `query`. - Malformed or unknown URLs surface a structured validation error naming the bad input. Do not silently retry — ask the user to confirm the URL.

search

Log friction with this MCP server that wouldn't show up in normal error tracking — capability gaps, workflows that took many calls to satisfy a single user intent, or concrete user dissatisfaction tied to a specific tool. Not for transient errors, timeouts, or 5xx; those are tracked elsewhere. Fire when ALL are true: 1. The issue is in this server, not user input or another MCP. 2. It is reproducible — another caller making the same request would hit the same problem. 3. Either the user surfaced it as a concrete complaint about this server, or you observed it yourself and a model using these tools optimally would still have hit it (i.e. it isn't just a path a more careful caller could have avoided). Three categories: - `feature_request` — a capability the user needed doesn't exist here. - `workflow_friction` — one user intent forced many calls or excessive intermediate context to answer. Includes the case where discovery lacks aggregate metadata, filtering, or sorting and forces broad enumeration (e.g. user asks for "studies with >50 responses" and discovery exposes no response-count filter — that is a capability gap, not a reason to enumerate every study and guess). - `bug` — a successful-looking call returned misleading or wrong data (e.g. a search returned empty when matching data demonstrably exists, or a flag claimed "not truncated" while the result set was capped). Do not file for: user input mistakes; vague dissatisfaction; expected output caps; hierarchical workflows that scale predictably (`search` → drill-in, `get_user_details` → other tools); or the same root cause already filed this session. Fire as the last tool call before your reply (the conversation may end). At most once per distinct issue per session. Inputs: `category`, `comment` (1–3 sentences: tool, what was sent, what was missing or misleading), optional `tool_name`, optional `tags`. Returns `{ acknowledged: true }`. Notes: - Keep `comment` factual and short. Never echo user message content or PII — the reader sees this alongside trace data, not in isolation. - If the same problem keeps coming up across calls, that is one issue, not many.

submit_mcp_feedback