MCP Tool Reference

Connect using the MCP server guide. The tool groups below describe the customer-facing tool inventory. Each tool’s discovered input schema is the reference for its required fields, enums, and optional settings. Availability in discovery does not remove user-permission or feature checks.

​

Tool groups

​

Read a study before changing it

Start with list_studies, then get_study. Inspect the study’s current questions, sections, settings, and relevant feature prerequisites before applying changes. New section-based studies expose their topic-guide structure through sections; older studies can use researchObjectives as the topic containers. Read isSectionBased and use the returned identifiers. Do not assume every research-objective ID is a section ID. Screener-directed stimulus allocation requires the study’s allocation feature to be enabled. get_study reports screenerDirectedAllocationEnabled; MCP does not enable that gate. Configure eligibility and balancing only when the prerequisite is satisfied. Global template publication is outside this customer workflow. set_question_routing also supports stimulusAssetCondition for a non-screener question: match the asset assigned to a randomized stimulus with stimulusId, operator: "isAnyOf", and assetIds. The stimulus does not need to appear before the routed question. Screener questions cannot use this condition because their routing occurs before that assignment. After a mutation, read back the affected study. Avoid blindly retrying a creation request after a timeout: the first call may already have created the item.

​

Use the setup assistant deliberately

chat_with_setup_assistant runs a real setup-assistant turn and accepts changes made during that turn into the study. Use it on a draft study you intend to modify. Pending changes previously left unreviewed in the editor are not automatically accepted by this tool. Run one setup-assistant turn at a time for a study. Review returned applied changes and any changes that could not be applied, then inspect the study before testing or launching it.

​

Configure facet extraction

add_facet_to_study accepts transcriptAndVideo as an extraction source alongside the other sources in their discovered schemas. Use the source that matches the evidence needed, and check that the relevant interview evidence is available. Facet changes require study editing access; review facets for extraction behavior and limitations.

​

Run analysis

1. Use create_analysis_session with one or more accessible study IDs.
2. Keep its returned sessionId.
3. Call query_study_data with that ID and a research question.
4. Reuse the session ID for follow-up questions, or inspect prior messages with get_analysis_session_messages.

The query can return a Markdown answer plus studies, tables, charts, and cited quotes. Treat the source references and structured results as evidence to review, rather than assuming every generated statement is correct. The analysis call has a server-side timeout; an error is not proof that no work occurred.

​

Find and download evidence

Use search_clips to find candidate quotes and their message IDs. To download a snippet, call prepare_snippet_download and inspect the result:

• ready: use the returned download URL.
• processing: retain the quote ID and poll get_snippet_download_status.
• error/failed: inspect the response; a missing video or failed extraction cannot be fixed by treating the response as a file.

Use list_quote_reels followed by download_quote_reel for existing reels. A reel may still be processing or have failed; the download tool reports that state instead of always returning a file. Review the quote-reel guide for rendering and sharing behavior.

​

Pagination and credential differences

list_studies uses page and pageSize with a maximum page size of 100. list_interviews uses skip and take, with a default take of 20 and maximum of 100. Interview listing can filter status, visibility, quality, and provider flags; it is broader than the completed-interview REST API. Read the schema for each listing tool instead of assuming one pagination convention applies everywhere. API keys expose only the six read tools listed in the connection guide; analysis, mutations, and download-preparation tools require an authorized OAuth connection.