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

> Canonical rules for creating and updating studies via the MCP server — read-before-write, screener types, mode flags, and soft deletes.

The MCP server's `instructions` field embeds this playbook so every client inherits
the same discipline the in-app chat experience enforces. Follow these rules whenever
you build or modify a study via the API.

## Read before write

Always call `get_study` before calling `update_study`. Do the same for
invites (`get_invite` before `update_invite`) and calls (`get_call` before
`update_call`).

The `screener_questions` field in `update_study` **replaces the full list** — it
is not a merge or append. If you skip the read step, you will silently drop any
screener questions that were already on the study.

## Panel vs custom screeners

Two kinds of screener question coexist on a study and must both be preserved
whenever you update `screener_questions`.

**Panel questions** target the panel. They require:

* `is_panel_question: true`
* A `qualification_id` sourced from `list_available_panel_questions`

Call `list_available_panel_questions` before composing a panel screener list to
confirm the `qualification_id` values that are available.

**Custom questions** are free-form text screeners you write yourself. They use:

* `is_panel_question: false`
* Your own question text — no `qualification_id` needed

When you read the existing `screener_questions` array and write it back, keep both
panel and custom rows intact. Dropping one type when updating the other is a
common mistake.

## No consent screeners

Never add questions like "Do you consent to being recorded?" or "Are you willing
to participate?" to the `screener_questions` list. Consent is collected outside the
screener flow and is handled by the platform.

## No auto-screeners on create

`create_study` should never automatically generate screener questions. Create
the study with an empty or null screener list and only add screeners when the user
explicitly asks for them, using a subsequent `update_study` call.

## Mode = flags, not a column

Study mode is controlled by two boolean flags on the study record:

| Flag                     | Default | Effect                               |
| ------------------------ | ------- | ------------------------------------ |
| `enable_chat`            | `false` | Text-chat interview instead of voice |
| `enable_video_recording` | `false` | Record video during the interview    |

Both flags default to `false`, which means voice-only. You can combine them — a
study with `enable_chat: true` and `enable_video_recording: true` runs a chat
interview that is video-recorded. There is no separate `mode` column.

## Language

Set `voice_config.language` to an ISO 639-1 language code. Call
`list_available_languages` to retrieve the list of codes the platform supports.
Do not hard-code language strings.

## Deletes are soft

`delete_study`, `delete_invite`, and `delete_call` do not permanently remove
records. They set a `deleted_at` timestamp. Deleted studies, participants, and
calls may be recoverable from the dashboard if you need to undo a deletion.