add_question
ChatGPTAdd a question to a draft unmoderated project. Supported types: url, task, written, range, single_select, multiple_select, image_select, audio_video. For url: label must be a valid http/https URL. For range: label, left_label, and right_label are required; scale (5-10, default 5) controls point count. For single_select/multiple_select: label and options (≥2 strings) are required; randomize shuffles options for testers; allow_other appends a free-text "Other" choice. For task: blur_video blurs tester webcam (default false). For image_select (the "Image" question) and audio_video (the "Audio/Video" question): the question is created with no media — attach the asset afterward with set_question_media (an image for image_select, a video for audio_video). For these two types the response also includes a manual_upload_url pointing to the build-study page; if the user has no public URL for their asset (e.g. they pasted an image into the chat), give them THIS manual_upload_url to upload it themselves, and do not point them anywhere else. position is 0-based; omit to append at end. If the position is occupied, existing questions shift down. Returns the created question with id, type, position, label, and type-specific fields. Only works on unmoderated projects in draft status — use list_question_types to discover field schemas.
add_screener_question
ChatGPTAdd a screener (qualifying) question to a draft project (unmoderated or survey). Screener questions are a pre-qualification gate, separate from the study questions — participants who pick a "disqualify" option are excluded. Only works on unmoderated or survey projects in draft status. Provide at least 2 answer options (the optional "Other" choice is separate). Each option has a disposition: "qualify", "disqualify", or "may_select" (neither). When disposition is omitted it defaults to the same value the UI uses: "qualify" for single_select, "may_select" for multiple_select. At least one option (including the "Other" choice if present) must not be "disqualify". To add a free-text "Other" choice, set other_option_disposition to its disposition (use "qualify" to match the UI default on single_select). That single choice is always labelled "Other" and shown last — it is NOT one of the entries in options. Omit it if the question has no "Other" choice. position is 0-based (0 = first) and matches the position returned by get_project; omit it to append the question to the end of the screener. Returns the created screener question with its options and stored positions.
add_survey_page
ChatGPTAdd a page to a draft survey project to last position. Survey questions live on pages, so create the pages that structure the survey flow, then add questions to each page. Only works on draft projects whose type is survey (returns 400 for any other project type). Provide an optional name; when omitted the page defaults to "Page N" (its 1-based position). A survey can have at most 75 pages (returns 422 when exceeded). Returns the created page as { id, name, position } (position is 0-based).
add_survey_question
ChatGPTAdd a question to a specific page of a draft survey project. Survey projects have a page hierarchy — questions must be placed under a specific page_id (from get_draft_project → pages[].id). Supported types: written, rating, single_select, multiple_select, instructions, ranking, matrix, first_click_test, five_second, preference, image_select. For rating: label, left_label, and right_label are required; scale (5-10, default 5) controls point count. The response type is "rating" (not the internal "range" stored in the DB). For single_select/multiple_select: label and options (≥2 strings) are required; randomize shuffles options for testers; allow_other appends a free-text "Other" choice. For instructions: only label is required (displays as a text slide). For ranking: label and items (≥2 strings) are required. For matrix: label, rows (≥2 strings) and columns (≥2 strings) are required; multiple_selection (default false) lets testers pick multiple columns per row. For first_click_test, five_second and image_select (the "Image" question): only label is required — the question is created with NO image; attach it afterward with set_question_media, or use the manual_upload_url in the response to have the user upload it on the build-study page. For five_second, display_time (1-30 seconds, default 5) sets how long the image is shown. For preference: label and images (an array of 2-8 caption strings) are required; one empty image slot is created per caption and the images are uploaded on the build-study page (use the manual_upload_url in the response). position is 0-based within the page; omit to append at the end of the page. Returns the created question with id, type, position, page_id, label, and type-specific fields. Only works on survey projects in draft status.
apply_saved_audience
ChatGPTApply a saved audience template to a draft project, pre-filling its device, demographics, language, and screener questions. Only available for unmoderated and survey projects in draft status. For survey projects the template's full device set is applied; for unmoderated projects it is reduced to a single device (computer first by priority). The audience_id must come from list_audience_templates — do NOT pass an ID from list_study_templates (those are study/question templates, not audience templates). Identify the audience by audience_id, or by audience_name (case-insensitive). When a name matches multiple audiences, the response has meta.ambiguous = true and data.matches lists each candidate with its id, name, and created_at (UTC ISO-8601); no audience is applied — re-call with the chosen audience_id.
configure_blocks
ChatGPTConfigure block randomization for a draft UNMODERATED project. Defines which questions are grouped into each block and whether each block is shown in randomized or fixed order to testers. This is the UNMODERATED-only randomization (question grouping into blocks). It is NOT the survey randomization: for survey projects, use set_survey_randomization (a single project-level on/off toggle, no blocks). Do not use this tool for survey projects. This is a full replacement — all existing blocks are overwritten in a single atomic write. At least 2 blocks must have randomize: true (UI requirement). Questions not assigned to any block are automatically placed in the first block. Default pattern mirrors the UI activation: [{ randomize: false }, { randomize: true }, { randomize: true }]. Use get_draft_project to get question IDs before calling this tool. Only works on unmoderated projects in draft status.
configure_project_details
ChatGPTConfigure the details step of a draft project: participant method, consent form, compensation, and study context. Works for both unmoderated and survey projects in draft status. Must be called before the project can be published. The project must be in draft status.
create_project
ChatGPTCreate a new unmoderated or survey research project in draft status. Returns the project ID, name, status, creation timestamp, and a direct URL to open the project in the PlaybookUX UI for manual review. The project is created in draft — it cannot be launched from MCP; use the PlaybookUX UI to publish it.
delete_draft
ChatGPTDelete a draft research project. Only unmoderated and survey projects in draft status can be deleted, and only by the project creator or a workspace admin. Once deleted, the project no longer appears in list_projects and cannot be restored through MCP. Returns the deleted project ID. Fails with a 403 for non-draft projects or insufficient permissions, a 422 for unsupported project types (e.g. card_sort), and a 404 when the project does not exist in the workspace.
delete_question
ChatGPTDelete a question from a draft unmoderated or survey project. question_id comes from get_draft_project or add_question. The remaining questions are re-indexed to stay contiguous; a question inside a randomization block (unmoderated) or a survey page is removed from that container too. Returns the remaining questions. Returns 404 if the question is not on the project.
delete_screener
ChatGPTDelete a screener (qualifying) question from a draft project (unmoderated or survey). Only works on unmoderated or survey draft projects. screener_id comes from get_project (ids change after each edit). Returns the remaining screener questions. Deleting the last question leaves the segment with no screener.
delete_survey_page
ChatGPTDelete a page from a draft survey project. page_id comes from get_draft_project or add_survey_page. All questions on the page are removed with it, and the remaining pages are re-indexed to stay contiguous. Only works on draft survey projects (returns 400 for any other project type). A survey must keep at least one page — deleting the last page returns 422. Returns the remaining pages. Returns 404 if the page is not on the project.
get_analytics
ChatGPTGet aggregated analytics for a project. Only returns meaningful data for card_sort projects: total_participants, similarity_matrix (pre-computed integer percentages 0–100; use as-is for dendrograms — do not derive from category_frequencies), similarity_matrix_labels (objects with id and name), and category_frequencies. All other project types return an empty data object — callers should skip analytics rendering when the response is empty.
get_audience_setup_options
ChatGPTList the audience options supported when configuring a study, for discovery before calling set_audience. Returns the available devices, the operating systems available per device class (computer vs mobile), and the supported participant languages as label/value pairs (the value is the code set_audience expects).
get_consent_forms
ChatGPTList consent forms available in the workspace. Use this to find valid consent form names before calling configure_project_details. Returns meta.returned_count (items in this response) and meta.matching_count (total matching across all pages).
get_demographics
ChatGPTList every demographic and employment targeting category with its valid option identifiers. Call this before set_demographics to discover valid ids. Returns categories: age (a free-form range, not a fixed list), gender, ethnicity, household_income, location_country, location_state, job_role ({id,name} from the panel database), work_status, company_size, industry, and seniority.
get_draft_project
ChatGPTRetrieve the complete configuration of a draft project, including metadata, details (face recording, compensation, consent form), audience attributes, and screener questions per segment. For unmoderated projects the response lists all questions with their block assignments; for survey projects it is organized by page (each page with its questions, type-specific fields inline, and per-page randomization) plus welcome and thank-you content. Supports unmoderated and survey projects.
get_highlights
ChatGPTGet highlight reels from a company. Optionally filter by project. Returns meta.returned_count (items in this response) and meta.matching_count (total items matching the filters across all paginated results).
get_notes_and_clips
ChatGPTGet notes and clips from test sessions in a project, differentiated by note type. Returns meta.returned_count (items in this response) and meta.matching_count (total items matching the filters across all paginated results).
get_project
ChatGPTGet detailed information about a specific project. Only available for unmoderated and survey projects.
get_questions
ChatGPTGet the questions defined in a project study. Only available for survey projects (not unmoderated or other types). Each question includes page_name (the survey page title, e.g. "Page 2: Five second test follow up questions") and page_order (1-based integer matching the page number shown in the UI, e.g. 2 for "Page 2") — use these fields to identify which survey page a question belongs to. Filter with page_order to narrow to a specific survey page. Returns meta.returned_count (questions in this response) and meta.matching_count (total questions matching the filters across all paginated results).
get_responses
ChatGPTGet participant survey and test responses for a project. Available for unmoderated, survey, tree test, and card sort projects. Every answer also includes a top-level image_url (the question's attached image, if any — present for first_click_test, five_second, and image_select questions; null otherwise). For non-card-sort projects, each answer includes page_name (the survey page title, e.g. "Page 2: Five second test follow up questions") and page_order (1-based integer matching the page number shown in the UI, e.g. 2 for "Page 2") — use these fields to filter or group answers by survey page. For tree test projects, each answer with question_type: "tree_test" contains a value object with path (breadcrumb string, e.g. "Home > Women > Shoes"), result (e.g. "Direct Success", "Indirect Success", "Direct Fail", "Indirect Fail"), duration_seconds, and duration_mm_ss. For ranking questions, value is an array of option labels ordered by the respondent's chosen rank (first = highest rank). For five_second questions, value is { duration_seconds } (or null if the timer never completed) — recall/memory-check questions are typically authored as independent questions on a subsequent survey page (grouped only by page_name/page_order), not nested under follow_up_answers. For card sort projects the response contains a categories array (with nested items) instead of an answers array, and a card_sort_type field ("open", "closed", or "hybrid"). Filter with question_id (not applicable for card sort), tester_id, or page_order (survey projects only — 422 on other types). Returns meta.returned_count (testers in this response) and meta.matching_count (total testers matching the filters across all paginated results).
get_segments
ChatGPTList audience segments for a company. Each segment belongs to a project and groups participants by criteria. Returns meta.returned_count (items in this response) and meta.matching_count (total items matching the filters across all paginated results).
get_sessions
ChatGPTList test sessions (participant recordings) for a project. Only available for unmoderated and moderated projects. Returns meta.returned_count (items in this response) and meta.matching_count (total items matching the filters across all paginated results).
get_survey_analytics
ChatGPTGet aggregated survey analytics for a project, grouped by page and question. Survey projects only — 422 on other project types. Returns data.pages, an array of { id, page (1-based order), questions }. Each question includes total (testers who submitted an answer to that specific question — testers who never reached or skipped the question are not counted in this denominator) plus type-specific fields: for single_select/multiple_select/range/preference, options each have count and percentage (of total); for matrix, a matrix object keyed by row/column option label with pre-computed {count, percentage} per cell; for ranking, options each have count (total times that option was ranked), a ranking array (count of respondents who placed that option at each rank position), and a derived average_rank; for first_click_test, the question's attached image is under image_url (consistent with other types), plus raw per-respondent first_click_coordinates ({x, y} pairs — bucket these yourself for a heatmap) and time_on_question ({time_per_tester, average_time_on_question}); for five_second, bare question metadata with image_url (no numeric aggregation exists for this type yet). Removed, unapproved, or manually-excluded (include_in_analytics: false) testers are always excluded from every aggregate. Filter with page_order or question_id to narrow the result to a specific page or question.
get_tags
ChatGPTGet tags applied to highlights and notes in a company workspace. Filter by project_id to return only tags actively used in a specific project. Returns meta.returned_count (items in this response) and meta.matching_count (total items matching the filters across all paginated results).
get_testers
ChatGPTList participants (testers) and their demographic data for a project. Available for unmoderated, moderated, survey, tree test, and card sort projects. Returns meta.returned_count (items in this response) and meta.matching_count (total items matching the filters across all paginated results).
get_transcripts
ChatGPTGet the speaker-attributed transcript for a single moderated session. Returns the tester name, a platform video URL, and an array of utterances with speaker label, start/end timestamps, and text. By default returns all utterances at once. Pass paginate=true to receive paginated results instead.
get_video_link
ChatGPTFind video watch links for a participant by first name, searching across all projects in the company. Returns one result per matching participant with their project context and a platform URL to watch the recording. When multiple participants share the same name, all matches are returned so the caller can disambiguate.
list_audience_templates
ChatGPTList saved audience templates for a company. Audience templates define reusable participant criteria (demographics, screener questions, device settings) — these are NOT study or question templates. Use these IDs with apply_saved_audience to pre-fill a project's screener and demographics. To browse study/question templates instead, use list_study_templates. Returns meta.returned_count (items in this response) and meta.matching_count (total items matching the filters across all paginated results).
list_projects
ChatGPTList research projects in a company workspace. Returns meta.returned_count (items in this response) and meta.matching_count (total items matching the filters across all paginated results).
list_question_types
ChatGPTList the question types available when building an unmoderated study, for discovery. Only unmoderated projects are supported. Each entry returns the canonical type identifier (e.g. written, url, task, range, single_select, multiple_select), a human label, required_fields and optional_fields (name/type/description), creation_validation constraints applied when building the question, a supported flag indicating whether the type can be used through MCP today, and available_in (a version hint such as "MCP 3.0") for types not yet supported.
list_study_templates
ChatGPTList saved study templates (question templates) available to a workspace for building unmoderated studies. These templates contain pre-built question sets — they are NOT audience or screener templates. To browse audience/screener templates instead, use list_audience_templates. Only unmoderated projects are supported. Returns both workspace-owned templates and PlaybookUX-provided global templates. Each template includes id, name, description, question_count, the distinct question_types it contains, and owner (workspace or playbookux). Returns meta.returned_count (items in this response) and meta.matching_count (total items matching the filters across all paginated results).
list_workspaces
ChatGPTWorkspaces: list_workspaces - get your workspace ID (required for all other calls)
rename_survey_page
ChatGPTRename a page on a draft survey project. Get page_id from get_draft_project or add_survey_page. Only works on draft survey projects (returns 400 for any other project type). Returns the updated page as { id, name, position }. Returns 404 if the page is not on the project.
reorder_questions
ChatGPTReorder the questions on a draft unmoderated or survey project. For unmoderated projects: provide question_ids in the desired order — it must be the complete current set of question ids (from get_draft_project; ids come from add_question). Not supported for projects that use randomization blocks (returns 422). For survey projects: page_id is required (UUID of the target page from get_draft_project). Provide question_ids in the desired order for the target page. Cross-page moves are supported — a question from another page is moved to the target page and the source page is re-indexed. Returns the reordered questions for the target page.
reorder_screeners
ChatGPTReorder the screener (qualifying) questions on a draft project (unmoderated or survey). Provide screener_ids in the desired order — it must be the complete current set of screener question ids (from get_project; ids change after each edit). Only works on unmoderated or survey draft projects. Returns the reordered screener questions.
reorder_survey_pages
ChatGPTReorder the pages on a draft survey project. Provide page_ids in the desired order — it must be the complete current set of page ids (from get_draft_project; ids come from add_survey_page). Only works on draft survey projects (returns 400 for any other project type). A partial or duplicated list returns 422; a page id that is not on the project returns 404. Returns the reordered pages.
search_projects
ChatGPTSearch for projects by name (partial, case-insensitive). Use this to find a project UUID when you know the name but not the ID. Returns up to 100 results. meta.matching_count reports the true total — if it exceeds meta.returned_count, narrow the search.
search_transcripts
ChatGPTSearch transcripts across the workspace by text. Uses full-text search powered by PostgreSQL. Optionally filter by project IDs.
set_audience
ChatGPTConfigure the audience step of a draft project: number of testers, devices, operating system, and language. Supports unmoderated projects (exactly one device) and survey projects (one or more devices) in draft status.
set_demographics
ChatGPTSet demographic and employment targeting on a DRAFT unmoderated or survey project that uses the PlaybookUX tester panel. Each category is an array of valid option ids — use get_demographics to discover them. A category you provide REPLACES that category's previous selection; an empty array CLEARS it; categories you omit are left unchanged. Only works on draft unmoderated or survey projects with the PlaybookUX tester method (Recruit-Your-Own projects return an error).
set_face_recording
ChatGPTEnable or disable face recording for an unmoderated draft project. Update face recording status requires a Scale plan; The project must be in draft status.
set_question_media
ChatGPTAttach a single media asset to a draft media question, on an unmoderated OR a survey project. Unmoderated media types: image_select (the "Image" question, takes an image) and audio_video (the "Audio/Video" question, takes a video). Survey single-image types: image_select, first_click_test and five_second (all take an image). Create the question first (add_question for unmoderated, add_survey_question for survey), then call this with its question_id. Note: the survey "preference" question holds multiple images and is NOT supported here — upload its images on the build-study page. Provide a single media_url: a publicly fetchable http/https URL the server downloads. The question type decides how it is used — image types take an image (jpeg/png); audio_video takes a video (mp4/webm). This URL can be one the host gives you for a file the user uploaded (e.g. ChatGPT exposes uploaded files as a download URL — pass that URL here). An image or video pasted directly into the chat with no public URL cannot be attached this way; in that case do NOT call this tool. Instead give the user the manual_upload_url that add_question returned for this media question (it points to the build-study page) so they upload it themselves there. Do not point them at the project details page. The server fetches the media and stores it on the question, replacing any existing media. Video has a smaller size limit than the app. If the media is too large or cannot be fetched, finish the upload in the app using the manual_upload_url returned in the response (the build-study page). Returns the updated question and a manual_upload_url to the build-study page.
set_survey_instructions
ChatGPTSet the Welcome page and Thank You page content for a draft survey project. The Welcome page is shown to participants before the survey begins; the Thank You page is shown after they finish. All four fields are optional, but provide at least one to change; omit a field to leave it unchanged. These pages always have content — passing an empty/blank value or null resets that field to the survey default (it is never left empty), mirroring the UI. There are no character limits, and body fields are stored as plain text (any HTML is not rendered). Only works on survey projects in draft status (returns 422 for other project types, 400 for non-draft). Returns the updated project with the saved welcome/thank-you content.
set_survey_randomization
ChatGPTEnable or disable question-order randomization for a SURVEY draft project. When enabled, questions are shown to participants in a random order within each page. This is a single project-level on/off setting that applies to the whole survey (not per page, no grouping). This is SURVEY-only and is NOT the unmoderated block randomization: for unmoderated projects, question randomization is configured with configure_blocks (grouping questions into randomized/fixed blocks). Do not use this tool for unmoderated projects. Only works on survey projects in draft status.
update_question
ChatGPTUpdate a question on a draft unmoderated or survey project — partial update (PATCH): send only the fields you want to change. Get question_id from get_draft_project or add_question. The question type CANNOT be changed (the backend returns 400); position is not changed here — use reorder_questions. For range, scale (5-10) rebuilds the rating points. For single_select/multiple_select, sending options (≥2 strings) replaces the answer choices, allow_other adds/removes the free-text "Other" choice, and randomize toggles option shuffling. For task, blur_video toggles webcam blur. For ranking, items (≥2 strings) replaces the ranked items. For matrix, rows (≥2 strings) and columns (≥2 strings) replace the row/column labels; multiple_selection toggles multi-select mode. Returns the updated question. Returns 404 if the question is not on the project.
update_screener
ChatGPTUpdate a screener (qualifying) question on a draft project (unmoderated or survey) — full replace (PUT): send the complete new definition. Adding or removing options is done by sending the new options list. Only works on unmoderated or survey draft projects. Get screener_id from get_project (segments[].screener_questions[].id); ids change after each screener edit, so re-fetch before chaining edits. Same option rules as add_screener_question: at least 2 options, "may_select" only for multiple_select, and at least one option must not be "disqualify". Returns the updated screener question.
validate_draft
ChatGPTValidate whether a draft project has everything required for launch, mirroring the checks the PlaybookUX UI runs on its Summary step. The MCP cannot launch projects, so use this as a pre-flight check before handing the draft to a teammate to review and submit in the UI. Supports unmoderated and survey projects in draft status. The result is nested under a data envelope: data.valid (boolean), data.errors (array of { step, field, message }), and data.warnings (array, reserved for non-blocking issues). The step names the wizard step the issue belongs to and differs by project type: unmoderated uses "details", "audience", "build-study", or "summary"; survey uses "details", "audience", "pages", "questions", or "summary". For surveys, an empty page is a blocking error under the "pages" step ("Page N has no questions."). A "summary"/"payment" error means the project needs payment but no payment method is on file (or it could not be verified); resolve payment in the UI. When data.valid is true the draft is ready for hand-off.
