PlaybookUX

Delete 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_screener

Delete 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.

delete_survey_page

Get 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_analytics

List 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_audience_setup_options

List 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_consent_forms

List 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_demographics

Retrieve 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_draft_project

Get 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_highlights

Get 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_notes_and_clips

Get detailed information about a specific project. Only available for unmoderated and survey projects.

get_project

Get 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_questions

Get 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_responses

List 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_segments

List 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_sessions

Get 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_survey_analytics

Get 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_tags

List 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_testers

Get 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_transcripts

Find 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.

get_video_link

List 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_audience_templates

List 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_projects

List 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_question_types

List 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_study_templates

Workspaces: list_workspaces - get your workspace ID (required for all other calls)

list_workspaces

Rename 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.

rename_survey_page

Reorder 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_questions

Reorder 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_screeners

Reorder 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.

reorder_survey_pages

Search 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_projects

Search transcripts across the workspace by text. Uses full-text search powered by PostgreSQL. Optionally filter by project IDs.

search_transcripts

Configure 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_audience

Set 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_demographics

Enable 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_face_recording

Set 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_instructions

Enable 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.

set_survey_randomization

Update 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_question

Update 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.

update_screener

Validate 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.

validate_draft

Attach 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.