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

# Studies

> 20 MCP tools for creating, customizing, reviewing, fielding, reporting on, and searching studies.

Studies are the central research object. The 20 tools below use the public API for study data; `review_study` presents that data as a read-only MCP App in supported clients.

| Tool | Description |
| - | - |
| `list_studies` | List study summaries with filters and report availability; use `get_study` before a write |
| `create_study` | Create a Panel, BYOP, or synthetic respondent metadata draft |
| `customize_study` | Send one natural-language turn to the dashboard's stateful Customize Plan conversation |
| `queue_customize_study` | Queue a planning turn and return a durable job ID; use this for text and public image URLs |
| `get_customize_study_job` | Poll the queued planning turn until it succeeds or fails |
| `get_study` | Fetch the complete study plan, screeners, and targeting |
| `review_study` | Open the saved plan and fielding progress in a read-only MCP App; other clients receive the study data as text |
| `update_study` | PATCH ordinary metadata only; use `customize_study` for designed content |
| `delete_study` | Soft-delete a study and linked records from normal reads; no public restore endpoint |
| `estimate_panel` | Get a read-only panel cost and timing estimate with an expiring estimate ID |
| `launch_panel` | Review a saved plan and current panel quote; approve through the App or explicit human chat confirmation in clients without Apps |
| `pause_study` | Pause recruitment while preserving progress and the reward hold |
| `resume_study` | Resume preserved panel recruitment |
| `stop_study` | End recruitment and settle or release its hold |
| `generate_report` | Queue analysis of completed interviews and return a job ID |
| `get_report_job` | Poll report generation status before fetching the result |
| `get_fielding_progress` | Compare qualifying completions with target, quality mix, and estimated finish |
| `get_study_report` | Fetch the latest report, canonical JSON sections, call-linked citations, interview count, and stale status |
| `search_research` | Search indexed study/report content and return only canonical API JSON |
| `answer_research` | Answer across selected studies with numbered citations to accessible canonical research records |

## 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`, or `synthetic_respondents`

For Panel and BYOP studies, omitted interview settings default to `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. For panel approval, check `get_study` after a timeout before taking any further action. The MCP review nonce is single-use; do not create a new approval merely to retry a launch. Backend idempotency protects the submitted paid request. 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

Do not translate the user's request into MCP-side `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:

| Field | Meaning |
| - | - |
| **provisioning\_status** | `draft`, `ready`, or `provisioned` |
| **fielding\_status** | Recruitment lifecycle: `not_started`, `starting`, `fielding`, `paused`, `complete`, `partial`, `failed`, `stopped`, `unavailable`, `not_applicable`, or `unknown` |
| **missing\_requirements** | The fields still needed before the interviewer can be provisioned |

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

Call `get_study` before `update_study`.

* `update_study` changes ordinary metadata such as name, recruiting method, interview format, language, voice, and BYOP incentives.
* `customize_study` changes the plan, expected duration, targeting, screeners, and concept material.

A fielding Panel study must be paused or stopped before it can be edited. Pause when recruitment should continue later; stop when recruitment is finished.

The raw REST API may expose additional structured study fields. The MCP intentionally routes designed content through Customize Plan so dashboard and agent-created studies follow the same planning behavior.


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