Maze

Read a drafting session as it now stands — from `draft_unmoderated_study`, `draft_ai_moderated_study`, `edit_unmoderated_study` or `plan_study` — or, while a turn is still working, how long it has been running. Use when one of those tools returned `status: "running"` and you need to know whether that turn has finished, or to re-read a working copy a fresh conversation is resuming. Use first one of them — a session exists only once it has returned a `sessionId`. Don't use to start a study or send the next refinement: that goes back to the tool the session came from, which is the only one that changes it, and `nextStepHint` names which. Don't use for a study already created in Maze — that is `get_unmoderated_study` or `get_ai_moderated_study`. Inputs: `sessionId`, the id that tool returned. Returns `status` — `complete` (read `draft`, absent when the session has none yet) or `running` (no `draft`; `blocksStreamed` or `learningGoalsStreamed` and `draftHash` report progress) — plus `previewUrl` and a `nextStepHint`. A collected turn carries the same readiness signals an inline one would have: `blocksNeedingSetup`/`blocksNeedingBuilderSetup`/`readyToCreate` for an unmoderated builder draft (an edited one carries `blocksNeedingSetup`/`readyToCreate` alone), `goalsNeedingSetup`/`readyToCreate` for an AI-moderated one — and a first unmoderated draft its `requiredBeforeReply`, the calls to make before you reply to the user. Notes: - Read-only and safe to call repeatedly: it never starts, advances, or clears a turn. See also: `draft_unmoderated_study`, `draft_ai_moderated_study`, `edit_unmoderated_study` and `plan_study` own the sessions read here; `nextStepHint` names which.

get_study_draft

Create a real AI-moderated study in the user's Maze workspace from the draft a `draft_ai_moderated_study` session holds. Before creating, tell the user the study is saved to the project they choose and nobody takes it until they share its participant link. Don't call the created study a draft or say it needs launching, and don't say creating it starts collecting participants. Use when the user has seen the current draft's content and said to proceed — "create it", "ship it", "put that in Maze". Use first `draft_ai_moderated_study`: this creates whatever that session last drafted, so refine before creating rather than after. Don't use on a study that already exists, or for unmoderated or moderated studies — an unmoderated draft is created by `create_unmoderated_study`. Confirm in this order: show the user the draft's research context and learning goals from the latest `draft_ai_moderated_study` or `get_study_draft` response and get that content approved — that approval is what `userConfirmedDraft` records — then resolve `projectId` with `search` (`entityTypes: ["project"]`) and confirm which project; there is no default. Asking about the project first reads as though the study is already decided when it isn't. Inputs: `sessionId` of the draft, `projectId`, `userConfirmedDraft`, and `idempotencyKey` — send one on every call so a retry is safe. Returns the new study's `studyUuid` and name, `builderUrl`, `participantUrl` — the link to send participants, or a `shareBlockedReason` in its place when the study cannot be shared yet — and a `nextStepHint`. Notes: - Each call creates a new study, so a retry without the same `idempotencyKey` makes a second one. After a failure, check `get_ai_moderated_study` before retrying. See also: `search` resolves a project name to the id this tool needs; `get_ai_moderated_study` reads the study back once it has sessions.

create_ai_moderated_study

Create a real unmoderated study in the user's Maze workspace from the draft a `draft_unmoderated_study` session holds, and open it in the Maze builder for the user to review and launch. Use when the user has seen the current draft's content and said to proceed — "create it", "ship it", "put that in Maze". Use first `draft_unmoderated_study`: this creates whatever that session last drafted, so refine before creating rather than after. Don't use on a study that already exists — changing one starts at `edit_unmoderated_study` — or for moderated or AI-moderated studies. Confirm in this order: show the user the draft's blocks and settings from the latest `draft_unmoderated_study` or `get_study_draft` response and get that content approved — that approval is what `userConfirmedDraft` records — then resolve `projectId` with `search` (`entityTypes: ["project"]`) and confirm which project; there is no default. Asking about the project first reads as though the study is already decided when it isn't. Inputs: `sessionId` of the draft, `projectId`, `userConfirmedDraft`, and `idempotencyKey` — send one on every call so a retry is safe. Returns the new study's `mazeId` and name, `blockTypes`, `blocksNeedingSetup`, `blocksNeedingBuilderSetup`, `builderUrl`, `participantPreviewUrl`, `issues` and `blockIssues` when something did not go through as drafted, and a `nextStepHint` — the hint states what each link is for. Notes: - Creates a study on every call and is not reversible from here. After a failure, retry with the same `idempotencyKey` — it resumes the same study instead of creating a second one. A retry without it, or with a different key, always makes a new study, so check `get_unmoderated_study` first if you called without one. - `participantPreviewUrl` opens for the user right away; anyone outside the team needs preview sharing turned on for the study from that page first. - For what each name in `blockTypes` means, read `maze://catalog/unmoderated-study-draft`. See also: `search` resolves a project name to the id this tool needs; `get_unmoderated_study` reads the study back once it has responses.

create_unmoderated_study

Build a new AI-moderated Maze study — voice interviews an AI moderator runs around learning goals the user sets — from what the user wants to learn, and reshape it over a conversation. Each call is one turn: pass the goal or the change, and the study comes back as a structured draft of learning goals. Nothing is created in Maze until `create_ai_moderated_study` runs. Use when the user has said what they want to learn from interviews and wants an AI-moderated study built from it. Asking for AI-guided interviews, a conversational study, or voice interviews with an AI moderator settles the method, so it comes straight here. Use first `plan_study` when the choice between unmoderated, moderated and AI-moderated interviews is still open: starting here would make it for the user. Don't use for something participants click through on their own — a test, a survey, a prototype test is `draft_unmoderated_study`, which drafts blocks rather than learning goals — for moderated interviews the user runs themselves, which this server cannot set up, or to read a study that exists (`get_ai_moderated_study`). Inputs: `teamId` and `message`, plus `sessionId` once a conversation is underway. `goals`, `audience`, `artifact`, `participantCount` and `timeline` ride along once the user has stated them; each persists for the rest of the conversation, so send it once. An image for a learning goal stages through `create_study_attachment_upload` first and arrives in `attachments`. Returns `status` — `drafted` (read `draft` and `goalsNeedingSetup`, plus `reply` when the turn follows up), `needs_input` (relay `reply`, and `needs` when present), or `running` — plus `previewUrl` and a `nextStepHint` naming the next action for that status. Notes: - A turn usually drafts and follows up with a question in `reply`; sometimes it returns `needs_input` with only the question. Neither is a failure. Relay the question rather than answering it for the user, and don't collect answers ahead of it — each turn asks for what it needs. - Every turn redesigns the whole study, not just the part named, and no call edits one learning goal exactly. Describe the change in prose and read the draft that comes back. - A goal in `goalsNeedingSetup` cannot run until it has its stimulus: stage an image with `create_study_attachment_upload` and pass the `s3Key` in `attachments`, or ask the user for the website URL. That blocks sharing the study, not creating it. - Don't resolve a project while drafting, even when the user names one in passing; `create_ai_moderated_study` does that once the draft's content is approved. See also: `maze://catalog/ai-moderated-study-draft` explains each learning-goal setting in a draft. `get_study_draft` re-reads a draft and collects a turn that returned `running`; `get_user_details` lists teams; `create_ai_moderated_study` creates the approved draft.

draft_ai_moderated_study

Change an unmoderated Maze study that already exists, over a conversation, saving each turn as it runs. Pass the change, and the updated study comes back as a structured draft, live immediately. Use when the user wants to change a specific unmoderated study that already exists in Maze — reword a question, add or drop a block, change its name, devices or recording settings, attach a Figma prototype — and has named or shown you which one. Editing starts here: the editor reads the study itself, so an ask to edit, change, update or fix one needs no read first. Don't use to build a new study, or to spin off a variant of this one — that is `draft_unmoderated_study`, which never touches the original. Don't use when the user only wants to see a study rather than change it — that is `get_unmoderated_study`. Don't use for moderated or AI-moderated interview studies. Inputs: `studyId` — a numeric maze id or an `app.maze.co` study URL — on every call, the change in `message`, and `sessionId` once a conversation is underway. Files stage through `create_study_attachment_upload` first and arrive in `attachments`. A Figma prototype attaches by sharing its link in `message`, with its password if it has one. Returns `status` — `needs_input` (relay `reply`, and `needs` when present — nothing was saved; also reached when a requested change undid itself back to the study as it stood), `saved` (the full updated study is already in `draft`, alongside `changes`, `mazeId`, `studyName` and `builderUrl` — no separate lookup needed — plus `reply`/`needs` too when the editor also has something to relay) or `reverted` (the same study fields, never `reply`/`needs`), or `running` — plus `issues` and `blockIssues` when something did not go through, and a `nextStepHint` naming the next action for that status. `draft` has the shape `draft_unmoderated_study` returns. Notes: - A `variant_comparison` already in the study is preserved across edits — that split is not branching. - An edit only needs to restate the properties changing — everything else on a block is preserved from before. - `devices`, `recording` and `requiredRecording` can be overridden on this tool's own commit — a capability constraint, not a dropped setting. `issues` flags some overrides but not all, so check the ask against `maze://catalog/unmoderated-study-draft` and tell the user which setting differs and why. - Required recording is all-or-nothing: `requiredRecording` is empty or the same as `recording`. A request to require some recording types and leave others optional cannot be saved — offer all required, none required, or dropping that type from `recording`. See also: `get_study_draft` collects a turn that returned `running`. For what each block type carries, read `maze://catalog/unmoderated-study-draft`.

edit_unmoderated_study

Get the contents of a single AI-moderated (conversational) Maze study from your workspace — study config (research focus, company context, 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, or the link to share it with participants. 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, advancing `offset` by your requested `limit` (not by `sessions.length` — see the `hasMore` field note; 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 (`researchFocus`, `productContext`, `knowledgeGaps`, `companyContext`, `learningGoals`, each goal with its `step` and each question with `showLearningGoalStimuli`; `INTRO` and `CLOSING` goals are returned even with no questions), plus `teamId`, `status` (`SUGGESTED` / `DRAFT` / `LIVE` / `STOPPED`), `participantUrl` (the participant link, or a `shareBlockedReason` in its place when the study cannot be shared yet), `previewEnabled`, participant requirements (`recording`, `requiredRecording`, `deviceRestrictions`), and end-of-study settings (`thankYouMessage`, `redirectAfterSubmit`, `redirectUrl`, `redirectUrlButtonText`). 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. - Give the user `participantUrl` only when they ask to share the study or recruit for it — an answer about results leaves it out. - `recording` lists only the optional media and `requiredRecording` only the mandatory media; they never overlap. An empty `recording` does not mean nothing is recorded; the media the study can record is the two lists combined. 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 a one-time upload URL for an image or PDF the user wants shown on a block in an unmoderated study — a screenshot for a five-second test, a design for context, a terms-of-service PDF on a legal block — or a product photo an AI moderator should show the participant, the image stimulus of an AI-moderated study's learning goal. You upload the file yourself with one short command, then hand the returned `s3Key` to the builder. Use first, before any builder, whenever the user names a real image or PDF for a block, even without saying "upload" — `draft_unmoderated_study` never invents an attachment, so a block that needs one stays empty until a key from here reaches `attachments`. The same holds for an AI-moderated learning goal's image: use this tool first whenever the user names a real file for one — `draft_ai_moderated_study` never invents one either. Don't use to describe an image in words and expect one to be sourced. Don't use for a prototype, a live site, or an app under test — those are `prototype_test`/`website_test`/`app_test` blocks with their own setup, and a Figma prototype link goes in the builder's `message` instead. For which unmoderated block types accept an attachment, read `maze://catalog/unmoderated-study-draft`; for which AI-moderated learning goals do, `maze://catalog/ai-moderated-study-draft`. Inputs: `filename`, `mimeType`, and exactly one of `studyId` (a study that already exists — the value `get_unmoderated_study` or `get_ai_moderated_study` takes) or `teamId` (one still being drafted, which has no id yet). Optionally `contentLength` in bytes. Returns a single-use `uploadUrl` with a ready-to-run `uploadCommand`, the `s3Key` the builder needs once it succeeds, `expiresAt`, a `fallbackPost` for a host that cannot run the command, and a `nextStepHint` with the exact upload steps. Notes: - The grant is single-use and expires at `expiresAt`. If the upload fails or expires, call this again rather than retrying the same `uploadUrl`. - Run `uploadCommand` directly — there is no need to save a script or any grant value to a file first. - This only stages the file. It is attached when `s3Key`, `filename` and `mimeType` reach the builder's `attachments` array with `message` saying which block or learning goal it is for — a key named in `message` alone is rejected. A staged file that never gets there is simply never used. See also: `draft_unmoderated_study` drafts the block the attachment goes on, `edit_unmoderated_study` adds one to a study that already exists, and `draft_ai_moderated_study` drafts the learning goal an image attaches to.

create_study_attachment_upload

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, advancing `offset` by your requested `limit` (not by `sessions.length` — see the `hasMore` field note; any "all / themes / counts / trends" question needs every page, 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 }`. Each team has an `mcpAccess` boolean; only `mcpAccess: true` teams work with team-scoped tools (`search` with a `teamId`, and `get_*` drill-ins). Ignore `mcpAccess: false` teams when choosing a `teamId` or presenting a choice — `disambiguation.required` already counts only accessible teams. To pick among accessible teams: match by name from the conversation ("Acme" → the team whose `name` matches), prefer the `isPersonalTeam` one for "my personal team", else ask. When `disambiguation.required` is true, present the accessible `teams` as a single-choice selection first. `search` needs no `teamId` — omit it to search every team at once.

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