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 pair an inline one would have: `blocksNeedingSetup`/`readyToCreate` for an unmoderated draft, `goalsNeedingSetup`/`readyToCreate` for an AI-moderated one. Notes: - Read-only and safe to call repeatedly: it never starts, advances, or clears a turn. - An unmoderated draft never carries answer-conditional logic, and `readyToCreate` does not track it, so never read one as having branching wired — see `maze://catalog/unmoderated-study-draft`. 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 a draft that `draft_ai_moderated_study` produced. The draft's research context and learning goals are all applied, and the study opens in Maze 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_ai_moderated_study`: there must be a draft on the session, and this tool creates whatever that session last drafted, so refine before creating rather than after. Don't use to change a study that already exists, and don't use for unmoderated or moderated studies — that is `create_unmoderated_study`, which this tool does not create. Confirm in this order. First, show the user the draft's research context and learning goals from the latest `draft_ai_moderated_study` response and get them to approve that content — that approval is what `userConfirmedDraft` records. Only once they have, resolve `projectId` with `search` (`entityTypes: ["project"]`) and confirm which project — there is no default and nothing is created anywhere they did not choose. Don't ask which project before the user has seen what will be created; asking first reads as though the study is already decided when it isn't. Inputs: `sessionId` of the draft, `projectId` to create it in, and `userConfirmedDraft` — `true` only after the content approval above, never a default set ahead of it. Pass `idempotencyKey` to make a retry after a timeout or dropped connection safe — see Notes. Returns the new study's `studyUuid`, its name, and `builderUrl` — the link to open it in Maze. Surface that link; it is what the user does next. Notes: - AI-moderated studies are a paid add-on — a team lacking it sees a `[PLAN_UPGRADE_REQUIRED]` error naming the entitlement; relay that to the user rather than retrying. - Not reversible from here, and calling twice with no `idempotencyKey` creates two studies. Pass `idempotencyKey` so a retry for the same attempt is safe: a call reusing that value returns the study the first attempt created rather than making another. Without one, if a call fails, say so rather than retrying blind — check with `get_ai_moderated_study` whether one was created. - The study is created as a draft in Maze. It is not live and collects no interviews until the user launches it themselves. - The drafting session stays usable afterwards, but further refinement does not change the study that was just created. 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` and saves through `update_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`, `builderUrl`, and a `nextStepHint`. Notes: - Creates a study on every call and is not reversible from here. A retry without the same `idempotencyKey` makes a second study — after a failure, check `get_unmoderated_study` before retrying. - 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

Draft an AI-moderated Maze study — AI-guided voice interviews following a script the user defines — from what the user wants to learn, and reshape it over a conversation. Each call is one turn: pass the user's goal or the change they want, and the study comes back as a structured draft of conversation topics (learning goals) the AI moderator will explore. 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 is already enough — the research goal is the precondition, not the wording. Use first `plan_study` when the choice between unmoderated, moderated and AI-moderated interviews is genuinely still open; starting here would settle that by default rather than on the merits. Don't use for unmoderated studies or surveys — that is `draft_unmoderated_study`, which drafts an ordered block list rather than conversation topics, and is picked when the user wants something self-serve for participants to click through rather than a guided interview. Don't use for moderated interviews the user schedules and runs themselves — this server cannot create those. Don't use to read an existing study — that is `get_ai_moderated_study`. Once a draft exists, calling again with the same `sessionId` and a refinement redrafts the whole study; there is no exact-edit tool for a single learning goal. Inputs: `teamId`, the user's message, and the `sessionId` from the previous call once a conversation is underway. When the user has already named a workspace or given a team id, pass it straight through — `get_user_details` is only needed to discover which teams exist. Pass `goals`, `audience`, `artifact`, `participantCount`, and `timeline` whenever the conversation has already resolved them, instead of folding them into `message` — the builder reads a resolved field as a fact rather than re-deriving it from prose, and it persists across the whole conversation once sent. `message` still carries everything else: the ask itself, nuance, and a follow-up refinement. Pass `attachments` — files already uploaded via `create_study_attachment_upload` — to set a real image as an IMAGE learning goal's stimulus; say which goal each one is for in `message`. Returns `status`: `"drafted"` carries the `sessionId` to replay and `draft` — the study's research context and its ordered learning goals, each with its discussion depth, format, and any scripted questions — alongside `goalsNeedingSetup` and `readyToCreate`. A false `readyToCreate` means the learning goals it names still need an image or website URL — call `create_study_attachment_upload` then pass its `s3Key` back here in `attachments` for an image, or ask the user for a website URL, before the study can launch; that stops the study launching, not the caller creating it. `"needs_input"` means the builder needs something from the user before it can draft or redraft — a clarifying question, or why it would not make the change asked for — in `reply`, plus `needs` when it also proposed ready-made answers structured for clickable UI. `"running"` means the turn is still working; it carries `elapsedMs` and `pollAfterMs` instead. The response always carries `previewUrl` — a link to a read-only, live-updating preview of the session in a browser. Hand it to the user as soon as it appears, even on a `"needs_input"` turn with no draft yet: the page renders learning goals as they stream in, not just the finished result of the last turn. Notes: - The first call usually returns `status: "needs_input"` instead of drafting. That is the builder working as intended, not a failure to retry. Answer only what the user has already told you. Anything that is theirs to decide — research goals, priorities, audience, which topics to probe — goes back to them before the next call, never inferred on their behalf. - A clarifying turn (no draft yet) typically replies within a few seconds; a drafting turn runs a multi-step model call and can take tens of seconds, occasionally longer. When it runs long this call returns `status: "running"` rather than waiting further — call `get_study_draft` with the same `sessionId` to collect the result once it finishes, following its `nextStepHint`. Do not call `draft_ai_moderated_study` again for the same `sessionId` just to check on it; the second call is rejected while the first is still running. - Every turn redesigns the whole study from the conversation, not just the part named. So describe the change you want in prose, and read the draft that comes back rather than assuming only that change landed. - Don't resolve or search for a project while drafting, even when the user names one in passing. That happens once, in `create_ai_moderated_study`, after the user has approved the draft's content. - Drafting does not create anything in Maze. The draft lives server-side for 7 days; tell the user what was drafted rather than pointing them at the app. - AI-moderated studies are a paid add-on — a team lacking it sees a `[PLAN_UPGRADE_REQUIRED]` error naming the entitlement; relay that to the user rather than retrying. See also: `get_user_details` lists the teams to choose from when the user has not named one. `plan_study` decides which of Maze's three study types fits a goal, when that is still open; pass this tool the same `goals`/`audience`/`artifact`/`participantCount`/`timeline` it already gathered as structured fields, not its `sessionId` — planning and drafting are separate conversations. `create_study_attachment_upload` stages a real image before it can be passed here in `attachments`. `create_ai_moderated_study` creates the drafted study once the user has approved it.

draft_ai_moderated_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. 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`), plus `teamId`, `status` (`SUGGESTED` / `DRAFT` / `LIVE` / `STOPPED`), `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. - `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 POST the file yourself, 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`; an AI-moderated learning goal's stimulus is not covered there. 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 `uploadUrl` and `uploadFields` for the multipart POST, the `s3Key` the builder needs once it succeeds, `expiresAt`, 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`. - Send the multipart POST as one direct command built from the values you already have — there is no need to save `uploadFields`, the token or a script 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

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