> ## Documentation Index
> Fetch the complete documentation index at: https://docs.userintuition.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Study-creation playbook

> Create a metadata draft, conduct the Customize Plan conversation, verify the result, and field the study safely.

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](/skills/overview) 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.