Assistants and MCP

Connect Claude, ChatGPT, Cursor or any MCP client to your workspace, with the full tool catalogue, generated from the server.

Read the manual without a connection

The manual is public and contains no private study data. An assistant can discover every page through llms.txt, fetch the full manual, or read one page as plain Markdown at /llms/{slug}.md. The rendered pages at /docs carry the same text.

GET /llms.txt
GET /llms-full.txt
GET /llms/recruitment.md

Connect

The server is at https://research.underheard.ai/api/research/mcp and speaks the Model Context Protocol over Streamable HTTP. It takes an API key as a bearer token; the key fixes the workspace and the scope, and a read key can only call read tools.

{
  "mcpServers": {
    "underheard-research": {
      "url": "https://research.underheard.ai/api/research/mcp",
      "headers": { "Authorization": "Bearer uh_research_YOUR_KEY" }
    }
  }
}

In Claude's web and desktop apps, add it as a custom connector with the same URL and the key as the bearer token. Settings, under API, shows the URL to copy.

The staging site has the same server at https://underheard-research-staging.vercel.app/api/research/mcp, behind Vercel's deployment protection: a client sends the key as the bearer and the protection bypass secret as the x-vercel-protection-bypass header. The Underheard team holds that secret.

Test a study end to end

The flow tools follow the screens, one tool per step, so an assistant or a script can set up and run a study the way a researcher does, without a browser. research_flow_help lists them in order.

research_setup_study: a brief (the decision, the audience, what to learn, markets, length, language) creates the study and writes its guide, as New study and Design do. It takes about a minute. Never write questions yourself.
research_get_study reads the guide with the open findings of Design's guide check; research_edit_guide changes it from a plain instruction; research_regenerate_guide writes it again from the brief.
research_publish_guide, then research_launch_study for a study whose participants are your own people. research_study_links returns the study link, the test link and the test link that starts past the screeners.
research_count_test_interview, research_pause_fieldwork and research_close_fieldwork run fieldwork; research_generate_report writes the report.
research_archive_tests archives every study whose name starts with your test prefix, so test studies never pile up.

The flow tools take no storage version and no idempotency key: each call runs once. A step the app holds for a Confirm (publishing, closing fieldwork, adding people) returns a preview until it is called with confirm: true.

How to work with it

Start with research_whoami: it says which workspace the key is in and what it may do.
Use research_search or the research_list tools to find ids. Every tool is scoped to the key's workspace; there is no organization selector.
Read a record before you change it. Updates take the record's current version and refuse a stale one with conflict.
Give every creation and effect a stable idempotencyKey, and reuse it on retry: the same call returns the same result instead of running twice.
Lists are bounded. Pass a cursor to read on; a result that would be too large says so.

Error code	Meaning
not_found	No such record in this workspace.
invalid_arguments	The input does not fit the tool's schema.
conflict	The record changed, or the idempotency key is bound to a different request. Read again and retry.
scope_denied	A read key called a write tool.
unsupported	The operation is not offered through MCP.
unavailable	A capability is switched off or a provider is not configured.
rate_limited	Too many calls. Wait and retry.
result_too_large	Narrow the query.

Write calls are reserved and audited per key before they run, so a retried write cannot run twice and every effect can be traced to the key that caused it.

What is not on MCP

Ordering panel respondents moves money and stays on Recruit; a study for your own people launches here. Sending messages to your own people, deleting a list, opting a person out, and billing stay on screen. It does not run arbitrary queries, browse other workspaces, or disclose share secrets. Participant lists and personal links are on the REST API and, for one person at a time, on research_own_person_link.

Tool catalogue

Generated from the server, so it is always current. A read tool never changes anything; a write tool does, and a destructive one archives, revokes, cancels, rejects or excludes.

Tool	Access	What it does
orientation
`research_whoami`	read	Show who this key belongs to, its fixed organization, scopes, and refused capability families.
`research_help`	read	Explain safe discovery workflows and unsupported operations.
`research_catalog`	read	List tool families in stable workflow order with access classification.
search
`research_search`	read	Search bounded tenant-scoped summaries without answer, transcript, upload, secret, or audit-log bodies.
flow
`research_flow_help`	read	The setup flow as tools, in order, for testing a study end to end without a browser: set up, read, refine, publish, launch, links, test interview, fieldwork, results, clean up.
`research_setup_study`	write	Create a study from a research brief and write its guide, the same way New study and Design do: the decision, the audience, what to learn, markets, length, language, and whether participants are your own people or a panel. Never write questions yourself: the platform writes the guide from the brief and its own screener. Takes about a minute. Returns the study id and every question.
`research_get_study`	read	One study as the researcher sees it: name, decision, brief (audience, markets, length, language, goals), the current guide with every question and the open findings of Design's guide check, how many responses it has, and its page links.
`research_edit_guide`	write	Make a targeted change to a study's guide from a plain instruction (add, remove, reword or reorder a few questions, change options), the same way Design's assistant does. Pass the intent, never question wording. For a whole new guide use research_regenerate_guide. A published guide gets a new draft version.
`research_regenerate_guide`	write	Write the study's whole guide again from its brief, the way Design's Draft guide does: when the guide is missing or a placeholder, when the brief changed, or to rethink it as a whole. Takes 30 to 90 seconds. A published guide gets a new draft version.
`research_edit_study_brief`	write	Change parts of a study's brief: decision, goals, audience, markets, length in minutes, number of participants, language, interviewer name. Only the fields given change. This does not rewrite the guide (research_regenerate_guide does).
`research_publish_guide`	write	Publish a study's current draft guide so it can be launched, as Design's Publish does. A published version cannot be edited; later edits make a new draft. Returns a preview until called with confirm: true.
`research_get_recruitment_setup`	read	Who a study recruits, exactly as saved on Recruit: the participant source, the audience rules, the quota cells and their targets, the plan's status, the planned interview length, the study's language and markets.
`research_estimate_recruitment`	read	Answer "how much", "how long" and "can we get them" for a panel recruit before anything is saved or launched: the reachable pool per market, the pool grade, the estimated cost and field time. For a study that invites its own people, says so.
`research_list_own_people`	read	Your own people on a study (Recruit, Your people): how many, where each stands (invited, opened, started, completed, opted out), the segments the list carries, and whether SMS and WhatsApp are connected. Names and stages only.
`research_add_own_people`	write	Add people to a study's own-people list (Recruit, Your people): name, phone or email, optional segments. Nobody is contacted; sending invitations stays on Recruit. Returns a preview until called with confirm: true.
`research_own_person_link`	read	The personal study link for one of your own people, by name, as Recruit's Link for one person does. Nothing is sent.
`research_study_links`	read	A launched study's links: the study link for your own people (whether it is on and open), the test link for the team, the same test link starting past the screeners (?screening=skip), and the test interviews taken so far with whether each was counted.
`research_count_test_interview`	write	Count a finished test interview in the results, on purpose, as Fieldwork's Count this interview does: it is copied under a real respondent as an accepted response. The test interview itself stays a test interview.
`research_pause_fieldwork`	write	Pause a study's fieldwork (no new people start; people mid-interview can finish) or resume it, as the Fieldwork page does.
`research_close_fieldwork`	write	Close a study's fieldwork for good, as the Fieldwork page's Close fieldwork does: no new people can start, interviews under way can finish, held panel places are released, and the study moves on to its results. Cannot be undone. Returns a preview until called with confirm: true.
`research_generate_report`	write	Write a new version of the study's written report from its complete responses (findings, charts, quotes, recommendations), exactly as the Report tab's Generate does. Takes about two minutes and continues in the background; the new version appears on the Report tab (research_list_reports).
`research_generate_demo_responses`	write	Fill a study with realistic demo responses (marked as demo everywhere) so its results pages can be seen before fieldwork. Underheard admins only. Takes a few minutes in the background. On a study that already has responses or demo data, returns a preview until called with confirm: true.
`research_archive_tests`	write, destructive	Archive every study in this workspace whose name starts with the given prefix (at least four characters, e.g. "MCP test:"), so test studies never pile up. Returns the studies it would archive until called with confirm: true. Archiving stops a study's interviews; it never deletes anything.
`research_update_respondent_copy`	write	Change what respondents read or hear around the questions, as Design's Welcome screen settings do: the title respondents see, the introduction on the welcome screen, the privacy notice, the consent statement, an optional end-screen email prompt, and for a spoken study the spoken opening and closing. Only the fields given change. A published guide gets a new draft version. Never put this text into a question's wording.
`research_set_study_languages`	write	The languages respondents may take the study in, as Design's Languages settings do. For a spoken study, `languages` are the languages offered on the welcome screen (two-letter codes; the study's own language is always kept). `autoTranslate` is Design's Translate automatically switch: on, the study is translated into every supported language at launch; off, respondents see only the languages it was written in. To write the study itself in another language, change the brief's language with research_edit_study_brief instead.
`research_save_report_version`	write	Save a shareable version of a study's results: a frozen copy of the current written report and the accepted responses, as Share and export on the Report tab does. Share links, PDF and PowerPoint downloads are built from the newest one. research_create_share_link saves one itself when none exists; call this to freeze a version on purpose, or right after a new report so the files carry it.
`research_create_share_link`	write	Create a public, read-only link to a study's report for people outside the workspace, as Share and export does: anyone with the link can read that report version for 30 days. When no shareable version is saved yet, one is saved first from the current written report. Returns a preview until called with confirm: true; research_revoke_report_share turns a link off.
`research_export_links`	read	Links to download a study's data and report: every response as an Excel workbook or a CSV file, the written report as a PDF (print view), and the report page. The downloads open in a signed-in browser; a key does not open them. For a link people outside the workspace can open, research_create_share_link.
studies
`research_list_studies`	read	List studies in the token-bound organization with bounded pagination.
`research_get_study_context`	read	Read one study and its bounded instrument revision summaries.
`research_create_study`	write	Create a draft study and initial draft instrument through the idempotent domain operation.
`research_update_study`	write	Update study name, objective, or method with optimistic concurrency.
`research_update_study_brief`	write	Replace the typed study brief with optimistic concurrency.
`research_set_study_stage`	write	Change a study stage and optional status with optimistic concurrency.
`research_set_study_archived`	write, destructive	Archive or unarchive a study with optimistic concurrency.
`research_list_instruments`	read	List bounded instrument revisions for one study.
`research_get_instrument`	read	Read one exact instrument revision in the token-bound organization.
`research_create_instrument`	write	Create a typed draft instrument revision for an existing study.
`research_update_instrument`	write	Update a draft instrument and its branch graph with optimistic concurrency.
`research_publish_instrument`	write	Publish a valid draft instrument revision with optimistic concurrency.
`research_launch_study`	write	Launch a study whose participants are the researcher's own people (brief recruitmentIntent "bring-own"), as Recruit's Launch button does: pins the newest published guide, opens fieldwork, and returns the study link and the test link. Nothing is bought and nobody is contacted. A study recruiting from a panel is refused: it launches on Recruit, where the order and its cost are shown. Calling it again after launch changes nothing.
`research_create_study_wave`	write	Create a new study wave from an existing instrument using a stable idempotency key.
`research_reuse_measure`	write	Copy one measure-backed question from a source revision into a target draft instrument.
audiences
`research_list_audiences`	read	List bounded audience-definition summaries in the authenticated organization.
`research_get_audience`	read	Read one tenant-scoped audience definition, including its filter and current storage version.
`research_create_audience`	write	Create an audience definition. This does not snapshot, import, recruit, or contact anyone.
`research_update_audience`	write	Update an audience definition using its current storage version.
`research_list_audience_snapshots`	read	List bounded frozen-audience metadata without membership references or member data.
`research_list_audience_sources`	read	List safe source capability metadata; endpoints and credential references are omitted.
`research_list_quota_plans`	read	List quota-plan configuration only; this tool cannot reserve quota.
`research_list_recruitment_plans`	read	List recruitment planning state without launching providers or contacting participants.
`research_get_recruitment_plan`	read	Read one tenant-scoped recruitment plan and its safe progress projection.
`research_create_recruitment_plan`	write	Create a draft recruitment plan idempotently; this never launches it.
`research_update_recruitment_plan`	write	Update draft recruitment planning fields using optimistic concurrency; this never launches it.
`research_set_recruitment_group_paused`	write	Pause or resume one existing recruitment group with optimistic concurrency; no provider is launched.
`research_list_fieldwork`	read	List fieldwork state and immutable launch metadata; this cannot launch fieldwork or contact participants.
quality
`research_list_quality_responses`	read	List bounded, redacted response summaries and quality counts for one study.
`research_get_quality_response_detail`	read	Read one tenant-scoped response. Answer and transcript text require standard detail.
`research_review_response`	write	Accept or reject a complete response with optimistic concurrency and a stable idempotency key.
`research_review_partial_response`	write	Include or exclude partial qualitative evidence with optimistic concurrency and a stable idempotency key.
analysis
`research_list_analysis_snapshots`	read	List or read immutable analysis snapshots in the token-bound organization.
`research_list_analysis_results`	read	List or read saved typed analysis results.
`research_preview_analysis_result`	read	Compute a typed result from an immutable snapshot without saving it.
`research_save_analysis_result`	write	Save or replay a typed result for an immutable snapshot.
`research_list_weight_sets`	read	List or read weight sets for immutable analysis snapshots.
`research_create_weight_set`	write	Create weights bound to an immutable analysis snapshot.
`research_list_transform_sets`	read	List or read typed recode and net definitions.
`research_create_transform_set`	write	Create immutable typed recodes and nets for a snapshot.
`research_list_library`	read	List or read bounded Research library metadata.
`research_set_asset_visibility`	write	Hide or show a supported asset with visibility-event compare-and-swap.
`research_save_library_item`	write	Save a typed Research library item without arbitrary record mutation.
`research_list_reports`	read	List or read saved report records without public-share secrets.
`research_list_report_deliveries`	read	List or read report delivery state and retry metadata.
`research_retry_report_delivery`	write	Retry only an existing non-contact download delivery.
`research_list_report_shares`	read	List or read share metadata without token hashes or plaintext tokens.
`research_revoke_report_share`	write, destructive	Revoke an existing report share without resolving or disclosing its token.
operations
`research_list_jobs`	read	List bounded, tenant-scoped workflow job summaries. Payloads, results, errors, and worker lease data are omitted.
`research_get_job`	read	Read one tenant-scoped workflow job summary without payload, result, error, or lease data.
`research_cancel_job`	write, destructive	Cancel one tenant-scoped workflow job. This never claims, checkpoints, heartbeats, or finishes a worker lease.
`research_retry_job`	write	Request one tenant-scoped manual workflow retry. This never claims or finishes a worker lease.
`research_get_worker_readiness`	read	Read the safe survey-worker readiness projection without worker identity, secrets, or provider configuration.
`research_list_sources`	read	List bounded source-connector summaries. Endpoints, credential references, and provider configuration are omitted.
`research_list_moderator_checks`	read	List bounded moderator-check run summaries for one study. Transcripts, provider metadata, and answer content are omitted.
lab
`research_lab_help`	read	How the interview lab tools fit together: versions, runs, transcripts, prompts, scenarios, replays, and the worker queue.
`research_lab_list_versions`	read	Every combination of code commit, interviewer prompt hash and model that ran, with run counts, spend and pooled headline metrics.
`research_lab_list_runs`	read	Runs newest first, with traceability (commit, prompt hash, models) and headline scores. Filter by scenario, commit, prompt hash or status.
`research_lab_get_run`	read	One run: its configuration, aggregate metrics with intervals, and every interview's status, flags and judge score.
`research_lab_get_interview`	read	One simulated interview. Detail summary gives metrics, flags and judge findings with evidence; transcript gives the spoken turns, tool calls and revealed facts from fromTurn, turns at a time.
`research_lab_compare_runs`	read	Metric differences between run A and run B with conservative 95% intervals and a verdict per metric; small samples are flagged.
`research_lab_list_prompts`	read	Every interviewer configuration the lab ran, by hash: source, model, temperature, tools, prompt length, first and last seen.
`research_lab_get_prompt`	read	One interviewer configuration in full: the system prompt text, the tool schemas and descriptions, and the turn settings.
`research_lab_list_scenarios`	read	The studies the lab can run, every synced version: industry, language, personas with their behaviours and planted facts count, section count.
`research_lab_get_scenario`	read	One scenario in full: personas with profiles, behaviours and planted facts, and the guide's sections, topics and probes.
`research_lab_list_replays`	read	Replay runs: the lab's interviewer written against real interviews turn by turn, with intent agreement, closeness and tool agreement.
`research_lab_get_replay`	read	One replay run with its per-case results: study, product, turns scored, same-intent rate, closeness, tool agreement, first divergence.
`research_lab_list_probes`	read	Probe reports: the probe bank (scripted moments, one interviewer turn each) run against one prompt, text only. Each report says which prompt and model ran, how many probes passed, and per case how many runs passed and which checks failed.
`research_lab_get_probe`	read	One probe report with its per-case summary and, when asked, every probe's reply verbatim (what the interviewer said, called and was answered) with the checks it failed.
`research_lab_list_evals`	read	Every eval that reached the dashboard in one shape, newest first: runs, forks, replays, probes, benchmark runs, paired runs and scorecards. One item each: kind, label, subject, status, the result in words (passed of total, or a score), the code commit and branch with a flag for uncommitted edits, the prompt hash, the models, spend, the pace (model latency per call, tool calls and model calls per interview or probe), and the machine it came from. Filter by kind, by a word in the label, subject or host, or by a commit or prompt prefix.
`research_lab_list_jobs`	read	The worker queue: queued, claimed, running and finished runs, forks, replays and re-scores, with who asked and the resulting run id.
`research_lab_list_workers`	read	Machines running `lab worker`: capabilities (browser, model keys, tiers), the commit they serve, their last heartbeat and current job. No worker online means queued jobs wait.
`research_lab_start_run`	write	Queue simulated interviews of a scenario for a connected worker. Spends up to budgetUsd of model credit. The agent is the repo prompt, the live agent, a stored prompt by hash, or a candidate prompt text.
`research_lab_fork_interview`	write	Continue a recorded interview from a spoken turn, count times, on a connected worker: the prefix replays for free, then the interview runs live with the chosen prompt and respondent model. Spends up to budgetUsd.
`research_lab_cancel_job`	write, destructive	Cancel a queued, claimed or running lab job. A worker already executing it stops at its next heartbeat; what it spent so far is kept and synced.
debug
`research_debug_help`	read	How a superadmin's notes from the debug panel reach an investigation: list the open notes, read the record around the flagged step, reply to close one.
`research_debug_feedback_list`	read	Developer feedback left on test interviews from the debug panel: open notes by default, each with its study, interview, flagged step, what the panel knew, and any replies.
`research_debug_interview_timeline`	read	One interview's debug timeline (what the interviewer received and did, step by step), the whole of it or a window around one event such as a feedback note, with the respondent's signals: address, approximate place, timezones, device and panel link parameters at each step of their way in, and flags (outside the study's countries, timezone mismatch, changed or shared address, automated browser).
`research_debug_feedback_resolve`	write	Reply to a feedback note with what was found or changed. The reply goes on the interview's timeline under the note, and the note leaves the open list.

Assistants and MCP

Connect Claude, ChatGPT, Cursor or any MCP client to your workspace, with the full tool catalogue, generated from the server.

Read the manual without a connection

GET /llms.txt
GET /llms-full.txt
GET /llms/recruitment.md

Connect

{
  "mcpServers": {
    "underheard-research": {
      "url": "https://research.underheard.ai/api/research/mcp",
      "headers": { "Authorization": "Bearer uh_research_YOUR_KEY" }
    }
  }
}

In Claude's web and desktop apps, add it as a custom connector with the same URL and the key as the bearer token. Settings, under API, shows the URL to copy.

Test a study end to end

The flow tools follow the screens, one tool per step, so an assistant or a script can set up and run a study the way a researcher does, without a browser. research_flow_help lists them in order.

research_setup_study: a brief (the decision, the audience, what to learn, markets, length, language) creates the study and writes its guide, as New study and Design do. It takes about a minute. Never write questions yourself.
research_get_study reads the guide with the open findings of Design's guide check; research_edit_guide changes it from a plain instruction; research_regenerate_guide writes it again from the brief.
research_publish_guide, then research_launch_study for a study whose participants are your own people. research_study_links returns the study link, the test link and the test link that starts past the screeners.
research_count_test_interview, research_pause_fieldwork and research_close_fieldwork run fieldwork; research_generate_report writes the report.
research_archive_tests archives every study whose name starts with your test prefix, so test studies never pile up.

How to work with it

Start with research_whoami: it says which workspace the key is in and what it may do.
Use research_search or the research_list tools to find ids. Every tool is scoped to the key's workspace; there is no organization selector.
Read a record before you change it. Updates take the record's current version and refuse a stale one with conflict.
Give every creation and effect a stable idempotencyKey, and reuse it on retry: the same call returns the same result instead of running twice.
Lists are bounded. Pass a cursor to read on; a result that would be too large says so.

Error code	Meaning
not_found	No such record in this workspace.
invalid_arguments	The input does not fit the tool's schema.
conflict	The record changed, or the idempotency key is bound to a different request. Read again and retry.
scope_denied	A read key called a write tool.
unsupported	The operation is not offered through MCP.
unavailable	A capability is switched off or a provider is not configured.
rate_limited	Too many calls. Wait and retry.
result_too_large	Narrow the query.

Write calls are reserved and audited per key before they run, so a retried write cannot run twice and every effect can be traced to the key that caused it.

What is not on MCP

Tool catalogue

Generated from the server, so it is always current. A read tool never changes anything; a write tool does, and a destructive one archives, revokes, cancels, rejects or excludes.

Tool	Access	What it does
orientation
`research_whoami`	read	Show who this key belongs to, its fixed organization, scopes, and refused capability families.
`research_help`	read	Explain safe discovery workflows and unsupported operations.
`research_catalog`	read	List tool families in stable workflow order with access classification.
search
`research_search`	read	Search bounded tenant-scoped summaries without answer, transcript, upload, secret, or audit-log bodies.
flow
`research_flow_help`	read	The setup flow as tools, in order, for testing a study end to end without a browser: set up, read, refine, publish, launch, links, test interview, fieldwork, results, clean up.
`research_setup_study`	write	Create a study from a research brief and write its guide, the same way New study and Design do: the decision, the audience, what to learn, markets, length, language, and whether participants are your own people or a panel. Never write questions yourself: the platform writes the guide from the brief and its own screener. Takes about a minute. Returns the study id and every question.
`research_get_study`	read	One study as the researcher sees it: name, decision, brief (audience, markets, length, language, goals), the current guide with every question and the open findings of Design's guide check, how many responses it has, and its page links.
`research_edit_guide`	write	Make a targeted change to a study's guide from a plain instruction (add, remove, reword or reorder a few questions, change options), the same way Design's assistant does. Pass the intent, never question wording. For a whole new guide use research_regenerate_guide. A published guide gets a new draft version.
`research_regenerate_guide`	write	Write the study's whole guide again from its brief, the way Design's Draft guide does: when the guide is missing or a placeholder, when the brief changed, or to rethink it as a whole. Takes 30 to 90 seconds. A published guide gets a new draft version.
`research_edit_study_brief`	write	Change parts of a study's brief: decision, goals, audience, markets, length in minutes, number of participants, language, interviewer name. Only the fields given change. This does not rewrite the guide (research_regenerate_guide does).
`research_publish_guide`	write	Publish a study's current draft guide so it can be launched, as Design's Publish does. A published version cannot be edited; later edits make a new draft. Returns a preview until called with confirm: true.
`research_get_recruitment_setup`	read	Who a study recruits, exactly as saved on Recruit: the participant source, the audience rules, the quota cells and their targets, the plan's status, the planned interview length, the study's language and markets.
`research_estimate_recruitment`	read	Answer "how much", "how long" and "can we get them" for a panel recruit before anything is saved or launched: the reachable pool per market, the pool grade, the estimated cost and field time. For a study that invites its own people, says so.
`research_list_own_people`	read	Your own people on a study (Recruit, Your people): how many, where each stands (invited, opened, started, completed, opted out), the segments the list carries, and whether SMS and WhatsApp are connected. Names and stages only.
`research_add_own_people`	write	Add people to a study's own-people list (Recruit, Your people): name, phone or email, optional segments. Nobody is contacted; sending invitations stays on Recruit. Returns a preview until called with confirm: true.
`research_own_person_link`	read	The personal study link for one of your own people, by name, as Recruit's Link for one person does. Nothing is sent.
`research_study_links`	read	A launched study's links: the study link for your own people (whether it is on and open), the test link for the team, the same test link starting past the screeners (?screening=skip), and the test interviews taken so far with whether each was counted.
`research_count_test_interview`	write	Count a finished test interview in the results, on purpose, as Fieldwork's Count this interview does: it is copied under a real respondent as an accepted response. The test interview itself stays a test interview.
`research_pause_fieldwork`	write	Pause a study's fieldwork (no new people start; people mid-interview can finish) or resume it, as the Fieldwork page does.
`research_close_fieldwork`	write	Close a study's fieldwork for good, as the Fieldwork page's Close fieldwork does: no new people can start, interviews under way can finish, held panel places are released, and the study moves on to its results. Cannot be undone. Returns a preview until called with confirm: true.
`research_generate_report`	write	Write a new version of the study's written report from its complete responses (findings, charts, quotes, recommendations), exactly as the Report tab's Generate does. Takes about two minutes and continues in the background; the new version appears on the Report tab (research_list_reports).
`research_generate_demo_responses`	write	Fill a study with realistic demo responses (marked as demo everywhere) so its results pages can be seen before fieldwork. Underheard admins only. Takes a few minutes in the background. On a study that already has responses or demo data, returns a preview until called with confirm: true.
`research_archive_tests`	write, destructive	Archive every study in this workspace whose name starts with the given prefix (at least four characters, e.g. "MCP test:"), so test studies never pile up. Returns the studies it would archive until called with confirm: true. Archiving stops a study's interviews; it never deletes anything.
`research_update_respondent_copy`	write	Change what respondents read or hear around the questions, as Design's Welcome screen settings do: the title respondents see, the introduction on the welcome screen, the privacy notice, the consent statement, an optional end-screen email prompt, and for a spoken study the spoken opening and closing. Only the fields given change. A published guide gets a new draft version. Never put this text into a question's wording.
`research_set_study_languages`	write	The languages respondents may take the study in, as Design's Languages settings do. For a spoken study, `languages` are the languages offered on the welcome screen (two-letter codes; the study's own language is always kept). `autoTranslate` is Design's Translate automatically switch: on, the study is translated into every supported language at launch; off, respondents see only the languages it was written in. To write the study itself in another language, change the brief's language with research_edit_study_brief instead.
`research_save_report_version`	write	Save a shareable version of a study's results: a frozen copy of the current written report and the accepted responses, as Share and export on the Report tab does. Share links, PDF and PowerPoint downloads are built from the newest one. research_create_share_link saves one itself when none exists; call this to freeze a version on purpose, or right after a new report so the files carry it.
`research_create_share_link`	write	Create a public, read-only link to a study's report for people outside the workspace, as Share and export does: anyone with the link can read that report version for 30 days. When no shareable version is saved yet, one is saved first from the current written report. Returns a preview until called with confirm: true; research_revoke_report_share turns a link off.
`research_export_links`	read	Links to download a study's data and report: every response as an Excel workbook or a CSV file, the written report as a PDF (print view), and the report page. The downloads open in a signed-in browser; a key does not open them. For a link people outside the workspace can open, research_create_share_link.
studies
`research_list_studies`	read	List studies in the token-bound organization with bounded pagination.
`research_get_study_context`	read	Read one study and its bounded instrument revision summaries.
`research_create_study`	write	Create a draft study and initial draft instrument through the idempotent domain operation.
`research_update_study`	write	Update study name, objective, or method with optimistic concurrency.
`research_update_study_brief`	write	Replace the typed study brief with optimistic concurrency.
`research_set_study_stage`	write	Change a study stage and optional status with optimistic concurrency.
`research_set_study_archived`	write, destructive	Archive or unarchive a study with optimistic concurrency.
`research_list_instruments`	read	List bounded instrument revisions for one study.
`research_get_instrument`	read	Read one exact instrument revision in the token-bound organization.
`research_create_instrument`	write	Create a typed draft instrument revision for an existing study.
`research_update_instrument`	write	Update a draft instrument and its branch graph with optimistic concurrency.
`research_publish_instrument`	write	Publish a valid draft instrument revision with optimistic concurrency.
`research_launch_study`	write	Launch a study whose participants are the researcher's own people (brief recruitmentIntent "bring-own"), as Recruit's Launch button does: pins the newest published guide, opens fieldwork, and returns the study link and the test link. Nothing is bought and nobody is contacted. A study recruiting from a panel is refused: it launches on Recruit, where the order and its cost are shown. Calling it again after launch changes nothing.
`research_create_study_wave`	write	Create a new study wave from an existing instrument using a stable idempotency key.
`research_reuse_measure`	write	Copy one measure-backed question from a source revision into a target draft instrument.
audiences
`research_list_audiences`	read	List bounded audience-definition summaries in the authenticated organization.
`research_get_audience`	read	Read one tenant-scoped audience definition, including its filter and current storage version.
`research_create_audience`	write	Create an audience definition. This does not snapshot, import, recruit, or contact anyone.
`research_update_audience`	write	Update an audience definition using its current storage version.
`research_list_audience_snapshots`	read	List bounded frozen-audience metadata without membership references or member data.
`research_list_audience_sources`	read	List safe source capability metadata; endpoints and credential references are omitted.
`research_list_quota_plans`	read	List quota-plan configuration only; this tool cannot reserve quota.
`research_list_recruitment_plans`	read	List recruitment planning state without launching providers or contacting participants.
`research_get_recruitment_plan`	read	Read one tenant-scoped recruitment plan and its safe progress projection.
`research_create_recruitment_plan`	write	Create a draft recruitment plan idempotently; this never launches it.
`research_update_recruitment_plan`	write	Update draft recruitment planning fields using optimistic concurrency; this never launches it.
`research_set_recruitment_group_paused`	write	Pause or resume one existing recruitment group with optimistic concurrency; no provider is launched.
`research_list_fieldwork`	read	List fieldwork state and immutable launch metadata; this cannot launch fieldwork or contact participants.
quality
`research_list_quality_responses`	read	List bounded, redacted response summaries and quality counts for one study.
`research_get_quality_response_detail`	read	Read one tenant-scoped response. Answer and transcript text require standard detail.
`research_review_response`	write	Accept or reject a complete response with optimistic concurrency and a stable idempotency key.
`research_review_partial_response`	write	Include or exclude partial qualitative evidence with optimistic concurrency and a stable idempotency key.
analysis
`research_list_analysis_snapshots`	read	List or read immutable analysis snapshots in the token-bound organization.
`research_list_analysis_results`	read	List or read saved typed analysis results.
`research_preview_analysis_result`	read	Compute a typed result from an immutable snapshot without saving it.
`research_save_analysis_result`	write	Save or replay a typed result for an immutable snapshot.
`research_list_weight_sets`	read	List or read weight sets for immutable analysis snapshots.
`research_create_weight_set`	write	Create weights bound to an immutable analysis snapshot.
`research_list_transform_sets`	read	List or read typed recode and net definitions.
`research_create_transform_set`	write	Create immutable typed recodes and nets for a snapshot.
`research_list_library`	read	List or read bounded Research library metadata.
`research_set_asset_visibility`	write	Hide or show a supported asset with visibility-event compare-and-swap.
`research_save_library_item`	write	Save a typed Research library item without arbitrary record mutation.
`research_list_reports`	read	List or read saved report records without public-share secrets.
`research_list_report_deliveries`	read	List or read report delivery state and retry metadata.
`research_retry_report_delivery`	write	Retry only an existing non-contact download delivery.
`research_list_report_shares`	read	List or read share metadata without token hashes or plaintext tokens.
`research_revoke_report_share`	write, destructive	Revoke an existing report share without resolving or disclosing its token.
operations
`research_list_jobs`	read	List bounded, tenant-scoped workflow job summaries. Payloads, results, errors, and worker lease data are omitted.
`research_get_job`	read	Read one tenant-scoped workflow job summary without payload, result, error, or lease data.
`research_cancel_job`	write, destructive	Cancel one tenant-scoped workflow job. This never claims, checkpoints, heartbeats, or finishes a worker lease.
`research_retry_job`	write	Request one tenant-scoped manual workflow retry. This never claims or finishes a worker lease.
`research_get_worker_readiness`	read	Read the safe survey-worker readiness projection without worker identity, secrets, or provider configuration.
`research_list_sources`	read	List bounded source-connector summaries. Endpoints, credential references, and provider configuration are omitted.
`research_list_moderator_checks`	read	List bounded moderator-check run summaries for one study. Transcripts, provider metadata, and answer content are omitted.
lab
`research_lab_help`	read	How the interview lab tools fit together: versions, runs, transcripts, prompts, scenarios, replays, and the worker queue.
`research_lab_list_versions`	read	Every combination of code commit, interviewer prompt hash and model that ran, with run counts, spend and pooled headline metrics.
`research_lab_list_runs`	read	Runs newest first, with traceability (commit, prompt hash, models) and headline scores. Filter by scenario, commit, prompt hash or status.
`research_lab_get_run`	read	One run: its configuration, aggregate metrics with intervals, and every interview's status, flags and judge score.
`research_lab_get_interview`	read	One simulated interview. Detail summary gives metrics, flags and judge findings with evidence; transcript gives the spoken turns, tool calls and revealed facts from fromTurn, turns at a time.
`research_lab_compare_runs`	read	Metric differences between run A and run B with conservative 95% intervals and a verdict per metric; small samples are flagged.
`research_lab_list_prompts`	read	Every interviewer configuration the lab ran, by hash: source, model, temperature, tools, prompt length, first and last seen.
`research_lab_get_prompt`	read	One interviewer configuration in full: the system prompt text, the tool schemas and descriptions, and the turn settings.
`research_lab_list_scenarios`	read	The studies the lab can run, every synced version: industry, language, personas with their behaviours and planted facts count, section count.
`research_lab_get_scenario`	read	One scenario in full: personas with profiles, behaviours and planted facts, and the guide's sections, topics and probes.
`research_lab_list_replays`	read	Replay runs: the lab's interviewer written against real interviews turn by turn, with intent agreement, closeness and tool agreement.
`research_lab_get_replay`	read	One replay run with its per-case results: study, product, turns scored, same-intent rate, closeness, tool agreement, first divergence.
`research_lab_list_probes`	read	Probe reports: the probe bank (scripted moments, one interviewer turn each) run against one prompt, text only. Each report says which prompt and model ran, how many probes passed, and per case how many runs passed and which checks failed.
`research_lab_get_probe`	read	One probe report with its per-case summary and, when asked, every probe's reply verbatim (what the interviewer said, called and was answered) with the checks it failed.
`research_lab_list_evals`	read	Every eval that reached the dashboard in one shape, newest first: runs, forks, replays, probes, benchmark runs, paired runs and scorecards. One item each: kind, label, subject, status, the result in words (passed of total, or a score), the code commit and branch with a flag for uncommitted edits, the prompt hash, the models, spend, the pace (model latency per call, tool calls and model calls per interview or probe), and the machine it came from. Filter by kind, by a word in the label, subject or host, or by a commit or prompt prefix.
`research_lab_list_jobs`	read	The worker queue: queued, claimed, running and finished runs, forks, replays and re-scores, with who asked and the resulting run id.
`research_lab_list_workers`	read	Machines running `lab worker`: capabilities (browser, model keys, tiers), the commit they serve, their last heartbeat and current job. No worker online means queued jobs wait.
`research_lab_start_run`	write	Queue simulated interviews of a scenario for a connected worker. Spends up to budgetUsd of model credit. The agent is the repo prompt, the live agent, a stored prompt by hash, or a candidate prompt text.
`research_lab_fork_interview`	write	Continue a recorded interview from a spoken turn, count times, on a connected worker: the prefix replays for free, then the interview runs live with the chosen prompt and respondent model. Spends up to budgetUsd.
`research_lab_cancel_job`	write, destructive	Cancel a queued, claimed or running lab job. A worker already executing it stops at its next heartbeat; what it spent so far is kept and synced.
debug
`research_debug_help`	read	How a superadmin's notes from the debug panel reach an investigation: list the open notes, read the record around the flagged step, reply to close one.
`research_debug_feedback_list`	read	Developer feedback left on test interviews from the debug panel: open notes by default, each with its study, interview, flagged step, what the panel knew, and any replies.
`research_debug_interview_timeline`	read	One interview's debug timeline (what the interviewer received and did, step by step), the whole of it or a window around one event such as a feedback note, with the respondent's signals: address, approximate place, timezones, device and panel link parameters at each step of their way in, and flags (outside the study's countries, timezone mismatch, changed or shared address, automated browser).
`research_debug_feedback_resolve`	write	Reply to a feedback note with what was found or changed. The reply goes on the interview's timeline under the note, and the note leaves the open list.

Assistants and MCP

Read the manual without a connection

Connect

Test a study end to end

How to work with it

What is not on MCP

Tool catalogue

Related pages

Assistants and MCP

Read the manual without a connection

Connect

Test a study end to end

How to work with it

What is not on MCP

Tool catalogue

Related pages