Study-creation playbook

The MCP server keeps a short set of critical rules in its instructions field so clients with small instruction limits still receive them. Step-specific rules appear in the relevant tool descriptions. This page provides the full workflow. A User Intuition Skill adds a reusable workflow on top of it.

​

1. Collect the required setup decision

Before creation, understand the research goal and ask for the missing recruiting choice:

• recruiting_method: panel, byop, or synthetic_respondents; never guess

For Panel and BYOP, create_study defaults to a voice interview in English with male voice configuration. Synthetic respondents use chat. An explicit user choice may instead set interview_format to chat or video where supported, choose another supported language, or choose female voice configuration. Chat studies also retain voice configuration; the public choice remains male or female. Keep the study name to 40 characters or fewer. Read userintuition://catalog/study-types when the user needs help choosing a study type, but do not draft a plan from its internal prompts.

​

2. Create only the metadata draft

Call create_study with a nonblank name, the user’s recruiting choice, and ordinary metadata. The MCP schema intentionally does not accept BYOP incentive settings, a study plan, expected duration, audience targeting, screener questions, concept links, or concept images.

​

3. Start the Customize Plan conversation

Call customize_study with the user’s natural-language research brief. Include what they want to learn, who they want to interview, requested screening, and any concept link or image they want participants to see. When the client exposes an attached image as bytes or a readable local path, base64-encode the raw bytes and pass them through concept_image on the same call. Pass the user’s meaning through in ordinary language. Do not construct or patch study_plan, targeting_attributes, screener_questions, or concept objects yourself. The backend runs the same stateful Customize Plan workflow used by the dashboard, including the study type’s chat_prompt instructions, canonical targeting selection, validation, duration calculation, conversation-flow formatting, concept checks, and plan reconciliation.

​

4. Keep the human in the loop

One customize_study call represents one conversation turn. Use decisions: "human" unless the researcher delegates ordinary research-design choices; then set decisions: "agent", report assumptions[], and still relay any required questions[]. Keep workflow constraints such as draft-only in execution_policy, outside the research message. Inspect response_type:

• question: show questions[] to the user, wait for their answer, then call customize_study again with that answer
• study_plan or a completion message: continue to verification

In human mode, never answer a Customize Plan confirmation yourself. Agent mode covers research-design assumptions only. Client permission settings do not replace a required recruiting choice, plan approval, or paid-launch approval.

​

5. Handle audience and screening through chat

Describe audience requirements naturally. Customize Plan should use existing targeting attributes when they fit criteria such as age or household income, and create custom screener questions only when canonical targeting cannot express the requirement or the user explicitly needs one. Never add recording-consent or willingness-to-participate screeners. The platform handles consent separately.

​

6. Handle concepts through chat

Send concept-link and concept-image requests through customize_study. When the client exposes an attachment’s bytes or a readable local path, base64-encode the raw image and pass it through the optional concept_image input with its filename, MIME type, and the user’s participant-facing label. Public image URLs remain supported in the conversation message. If the client exposes only an opaque attachment reference with no readable bytes, path, or public URL, explain that client limitation and offer the available upload routes. Never request login credentials. The backend owns URL safety, embeddability, login detection, recorder compatibility, file validation, storage, deduplication, IDs, mode compatibility, and plan reconciliation. Studies with concept links cannot use chat interviews. Relay the backend’s question or validation result and let the user choose voice or video.

​

7. Verify the persisted study

Call get_study after customization. Return the complete persisted study plan in a readable form, together with the audience, screeners, concepts, interview settings, and provisioning_status. Ask the user to approve that exact plan or request revisions. Do not replace the plan with a short summary or only a dashboard link. Send requested revisions back through customize_study, fetch the study again, and return the complete revised plan. Approval of an earlier version does not cover a revised plan. Client permission settings, approval to create a draft, answers to Customize Plan questions, and approval of a cost estimate do not count as study-plan approval. Only create BYOP participants or launch a paid Panel study when provisioning_status is provisioned and the user has explicitly approved the current returned plan. If the result is incomplete, continue through customize_study rather than filling designed fields through another tool.

​

8. Field safely

For BYOP, call create_participants only after provisioning and plan approval. Poll get_participant_job to completion, then list the invitations. For Panel recruitment:

1. Ask the user to choose the launch country explicitly. Each launch_panel call fields exactly one country; never infer a country from a broad region such as Europe or Asia.
2. Verify that country/language combination with userintuition://catalog/panel-countries.
3. Use submit_feasibility_request when incidence is below 10% or the audience requires specialist review.
4. Call the read-only estimate_panel with the explicit country_code.
5. Show the resolved country, language, cost, and heuristic timeline; retain estimate_id.
6. Confirm the user has approved the current returned plan.
7. Wait for explicit approval of that complete estimate before calling launch_panel with its estimate_id and the same country. Obtain a new estimate if it expires or relevant inputs change.

For multi-country research, ask the user to select one launch country or create separately reviewed and approved country-specific studies or launches. A multi-country Learning Plan does not turn one Panel launch into multi-country recruitment.

​

9. Read before metadata updates

Call get_study before update_study, and get_participant before update_participant. update_study is for ordinary metadata only; route designed-content changes back through customize_study. A fielding Panel study must be paused or stopped before editing. Pause if recruitment should resume; stop when fieldwork is over.

​

10. Confirm external and destructive actions

Require explicit confirmation before a paid launch, reward, webhook registration, stop, study deletion, or interview deletion. Treat tool annotations as authoritative. create_webhook returns its signing secret once. Tell the user to store it securely without repeating the value.