--- name: userstudies description: Chat with synthetic personas, suggest Persona/Problem/Promise/Product brief ideas, and run interview, browser-task, desirability, and storyboard studies through User Studies. Use to explore research hypotheses, compare designs, observe simulated website tasks, or illustrate a product journey. --- # User Studies Use the connected User Studies MCP tools `chat_with_persona`, `generate_brief_idea`, `start_study`, `get_study`, `stop_study`, and `list_storyboards`. Connection instructions: https://userstudies.ai/mcp.md. Downloading this file does not register an MCP server. Never invent results if the connection is unavailable. ## Choose the study Reuse the user's audience, decision, and context. Ask only for missing inputs needed to run the requested study. All generated participants, quotes, and reactions are **SYNTHETIC**: hypotheses, not customer evidence, prevalence, demand, or actual adoption. - `chat_with_persona` (Chat tab): send one message to a synthetic persona. Required `persona` (up to 4,000 characters) and either `message` (up to 4,000 characters) or `image` (inline PNG/JPEG/WebP data URL, at most 1 MB decoded). Optional `problem`, `promise`, `product`, `model`, `history` (up to 50 `{role,content}` user/assistant turns), and `completePersona` (the string returned by the prior call). The first call may create a character; send both returned `completePersona` and prior turns on later calls for continuity. The response has `text`, `completePersona`, and `suggestedQuestions`. Chat is turn by turn and does not create a study ID. Selectable models: `openai/gpt-oss-120b` (default), `openai/gpt-6-luna`, and `meta/muse-spark-1.3-contributor`. Image input follows the Chat UI's vision-model path. - `generate_brief_idea` (left sidebar Autofill): choose `fieldToAutofill` from `persona`, `problem`, `promise`, or `product`. Pass `currentInputs` as an object containing any existing brief fields and optionally `conversation` as up to 50 prior `{role,content}` user/assistant turns. The tool uses the same backend as one sidebar Autofill click, returning `{suggestedInput}`. It does not edit the brief or start a study. Treat the result as a draft idea to review, especially if the conversation or brief is thin; do not present it as observed customer evidence. There is no model selector for this backend action. - `interview`: a complete moderated interview, including adaptive questions, participant replies, and synthesis. Supply `persona` and `question` or `problem`. Default is one participant and six turns each. For discovery, omit `promise` and `product`; supplying either introduces a hypothetical concept late in the interview. - `desirability`: supply `persona` and `stimuli`. Each item has unique `id`, neutral `label`, and `text`, `image`, or both. Images are inline PNG/JPEG/WebP base64 data URLs, at most 1,000,000 decoded bytes each; remote image URLs are not accepted. Participants inspect the exact supplied stimulus and select up to five words from a shared balanced set, then explain their choices. Optional `proposition` introduces benefits, setup, recurring effort, dependencies, price and alternatives after initial selections. `intendedAttributes` are analyst-only. Without a proposition, leave adoption unresolved. - `browser_task`: supply `persona`, public HTTPS `url`, and a concrete `task`. Runs reuse the product's browser execution. Respect the user's existing authorization for interactions with the target website. - `storyboard`: supply `persona`, `problem`, `promise`, and `product` to generate six illustrated beats (setting, trigger, old way, encounter, action, changed situation). Do not pass `participantCount`, `turns`, `stimuli`, or `proposition`. The result is **ILLUSTRATIVE**, an imagined journey rather than observed participant evidence. ## Start and retrieve Call `start_study` with `mode`, `persona`, and a unique `idempotencyKey`, plus the mode-specific inputs. Optional `participantCount` is 1–5 (default 1); `turns` is 1–12 (default 6, interviews only). Optional contextual fields: `problem`, `promise`, `product`, `question`, `proposition`; each at most 4,000 characters. At most 8 stimuli and 20 intended attributes. Keep the whole request below 8 MiB. An idea suggestion is not a user-approved brief; do not autofill an unknown problem, promise or product simply to launch. Example: ```json {"mode":"interview","persona":"Freelance designers who collect client feedback in email","question":"How do they collect and act on client feedback?","participantCount":1,"turns":6,"idempotencyKey":"client-feedback-001"} ``` Starting returns `studyId` and status immediately; the server conducts the whole study. Reuse the same key and identical input when retrying an uncertain launch. A changed brief needs a new key; key conflicts must not silently launch duplicates. For Storyboard history, call `list_storyboards` with optional `cursor` (0–10000, default 0) and `limit` (1–20, default 20). Follow `nextCursor` until null. Each owner-scoped item includes its saved brief, status, parent ID, feedback, and a preview image reference. Open a generation with `get_study`. To regenerate with feedback, call `start_study` with `mode:"storyboard"`, the prior generation's saved four brief fields, `feedback`, `parentStudyId`, and a new idempotency key; the parent must be complete. To draw a fresh variation, omit both feedback and parent ID. Image references such as `/api/studies//assets/0` require an authenticated GET to `https://userstudies.ai` with the same Bearer token; indices are 0–5. Images are private. Call `get_study` with `studyId`. Poll at a reasonable interval (for example 5 seconds), not a tight loop. `detail` defaults to `summary`; use `transcript` for interview turns/browser events and `evidence` for desirability records, word visuals, or browser evidence. Optional `participantId` narrows records. `cursor` defaults to 0; `limit` defaults to 20 and accepts 1–100. Follow `nextCursor` until null, even if a participant-filtered page is empty. Browser transcript/evidence cursors are event sequence IDs; research cursors are offsets. The first browser evidence page adds latest frames and outcomes to the bounded historical frame-event page. Browser detail records are under `browser.items`; research records are under `items`. Preserve partial-result warnings and report failed, stopped, or interrupted studies as incomplete. Missing replies are not agreement. Do not relaunch failed runs repeatedly to obtain a preferred finding. Use `stop_study` with `studyId` when the user cancels or the work is no longer wanted; it preserves completed work. Ordinary MCP request disconnection does not cancel a durable background study. ## Interpret and present Lead interviews with decision implications, hypothesized patterns, counterexamples, attributed synthetic quotes, and next real-user checks. Keep full transcripts secondary. Preserve participant identifiers and distinguish analyst inference from generated testimony. Lead desirability with the returned word-association SVG beside the specific stimulus. Show Appearance / Personal relevance / Conditional adoption separately. Counts and denominators describe only these simulations. Positive appearance does not establish desire to use, usability, or demand. If no visual rendering capability exists, disclose that and provide the recorded selections. For browser tasks, separate observed interface actions and screenshots from simulated reactions. An executor/provider error is not proof the target product failed. Never describe synthetic participants as recruited customers. For storyboards, show the six captions with their corresponding images when the client can fetch/render them. Keep missing images and partial or failed generations visible; do not imply the changed outcome happened to a real person. Feedback revises a completed prior generation; a fresh variation has no parent link. ## Errors and access 401: reconnect with a valid agent token; never ask the user to paste secrets into public documents. 403/421: check the approved origin/host. 400: correct bounded inputs. 404: check the study ID and owner. 409: reuse the original request or choose a new key for an intentionally new study. 429: wait for capacity; do not bypass budgets. If a study fails, retrieve its partial records and explain the missing evidence. Tokens represent the originating browser session, expire after 30 days, and can be revoked at https://userstudies.ai/agents.html. Replacing a token invalidates the previous token. Study data is stored by the service; participant/context and supplied images are sent to its configured model provider via OpenRouter. Chat and brief ideas use the site's existing backend and configured OpenRouter model; neither creates a study record, and existing backend tracing may apply. Do not submit information outside the user's authorized scope. Research requests are capped at 150 moderator/participant/analysis calls per study, in addition to the existing profile-generation request. Oversized designs/turn combinations are rejected before execution. Aggregate inline image data URLs must fit within 6,000,000 characters; each image also retains its 1,000,000-byte decoded limit.