review_study presents that data as a read-only MCP App in supported clients.
Review study
review_study cannot approve a plan or start recruitment. Review the persisted study version and obtain explicit approval before any participant creation or paid launch.
Structured reports and search
generate_report returns a durable job. Poll get_report_job until it succeeds, then call get_study_report. get_fielding_progress reports current target-cycle completions and quality counts; expected finish is null until a rate estimate is supportable.
Reports use schema report-v2. The default view: "overview" returns report identity, freshness, counts, a short summary, and available_sections. Set view to study_findings, participant_profiles, participant_responses, evidence_coverage, recommended_next_steps, or references to fetch one section; use full only when all sections are needed. included_sections distinguishes omitted sections from sections that are present but empty. The complete saved interview-ID list is included only in full.
study_findings.learning_goals nests each finding under its Learning Goal and gives it a stable finding_id. Explicit frequency becomes prevalence: { n, of }, and resolvable source quotes become quotes[] with reference_id, interview_id, turn_id, and start_s when timing was stored. Missing evidence stays null or empty on older reports. participant_profiles is an array keyed by a stable question_id derived from the question heading; its content is an array of { answer, participants, percentage }. Use references and public interview_id to inspect source evidence.
search_research searches 1–20 study IDs and optionally filters by content type or research date. It can retrieve study_plan, study_finding, participant_profile, participant_response, and recommended_next_step objects. Search ranks candidates, but the tool discards generated prose and returns the exact canonical JSON stored by the Study/Report APIs. Results are grouped in studies[] under each requested study; check its index_status, latest_report_id, and indexed_report_id for freshness. Follow next_cursor with unchanged query, filters, and limit until null; an empty final page is possible. Participant-response matches include a public interview_id to use with get_interview.
answer_research takes a question and the same study/date/content filters. It returns generated prose with numbered citations whose content IDs were verified against accessible canonical search results. citations[] identifies each source’s study, content type, report, and interview when available; studies[] reports index freshness without repeating the full search payload. insufficient_evidence means the indexed sources did not support an answer. Use search_research, get_study_report, or get_interview to inspect source content and verify exact quotations.
When the primary ranking service is unavailable, search falls back to bounded keyword matching over current indexed research for the same authorized study IDs and filters. Keyword ranking can differ from the primary semantic ranking; results still come from the canonical stored records.
Finding studies
list_studies defaults to 20 rows per page and accepts at most 100. Filter by name, provisioning status (draft, ready, or provisioned), recruiting_method, ISO date-time created_after, or has_report. Filters apply before the count and page. Results are ordered by updated_at descending, then study ID descending, so pages have a stable order. Each row’s interview_count uses the same completed, visible, non-test, quality-filtered set as list_interviews(status=completed); get_study returns that count too. report_status is available or not_generated. study_link is the live participant interview link when the interviewer is provisioned and the study is not paused; it is not a researcher preview link.
Study detail also returns invitation_count (invitation records), interview_attempt_count (all attempts), and quality_interview_count (interviews that passed quality checks). A panel launch can have one invitation record and many interviews. The older count aliases are no longer returned.
study_plan.learning_goals_structured gives each enriched Learning Goal a stable id, question, and evidence_needed. Report learning_goal_id values use those IDs. The markdown learning_goals field remains for existing clients. Historical study labels appear in use_case; study_type is always one of the current creation types.
Study decisions and defaults
Before creating a study, ask for the required recruiting decision:recruiting_method:panel,byop, orsynthetic_respondents
interview_format: "voice", language: "en", and voice: "male". Synthetic respondents use chat. Use explicit alternatives only when the user requests them. Voice configuration remains required for chat studies and accepts only male or female. create_study requires a nonblank name and an explicit recruiting method; it does not accept byop_config or designed content. Prototype tests cannot use chat.
The study name has a maximum length of 40 characters.
study_type accepts in-depth-interview, concept-test, and prototype-test; the default is in-depth-interview. Prototype tests cannot use chat. Catalog tools may help explain the available template, but the MCP host must not turn catalog prompts into a plan. customize_study loads and applies the selected study type’s instructions on the backend.
Customize Plan conversation
create_study, customize_study, queue_customize_study, create_participants, generate_report, and launch_panel accept an optional idempotency_key. Use a new key for each approved paid launch. Reuse it with identical inputs when retrying a timed-out call; a completed launch replays its original response without another panel launch. The planning conversation is stored on the study; continue it with study_id, without passing a separate conversation identifier.
For a text planning turn, call queue_customize_study. It returns a job ID promptly. Poll get_customize_study_job until status is succeeded or failed; a successful job includes the next planning response in result. Call get_study after success to inspect the persisted plan. The synchronous customize_study remains available for native concept images, which the queue does not accept. A public image URL may be included in the queued message.
After creating the metadata draft, call customize_study with the user’s ordinary-language brief. Use the same tool for all later changes to:
- the study plan and expected duration
- canonical audience targeting and custom screeners
- concept links and concept images
study_plan, targeting_attributes, screener_questions, or concept schemas. The backend owns those fields and performs the same checks and reconciliation as Customize Plan in the dashboard.
Use decisions: "human" by default: relay questions[] to the researcher and call customize_study again with their answer. When the researcher delegates ordinary research-design choices, use decisions: "agent"; report assumptions[], and relay only questions still returned as required. This never authorizes the agent to choose an unspecified recruiting method, send invitations, or approve a paid launch. Put a draft-only workflow instruction in execution_policy: "draft_only", not in the research message; direct launch or invitation commands in message return 422. The policy is returned with this turn, and this endpoint never starts recruitment. It does not replace approval checks on later fieldwork calls. When the response contains a plan or completion message, call get_study to verify what was persisted.
Return the complete persisted plan in a readable form and ask the user to approve that exact version or request revisions. Do not substitute a summary or dashboard link. Route revisions through customize_study, fetch the result again, and repeat review. Approval to create a draft, client tool permissions, and approval of a Panel estimate do not count as approval of the current study plan.
For an attached concept image, include concept_image with the raw bytes encoded as base64, filename, MIME type, and the user’s participant-facing label. This works when the client exposes attachment bytes or a readable local path and does not require public hosting. Public downloadable image URLs remain supported in the message. Never ask for login credentials.
Drafts and provisioning
create_study supports incremental setup and may return a draft. Every study response includes:
When the Customize Plan conversation completes the last missing requirement, provisioning happens automatically. Only create BYOP participants or launch a paid Panel study after
get_study says provisioning_status: "provisioned" and the user has approved the current returned plan.
Treat fielding_status as distinct from provisioning. Panel studies expose their persisted recruitment state. BYOP returns unavailable because progress is tracked on invitations and interviews, while synthetic respondents return not_applicable.
Read before write
Callget_study before update_study.
update_studychanges ordinary metadata such as name, recruiting method, interview format, language, voice, and BYOP incentives.customize_studychanges the plan, expected duration, targeting, screeners, and concept material.