confirm_study_video_upload
ChatGPTFinish a video upload started with create_study_video_upload, and report whether the video has finished converting. Call it once the upload command has succeeded. Use after create_study_video_upload and its upload command succeeded, and whenever the user asks if their video is ready. Don't use to upload a file, and don't use for images or PDFs. Inputs: the same studyId and blockUuid or blockRef used to start the upload, and its uploadId. Returns processingStatus (PROCESSING, READY or FAILED), processingError on failure, and a nextStepHint. Notes: - Safe to repeat one call at a time: a repeat reports the current status and starts conversion only for an upload that has not started one. See also: create_study_video_upload mints the upload URL this tool confirms.
create_ai_moderated_study
ChatGPTCreate 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_study_attachment_upload
ChatGPTGet 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_video_upload
ChatGPTGet a one-time upload URL for a video the user wants shown in a study that already exists: the video on a block of an unmoderated study, or the video stimulus of an AI-moderated learning goal. You upload the file yourself with one short command, then call confirm_study_video_upload. Use when the user names a real video file (MP4, MOV or WebM, up to 500 MB and 5 minutes). Don't use for an image or PDF, which is create_study_attachment_upload, and don't use before the study is created: a video needs a saved study, so create the study first. For an unmoderated study the block must already exist and have a video slot, or be an AI conversation block in a study that has not launched; for an AI-moderated study the block must exist. Inputs: studyId, then blockUuid (unmoderated) or blockRef (AI-moderated), plus filename, mimeType and the exact contentLength in bytes. replaceImage only after the user agreed to replace a conversation's image. Returns a presigned uploadUrl with a ready-to-run uploadCommand, the uploadId to confirm, expiresInSeconds, and a nextStepHint with the steps. Notes: - The video converts after upload, and a video over 5 minutes fails at that stage, not here. - Unmoderated block video needs the team's block-video feature. When it is off, the call fails as not found, so tell the user the feature may not be enabled for their team. See also: confirm_study_video_upload finishes the upload and reports processing.
create_unmoderated_study
ChatGPTCreate 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, and a nextStepHint — the hint states what each link is for. 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. - 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.
draft_ai_moderated_study
ChatGPTBuild 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), needs_input (relay reply, and needs when present), or running — plus previewUrl and a nextStepHint naming the next action for that status. Notes: - A first call usually returns needs_input: that is the builder asking, not a failure. Relay its question rather than answering it for the user, and don't collect answers ahead of it — the builder 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 turn that continues a draft the user has already seen returns a refinementHint saying how to account for it. - 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_unmoderated_study
ChatGPTBuild a new unmoderated Maze study 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. Nothing is created in Maze until create_unmoderated_study runs. Use when the user has asked for the thing an unmoderated study is — a test, a survey, a prototype test, something to send to participants — and has stated their own goals, in their own words, pointing at this one method. That settles both the method and the direction, so it comes straight here. Use first plan_study when goals are vague, span more than one study direction, or are your own inference or paraphrase of what the user said — even when the user has already named a method — since drafting here would settle a direction they have not actually confirmed. Don't use to change a study that already exists — that is edit_unmoderated_study — to read one (get_unmoderated_study), to find one by name (search), or for moderated or AI-moderated interview studies. Inputs: teamId and message — the user's ask in their own words — plus sessionId once a conversation is underway. After plan_study confirms an unmoderated study, the first call passes its sessionId as planSessionId instead of a message, and the builder starts from that conversation. A first call often comes back asking the user to confirm or sharpen their goals rather than drafting straight away — that confirm turn is normal, not a sign something went wrong. Files stage through create_study_attachment_upload first and arrive in attachments. A Figma prototype attaches by sharing its link in message: the builder checks it and records it on the study. A password-protected prototype has its password entered in the Maze builder, so never ask the user for it or pass one along. Settings are the builder's to change too — the name, the devices participants may take it on, and what is recorded and which recordings are required — asked for in message like any block change. Returns status — drafted (read draft, and reply/needs too when the builder also has something to relay), needs_input (relay reply, and needs when present; no draft, since the study is as the previous call left it — also reached when a requested change undid itself), reverted, or running — plus previewUrl and a nextStepHint naming the next action for that status. A session's first draft also leads with requiredBeforeReply: make those calls before you reply to the user. Notes: - A first call still returns needs_input when something is open. Relay the question rather than answering it: what is the user's to decide — goals, audience, scope, which tradeoff to take — stays theirs. - Review each draft against what the user asked for before showing it. A change the user has asked for in so many words is the next turn's message — send it rather than asking them to confirm it again. Anything else you would change, a draft that misses what they said included, is a proposal: say what and why, and send it only once they agree. - The builder may add a screener unasked, and a screener disqualifies participants. Check it does not exclude a group the user wants to hear from, and raise it before creating if it does. - devices, recording and requiredRecording can be overridden when create_unmoderated_study commits the study — a capability constraint, not a dropped setting. Its 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 drafted — offer all required, none required, or dropping that type from recording. - Leave recording and requiredRecording as the builder set them, which is Maze's recommended setup: change them, or suggest changing them, only when the user asks. Recording is a study-wide setting, not spec…
edit_unmoderated_study
ChatGPTChange 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 a nextStepHint naming the next action for that status. draft has the shape draft_unmoderated_study returns. Notes: - No turn can add answer-conditional logic, so never report branching or skip logic as wired. A variant_comparison already in the study is preserved — 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. Its nextStepHint 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.
get_ai_moderated_session
ChatGPTGet 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_study
ChatGPTGet 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_moderated_session
ChatGPTGet 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_study
ChatGPTGet 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_resource
ChatGPTFetch 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_study_draft
ChatGPTRead 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. 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_preview
ChatGPTGet a study draft in the raw form the inline study-draft card draws: the draft definition as it stands, half-written while a drafting turn streams, with the version counters the card pins itself to. Use only from the study-draft card, which calls it every few seconds to refresh while a turn runs. Don't use to check on a draft, collect a running turn, or re-read a session for the user: that is get_study_draft, which returns progress and readiness you can report. Don't use to change a draft: that goes back to the tool the session came from. Inputs: sessionId, and optionally version to pin the read to one turn's draft. Returns studyType, studyDefinition (null before anything is drafted), updatedAt, isStreaming, latestVersion, and baseVersion on a read of the live draft. A pinned read of a settled AI-moderated version also returns editedUuids, the learning goals that version's turn added or changed.
get_unmoderated_study
ChatGPTGet 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…
get_user_details
ChatGPTGet 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_website_test_snippet
ChatGPTGet the team's Maze tracking snippet for a website test, plus where it goes and how to verify it — the copy-paste <script> tag that turns click tracking on for the team's website blocks. Use when the user asks how to get heatmaps, click tracking, or path validation working for a website test, or asks for "the snippet," "the tracking code," or "how do I install Maze on my site." A website_test whose snippetState is NON_CONNECTED runs recording-only — participants' screens are recorded, nothing is tracked, and a PATH_BASED task can't be verified — until this snippet is installed and the domain is verified in the builder. It still runs and publishes that way, so tracking is an upgrade: call this tool once the user wants it. Don't use for a Figma prototype or a mobile app under test — those are prototype_test/app_test blocks with no snippet of their own. Inputs: teamId, as returned by get_user_details. Returns snippetCode (the ready-to-paste tag), installUrl (the builder tab where the domain is verified — the step that actually turns tracking on), helpUrl for GTM / ad-blocker install caveats, and a nextStepHint. Notes: - Installing the snippet alone does not turn on tracking — the domain must also be verified in the builder at installUrl; this tool cannot do that step. - The key is minted the first time a team without one asks; calling this again for the same team returns the same key, so it's safe to call more than once. See also: get_user_details resolves teamId.
plan_study
ChatGPTWork out which kind of Maze study — unmoderated, moderated, or AI-moderated — fits what the user wants to learn, and return a recommended type with the reasoning. Use when the user wants research done but has not settled on how to run it: "why are people churning", "help me set up a study", "what is the best way to test this". Also use when they have not yet said what they want to learn, however plainly they ask for a study — the goal is what a recommendation is made from. Use here too, even when a method is already named, whenever their goals are vague, span more than one study direction, or are your own inference or paraphrase of what they said — drafting straight away would settle a direction they have not actually confirmed. Don't use once the user has stated their own goals, in their own words, pointing at one study direction: that goes straight to draft_unmoderated_study. Don't use to read, find, or change a study that already exists — that is search and the get_* tools. Inputs: teamId and message, plus any brief fields already known — goals, audience, artifact, participantCount, timeline, screener — so the assistant confirms the goal, then asks only for what is missing. sessionId continues the conversation. Returns status — complete or running — and a nextStepHint naming the next action. A complete turn carries reply, with needs when it offered options to click; once a type is settled, recommended, alternatives, why and readyToBuild; and once the user has confirmed it, brief — a summary of what was gathered, which nextStepHint says how to hand on. Notes: - A moderated recommendation is a real answer: readyToBuild is false and nextStepHint says where the user creates one in Maze. Never draft an unmoderated or AI-moderated study instead. - An AI-moderated recommendation is buildable here, with readyToBuild true, when the team's plan includes the AI-moderated add-on. When it does not, recommended still names AI-moderated, but readyToBuild is false and nextStepHint says the team needs a plan upgrade. Never switch to an unmoderated study to work around the plan. - Planning creates nothing in Maze. See also: draft_unmoderated_study builds the study once the user agrees to an unmoderated recommendation, draft_ai_moderated_study once they agree to an AI-moderated one; get_user_details lists teams.
publish_unmoderated_study
ChatGPTPublish an unmoderated study in the user's Maze workspace — makes it live and its share link reachable, running the same validation the app's own Publish study button runs. Publishing does not recruit anyone, so no responses arrive until participants take the study. Use when the user has reviewed a study and explicitly says to publish it or send it live. Don't use for a study that still needs edits — use edit_unmoderated_study to save it first. Don't use to get a link for a study that's already live — use get_unmoderated_study, which returns its shareLink. Don't use for moderated or AI-moderated studies, which publish through different mechanisms entirely. Get the user's explicit approval to go live before calling — that approval is what userConfirmedPublish records. Inputs: studyId and userConfirmedPublish. Returns the published study's mazeId, shareLink (response tracking and one-response-per-device both on) to send participants, and — when the study has a resolvable project — resultsUrl, the study's results page, and recruitUrl, its recruitment page. A nextStepHint says what to tell the user next. Notes: - This is one-way: nothing in this milestone can pause, unpublish, or reverse a publish. Say so before the user confirms. - Only sets a draft study live; calling it on a study that's already live is refused. - Refuses without publishing when the study has blocks that still need setup (an unattached prototype, URL, image, or document), naming which ones so the user can finish them first. - Refuses without publishing when the study fails the same checks the app's Publish study button runs (e.g. a broken prototype path) — the error names what to fix and, when one block is at fault, where to fix it. - For a preview link that records no responses append ?notrack=true to shareLink, and for repeat responses from one device guerilla=true. Read maze://catalog/share-links before building any share link. See also: edit_unmoderated_study to change a study before publishing; get_unmoderated_study for a live study's shareLink later.
search
ChatGPTFind 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.
submit_mcp_feedback
ChatGPTLog 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.
create_ai_moderated_study
Claudecreate_study_attachment_upload
Claudecreate_unmoderated_study
Claudedraft_ai_moderated_study
Claudedraft_unmoderated_study
Claudeedit_unmoderated_study
Claudeget_ai_moderated_session
Claudeget_ai_moderated_study
Claudeget_moderated_session
Claudeget_moderated_study
Claudeget_resource
Claudeget_study_draft
Claudeget_unmoderated_study
Claudeget_user_details
Claudeget_website_test_snippet
Claudeplan_study
Claudepublish_unmoderated_study
Claudesearch
Claudesubmit_mcp_feedback
Claude