---
name: userstudies
description: Run complete synthetic persona interviews, desirability studies, and browser-task studies through User Studies. Use for exploring research hypotheses, comparing reactions to supplied designs, or observing simulated participants attempt a website task.
---

# User Studies

Use the connected User Studies MCP tools `start_study`, `get_study`, and `stop_study`. 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.

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

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

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.

## 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. Data is stored by the service; participant/context and supplied images are sent to its configured model provider via OpenRouter. 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.