MCP: What's available - Great Question

The MCP provides access across the full research workflow: Candidates: Create, update, and delete participant profiles. View full profiles with demographics. Search by name, email, study, date, or saved segment. Study design: Create, update, and delete interview studies (1:1, round robin, or collective), survey studies, and unmoderated studies (prototype tests, website tests, card sorts, and tree tests). Configure incentives, participation caps, consent forms, participant language, and meeting providers. Build and manage screener questionnaires with qualification rules, disqualification rules, and skip logic across a full range of question types — or apply one of your saved templates instead of rebuilding questions from scratch. Add and reorder unmoderated study blocks (the tasks and questions participants work through). Scheduling: Configure interview booking limits, availability windows, buffers, scheduling notice, and livestream settings. Add, update, and remove moderators, collaborators, and observers. Recruitment: Find participants across all your studies by interview time, for example everyone interviewed or booked today. Shortlist existing candidates directly onto a study, or send screener invitations to qualify them first. Customize the invitation, screener, reminder, and other study emails before you send. Works across interview, survey, and unmoderated studies. Analysis: Browse and search sessions, transcripts, highlights, and participant responses (screener responses for interviews; survey and unmoderated submissions for surveys and unmoderated studies). Access speaker-attributed transcripts, including session recording transcripts surfaced directly on unmoderated responses, full-text search across transcript content, and prototype-test analytics (completion rate, top response paths, and drop-off by screen) with deep-links to heatmap and funnel views. Synthesis: Search the whole repository at once, and browse insights, highlights, reels, and tags across studies. Create, update, and delete highlights, reels, and insights, and create, apply, and remove tags, so work done in your AI tool is saved back to Great Question. Analytics: Admins on Enterprise plans can run the reports on the Analytics board (recruitment, panel health, research consumption, and seat usage) and get the same numbers the board shows.

Available tool calls

The MCP exposes the following tools, organized by research workflow stage. Write tools can create, update, and delete resources. Read tools retrieve and search data.

Candidate tools

Tool	What it does
`create_candidate`	Create a new participant profile. If a candidate already matches on your account’s unique identifier (email, phone, or external ID), that existing candidate is updated with the new details instead of creating a duplicate.
`update_candidate`	Update a participant’s profile and custom attributes.
`delete_candidate`	Permanently forget a candidate (irreversible). Use for GDPR compliance.
`get_candidate`	Get a full candidate profile by ID, including demographics, custom attributes, consent and opt-in status, and when they were last contacted. To see a candidate’s status in a study, use the participant tools.
`list_candidates`	Browse all participants. Returns name, email, and demographics. Supports pagination.
`search_candidates`	Find participants by name/email, study ID, saved segment, or updated-since timestamp.

You can also browse and search your account’s saved candidate segments (list_candidate_segments, get_candidate_segment, search_candidate_segments) and pass a segment ID into search_candidates to pull everyone matching that segment.

Study tools (all types)

These tools work across all study types (interviews, surveys, and unmoderated studies).

Tool	What it does
`get_study`	Get full details for a specific study by ID, including methodology and configuration.
`list_studies`	Browse standard studies in your workspace. Returns title, status, style, and configuration. Supports pagination. Does not return AI-moderated studies.
`search_studies`	Find studies by title, status (`draft`, `pending`, `active`, `paused`, `closed`, or `archived`), duration, creator, owner, whether you own it (owned_by_me), tags, creation date, last activity date, or last updated date.

Configuring study setup

When creating or updating any study type, you can configure:

Incentives:
- incentive_method (manual, tremendous, coupon, product, other)
- incentive (amount in whole currency units)
- currency (USD, AUD, TRY, GBP, CAD, EUR, or JPY), which can only be changed while the study is a draft
- incentive_title
- incentive_instructions
- incentive_coupons (codes, when the method is coupon)
- To run a study with no incentive, set incentive_method to null. Omitting it on create gives the workspace default: an incentive of 1 in the study’s currency (or the external recruitment minimum when external recruitment is on), paid through Tremendous if your account has funds or a card on file, otherwise manually.
Participation caps: participation_limit to cap how many people can participate
- interview studies accept an object with count and cadence (total or weekly);
- surveys and unmoderated studies accept an integer (total only).
As-started grace period: maximum_as_started_in_minutes — how long a participation can sit in “Started” before it reverts to “Invited” (defaults to 60 minutes for surveys and unmoderated studies; interview studies have no default, so participations never revert unless you set it).
Consent form: consent_form_id to attach a consent form (discover IDs with list_consent_forms / search_consent_forms). Set it to null to remove the attached form.
Research goal and ownership: research_goal and owner_id. Update tools also accept version, so an update fails instead of overwriting changes someone else made in the meantime.
Participant language: language for emails, booking pages, and public participation surfaces (de, en, es, fr, it, pt-BR, tr; defaults to en).

Interview studies additionally support:

Scheduling style: scheduling_style (one_on_one, round_robin, or collective; defaults to one_on_one)
- with round_robin_assignment (availability or fairness) when using round robin.
Meeting provider: meeting, an object with provider (manual, zoom, google_meet, microsoft_teams, webex, in_person) and, for manual only, a url. Plus duration_in_minutes.
Calendar & availability: availability (weekly hours, timezone, and booking window) and buffer_minutes. All days in weekly hours must share the same start and end time, and on update the days you pass replace the existing set.
Booking limits and notice: booking_limit (per_day and per_week; null means no cap), minimum_notice_minutes, and maximum_notice_days. Minimum notice can only be set here. Booking limits, maximum notice, and livestream settings can also be changed with the Scheduling tools below.

Screener question types. Screener and survey questions across all study types support these types: short_text, long_text, number, number_range, single_choice, multiple_choice, yes_no, email, website, info, date, location, and matrix. number_range questions need number_range_options, and matrix questions need matrix_options (rows and columns). Screener choice questions support qualifying answers, disqualifying answers, and skip logic. When updating a question, pass an empty skip_logic list to clear its rules; leaving skip_logic out keeps them.

Interview study tools

Study management:

Tool	What it does
`create_interview_study`	Create a new interview study (1:1, round robin, or collective) with optional screener and skip logic. Supports incentive setup, participation caps (total or weekly), meeting provider, calendar/availability configuration, consent form, and language.
`update_interview_study`	Update title, goal, team, owner, scheduling style, meeting provider, calendar/availability, incentive setup, participation caps, consent form, and language.
`delete_interview_study`	Soft-delete an interview study.
`get_interview_study`	Get full interview study details by ID.
`list_interview_studies`	Browse all interview studies. Supports pagination.
`search_interview_studies`	Filter by status (`draft`, `pending`, `active`, `paused`, `closed`, or `archived`), creator, owner, owned_by_me, or dates.

Screeners

Tool	What it does
`create_interview_screener`	Add or replace all screener questions on an interview study.
`delete_interview_screener`	Remove all screener questions from an interview study.
`get_interview_screener`	Get all screener questions and configuration.
`add_interview_screener_question`	Add a screener question with qualification, disqualification, and skip logic rules, at the position you choose. Existing questions are kept.
`update_interview_screener_question`	Edit a question or its logic rules.
`delete_interview_screener_question`	Remove a screener question.

Survey study tools

Study management:

Tool	What it does
`create_survey_study`	Create a new survey study, optionally with its questions in a single call. Supports incentive setup, a total participation cap, consent form, and language. Screener (qualification) questions are managed separately.
`update_survey_study`	Update title, goal, team, ownership, incentive setup, participation cap, consent form, and language.
`delete_survey_study`	Soft-delete a survey study.
`get_survey_study`	Get full survey study details by ID.
`list_survey_studies`	Browse all survey studies. Supports pagination.
`search_survey_studies`	Filter by status (`draft`, `pending`, `active`, `paused`, `closed`, or `archived`), creator, owner, owned_by_me, or dates.

Screeners

Tool	What it does
`create_survey_screener`	Add or replace all screener questions on a survey study.
`delete_survey_screener`	Remove all screener questions from a survey study.
`get_survey_screener`	Get all screener questions and configuration.
`add_survey_screener_question`	Add a screener question with qualification, disqualification, and skip logic rules, at the position you choose. Existing questions are kept.
`update_survey_screener_question`	Edit a question or its logic rules.
`delete_survey_screener_question`	Remove a screener question.

Survey questions

Edit a survey’s own questions one at a time, without replacing the rest. These are the survey itself, not its screener.

Tool	What it does
`list_survey_questions`	List a survey’s questions in display order. Supports pagination.
`add_survey_question`	Insert a question at the position you choose (label, question type, and the fields for that type). Existing questions are kept.
`update_survey_question`	Edit one question. Use `reorder_survey_question` to move it.
`reorder_survey_question`	Move a question to a new position (1-based) and shift the questions around it.
`delete_survey_question`	Remove a question and clear any skip logic that pointed to it.

Survey questions accept other and none_of_above on choice questions instead of qualifying and disqualifying answers. Survey skip logic can end the survey and submit it (with or without automatic review) or end it without submitting.

Unmoderated study tools

Unmoderated studies cover self-guided research, prototype tests, website tests, card sorts, and tree tests. Each study is built from an ordered set of blocks (the tasks and questions a participant works through). Study management:

Tool	What it does
`create_unmoderated_study`	Create a new unmoderated study with optional screener. Supports incentive setup, a total participation cap, consent form, and language.
`update_unmoderated_study`	Update title, goal, team, ownership, incentive setup, participation cap, consent form, and language.
`delete_unmoderated_study`	Soft-delete an unmoderated study.
`get_unmoderated_study`	Get full unmoderated study details by ID, including its ordered block configuration. Prototype-test blocks also return analytics (completion rate, top response paths, drop-off by screen) and deep-links to the heatmap and funnel views in the app.
`list_unmoderated_studies`	Browse all unmoderated studies. Supports pagination.
`search_unmoderated_studies`	Filter by status (`draft`, `pending`, `active`, `paused`, `closed`, or `archived`), creator, owner, owned_by_me, or dates.

Blocks

Tool	What it does
`create_unmoderated_block`	Add a task or question block — prototype test, website test, card sort, tree test, or a question block (short/long text, number, email, website, date, location, linear scale, single/multi select, yes/no, info). Structural blocks (welcome, thank you, permissions, AI-moderated interview) are created with the study.
`update_unmoderated_block`	Update a block’s shared attributes and its kind-specific fields (e.g. prototype/website URL, card sort cards and categories, tree test node randomization, rating scale bounds and labels, choice options, permission requirements). A tree test’s nodes are set when the block is created and can’t be changed afterward.
`reorder_unmoderated_block`	Move a block to a new position. Structural blocks stay pinned at the start and end.
`delete_unmoderated_block`	Remove a block. Structural blocks cannot be removed.

Block kinds. Set kind on create_unmoderated_block and pass the fields for that kind. Every kind also accepts the shared title, description, and required. The id returned on create is what you pass back to update_unmoderated_block and reorder_unmoderated_block.

`kind`	Kind-specific fields
`short_text`, `long_text`, `number`, `email`, `website`, `date`, `location`, `yes_no`, `info`	None. The shared fields are the whole block.
`linear_scale`	`number_range_options: {min, max, labels}` — a rating scale from `min` to `max` with optional labels keyed by position (see below).
`single_select`, `multi_select`	`options` (array of choice strings), `other` (offer a free-text “Other” choice). `multi_select` additionally accepts `none_of_above`.
`prototype_test`	`url` — a Figma prototype URL. Screens and paths are fetched from Figma asynchronously and are not present in the immediate response.
`website_test`	`url` — the site under test.
`card_sort`	`sort_type` (`open`, `closed`, or `hybrid`), `cards`, `categories`, `randomise_cards`, `randomise_categories`, `require_all_sorted` (whether every card must be sorted before submitting).
`tree_test`	`tree` (nested nodes), `randomise_tree_nodes`.

number_range_options shape (linear scale). Same vocabulary as the number_range screener question, so a scale is authored the same way in a screener or a block:

{
  "kind": "linear_scale",
  "title": "How likely are you to recommend us?",
  "number_range_options": {
    "min": 1,
    "max": 7,
    "labels": { "1": "Not at all likely", "7": "Extremely likely" }
  }
}

min and max are integers and define the endpoints. labels is optional and keys are the position as a string; unlabelled positions render as the number alone. Updating a labelled scale (say 1–5 → 1–7) keeps the labels of the surviving positions and lets you add labels for the new ones; narrowing drops labels that fall outside the new range.

Screeners

Tool	What it does
`create_unmoderated_screener`	Add or replace all screener questions on an unmoderated study.
`delete_unmoderated_screener`	Remove all screener questions from an unmoderated study.
`get_unmoderated_screener`	Get all screener questions and configuration.
`add_unmoderated_screener_question`	Add a screener question with qualification, disqualification, and skip logic rules, at the position you choose. Existing questions are kept.
`update_unmoderated_screener_question`	Edit a question or its logic rules.
`delete_unmoderated_screener_question`	Remove a screener question.

Scheduling tools

Interview calendar:

Tool	What it does
`update_interview_calendar_settings`	Configure daily/weekly booking limits (booking_limit_daily and booking_limit_weekly, where -1 means unlimited), livestream settings, and maximum scheduling notice in days. Availability, buffers, and minimum notice are configured via the interview study tools instead (see “Configuring study setup” above).
`get_interview_calendar_settings`	View current booking settings for an interview study.

Interview moderators

Tool	What it does
`add_interview_moderator`	Add a moderator, collaborator, or observer to an interview study, by user ID or email, optionally with a calendar.
`update_interview_moderator`	Change a team member’s role or calendar settings.
`remove_interview_moderator`	Remove a team member from the interview study. The study owner can’t be removed.
`list_interview_moderators`	View all assigned team members.

Study message tools

Customize the emails a study sends, invitations, screener invites, reminders, booking confirmations, thank-yous, and more, before you send them. Templates are your account’s per-kind defaults. A study holds one email template per kind, seeded from those defaults the first time that kind is opened or sent, and that is the copy the study actually sends. A study can also hold one-off copies written in the app for a single send; those carry custom: true and no automatic send reads them.

Tool	What it does
`list_message_templates` / `get_message_template`	Browse the message templates your account has saved, or fetch the default for a given kind (invite, screener, reminders, booked, thanks, welcome, and more). For a kind your account hasn’t customized, `get_message_template` returns the Great Question default.
`list_study_messages` / `get_study_message`	Browse or fetch a study’s messages. A message with `custom: true` is a one-off written in the app for a single send; every other message is the study’s own email template for that kind, the copy the study sends. A kind that has never been opened or sent has no message yet — read its default with `get_message_template`.
`compose_study_message`	Set the email template on a study for a kind (subject, body, sender, layout), seeded from your account default on the first call. A study holds one template per kind, so composing the same kind again replaces what is already there, including copy someone wrote in the app. It is not how you draft several different one-off emails.
`revise_study_message`	Edit an existing study message in place, by id. Revising a `custom: true` one-off changes nothing the study sends automatically.
`discard_study_message`	Discard a one-off message written for a single send. A study’s own email template cannot be discarded.

Participant tools

Tools for reading and changing a study’s participants, finding participants across studies by interview time, and adding candidates to a study. Read and change participant status. A participant’s status is the source of truth for attendance. A session with a recording does not mean the participant showed up, because recording starts when the moderator joins.

Tool	What it does
`list_study_participants` / `get_study_participant`	Browse a study’s participants, or fetch one, with their status, status timestamps, `interview_at`, and `study_id`.
`search_study_participants`	Find a study’s participants by status, for example everyone marked `no_show`.
`get_study_participation_status_counts`	Count a study’s participants in every status, including statuses with zero, without paging through participants. A quick way to check recruiting progress.
`update_study_participant`	Change a participant’s status the way a researcher does in the app: `shortlisted`, `removed`, `completed`, `no_show`, or `canceled`. Removing only applies before a participant is scheduled, and can be undone by shortlisting again — use `canceled` for someone already scheduled. Marking a participant completed does not pay or send an incentive. Incentives cannot be issued through MCP. Completing fails if the study lacks funds. Marking a participant `no_show` or `canceled` cancels an incentive they haven’t redeemed.

Find participants across studies by interview time. These tools return participants from every study you can see, so you can answer questions like “Which interviews were held or booked today?” in one call. Studies you can’t see, deleted studies, AI-moderated studies, and restricted candidates are excluded.

Tool	What it does
`list_participants`	Browse participants across all your studies, earliest interview first. Participants with no booked interview come last. Supports pagination (up to 100 per page).
`search_participants`	Filter participants across studies by `status`, `study_ids`, and an interview time window.

search_participants accepts these filters:

status: only participants in these statuses, for example scheduled, completed, or no_show.
study_ids: only participants of these studies.
interview_at: interviews at or after this time. This is when the interview happens, not when it was booked.
interview_before: interviews before this time.

The time window is half-open. It includes interview_at and excludes interview_before, so back-to-back windows never overlap or leave gaps. Participants with no booked interview never match a window. Timestamps must be ISO 8601 with a UTC offset, such as 2026-10-28T00:00:00-03:00 or 2026-10-28T09:00:00Z. A timestamp without an offset returns an error, because “today” depends on your timezone. A window whose end is not after its start also returns an error. For example, to find today’s interviews in UTC-3, pass:

{
  "interview_at": "2026-10-28T00:00:00-03:00",
  "interview_before": "2026-10-29T00:00:00-03:00"
}

Each result includes study_id, candidate_id, interview_at, and status. A booked interview time does not mean the interview took place. Check status, where completed and no_show are the source of truth. Shortlisting adds existing candidates to the study’s participant list; sending a screener invitation emails them to fill out the study’s screener. You can combine them (shortlist candidates first, then optionally send them a screener to qualify) or use either on its own. Shortlist existing candidates. Each call automatically skips candidates who are already on the study, inaccessible to your team, uncontactable, or ineligible.

Tool	What it does
`add_study_participant`	Shortlist candidates onto any study type by study ID (works across interview, survey, and unmoderated).
`add_interview_participant`	Shortlist candidates onto an interview study.
`add_survey_participant`	Shortlist candidates onto a survey study.
`add_unmoderated_participant`	Shortlist candidates onto an unmoderated study.

Send a screener invitation. Email candidates a link to fill out the study’s screener. Works whether or not they’ve already been shortlisted.

Tool	What it does
`send_interview_screener_invitation`	Send a screener invitation to candidates for an interview study.
`send_survey_screener_invitation`	Send a screener invitation to candidates for a survey study.
`send_unmoderated_screener_invitation`	Send a screener invitation to candidates for an unmoderated study.

Each send takes up to 500 candidates and only emails those who can be contacted; the response reports how many were sent and how many were skipped. Each sender also has a daily limit on screener invites, and a send that would go over it is refused with the number of invites left today.

Repository search

Tool	What it does
`search_repo`	Search the research repository the way its search page does: highlights, reels, insights (files included), sessions, and survey results ranked together by relevance, then by most recently updated. Search by text and filter by types (`insight`, `session`, `highlight`, `reel`, `survey_result`), study IDs, tag IDs, candidate IDs, creator IDs, or creation date, and sort by updated or created date, owner, or name. Each result carries a `url` that opens it in Great Question and a `reference` (`type`, `id`, `title`, `url`) to open with the matching `get_*` tool. Results you can’t open are omitted. Supports pagination.

Session & Transcript tools

Every session and transcript read tool returns a url that opens the record in the Great Question app. Share the url when you cite a session or passage so your team can jump straight to it.

Tool	What it does
`list_repo_sessions`	Browse all sessions (interviews, calls, observations). Returns title, summary, and timestamps. A session with a recording does not mean the participant attended; use `list_study_participants` for that. Supports pagination.
`search_repo_sessions`	Find sessions by title, candidate IDs, creator IDs, or study IDs.
`get_repo_session`	Get full session details by UUID, including tags, recording metadata, and associated study/candidate. When an account admin has opted in to API recording delivery, the recording also carries a short-lived signed video URL; the URL is omitted when PII hiding for the MCP is turned on, when your role can’t download recordings, on HIPAA accounts, and while the recording is still processing.
`get_repo_session_transcript`	Get the complete speaker-attributed transcript for a session. If the transcript is still being created, the response says it isn’t ready yet and how long to wait before trying again. If transcription failed, it says so and retrying won’t help.
`list_transcripts`	Browse all transcripts. Returns metadata (title, status, study, candidate, and a link), not the transcript text; use `get_repo_session_transcript` or `search_transcripts` for content. Supports pagination.
`search_transcripts`	Search within transcript content. `q` searches by meaning; `keyword` matches exact words and supports `OR`, quoted phrases, and `-` to exclude a word. Filter by candidate IDs or study IDs. Results are ranked passages with a score, so one transcript can appear more than once. Each excerpt returns `start_ms` (milliseconds into the recording where the excerpt begins) and a `url` that opens the session at that moment.
`get_transcript`	Get a complete transcript by ID with speaker attribution.

Response tools

Access participant responses across all three study types. What a “response” contains depends on the study type:

Interview studies: screener responses, the candidate’s answers to the screener questions, with qualification status and match score. The interview session itself is accessed via the Session & Transcript tools.
Survey studies: the full survey submission, the participant’s answers to the survey questions.
Unmoderated studies: the full submission, answers, task metrics, and timings. For AI-moderated sessions, the response also includes recording details (length, when it was recorded, and a pointer to the session transcript) and a link to the session in Great Question. Playable video links aren’t included.

Type	Tool	What it does
Interviews	`get_interview_response`	Get a participant’s screener answers, match score, and qualification status.
	`list_interview_responses`	Browse a study’s screener responses. Supports pagination.
	`search_interview_responses`	Filter screener responses by submission date.
Surveys	`get_survey_response`	Get a participant’s survey answers and qualification status.
	`list_survey_responses`	Browse a study’s survey responses. Supports pagination.
	`search_survey_responses`	Filter survey responses by submission date.
Unmoderated	`get_unmoderated_response`	Get a participant’s submission with answers, task metrics, and timings.
	`list_unmoderated_responses`	Browse a study’s unmoderated responses. Supports pagination.
	`search_unmoderated_responses`	Filter unmoderated responses by submission date.

Screener responses are also available per study type via the dedicated screener-response tools (e.g. get_interview_screener_response, list_survey_screener_responses, search_unmoderated_screener_responses). For interview studies, these return the same underlying data as get_interview_response and friends — interviews only have one screener, so there’s no separate qualification-screener dataset to distinguish. For surveys and unmoderated studies, the screener-response tools return a distinct qualification screener, separate from the study’s main response data. get_screener_response is a generic lookup that works across all three study types: pass a screener response ID and it returns that response, scoped to qualification screeners only.

Artifact tools (Highlights, Insights, Reels & Tags)

Every highlight, insight, and reel read tool (get_*, list_*, and search_*) returns a url that opens the artifact in the Great Question app. A highlight’s url opens its clip at the first quoted word.

Type	Tool	What it does
Highlights	`create_repo_highlight`	Highlight a passage of a session transcript, clipping the recording it covers. If the session has no recording, or the words have no timings (as in AI-moderated sessions), the highlight is text-only and can’t go in a reel. The transcript must be ready, and words already in another highlight can’t be highlighted again. Select the passage by a quote, which must match one passage word for word said by one speaker, or by `start_ms` and `end_ms`, which take every word spoken inside the range. Prefer a quote: transcripts show only `MM:SS` times, so a time range needs milliseconds you rarely know. Copy numbers as the transcript spells them, usually in words (“fifteen”, not “15”). Tags must be global or belong to the session’s study.
	`update_repo_highlight`	Revise a highlight’s title, description, or tags, or move it with a new quote or time range. Requires edit permission on the highlight’s study. Omitted fields keep their value. `tag_ids` replaces every tag; an empty list removes them all.
	`delete_repo_highlight`	Delete a highlight. Requires edit permission on the highlight’s study. Its words are unmarked in the transcript, its clip is removed from every reel that uses it, and insights that embed it stop showing it.
	`list_repo_interview_highlights`	List every highlight from one session by its `session_uuid`, including text-only highlights made on its transcript without a clip. Works for any kind of session, including recordings and unmoderated tests. Supports pagination.
	`list_repo_highlights`	Browse all highlights (annotated excerpts from sessions). Returns text, title, and color. Supports pagination.
	`search_repo_highlights`	Find highlights by title/text, candidate IDs, creator IDs, study IDs, or creation date (`created_at`, `created_before`). Returns newest first.
	`get_repo_highlight`	Get full highlight details by UUID, including description, tags, session reference, and `used_in` (the reels and insights that use the highlight). Does not return playable video URLs.
Insights	`list_repo_insights`	Browse all insights (research findings). Returns title, description, and content type. Supports pagination.
	`search_repo_insights`	Find insights by title/description, creator IDs, study IDs, or creation date (`created_at`, `created_before`). Returns newest first.
	`get_repo_insight`	Get full insight details by slug, including text, cover image, tags, and associated study.
	`create_repo_insight`	Write an insight: its title, a TipTap body, and the highlights (by UUID) and reels (by token) it embeds. The embeds follow the body, highlights first, each in the given order.
	`update_repo_insight`	Change an insight’s title, description, body, or embeds; omitted fields stay. A new body keeps every embed after it. `highlight_uuids` and `reel_tokens` each replace that kind’s embeds: kept ones stay in place, new ones are appended. An insight backed by an uploaded file has no body or embeds to change.
	`delete_repo_insight`	Delete an insight. The highlights and reels it embeds stay.
Reels	`create_repo_reel`	Compile highlights into a new reel, in the order given. Each highlight may appear once and must have a clip, so highlights made on untimed transcript words are rejected. The reel’s video is stitched in the background.
	`update_repo_reel`	Change a reel’s title, subtitle, or highlights. Omitted fields stay unchanged. `highlight_uuids` replaces the reel’s highlights and sets their order: include a highlight to add it, leave one out to remove it. A reel in a study only holds highlights from that study. Study synthesis reels cannot be changed. The reel’s video is restitched in the background when its highlights change.
	`delete_repo_reel`	Delete a reel. Its highlights stay. Study synthesis reels cannot be deleted.
	`list_repo_reels`	Browse all reels (curated highlight video compilations). Returns title and subtitle. Supports pagination.
	`search_repo_reels`	Find reels by title/subtitle, creator IDs, study IDs, or creation date (`created_at`, `created_before`). Returns newest first.
	`get_repo_reel`	Get full reel details by token, including clips (each with its `highlight_uuid`) and tags. Does not return playable video URLs.
Tags	`create_repo_tag`	Create a tag to apply to highlights, reels, and insights: global, or scoped to a study with `study_id`. A `group_id` must belong to the same study, or be global for a global tag. Names are unique within a study, ignoring case, so a taken name is rejected rather than reused. The error names the existing tag and its ID; apply that tag with `apply_repo_tag` instead.
	`list_repo_tags`	Browse the tags you can see: global tags and tags of studies you can read. Returns each tag’s ID, name, study, and group, so tag IDs on highlights, insights, and reels resolve to names. Supports pagination.
	`search_repo_tags`	Find tags whose name contains a word, ignoring case. Search before `create_repo_tag` so an existing tag is reused rather than duplicated. Supports pagination.
	`get_repo_tag`	Get one tag by ID, with its name, study, and group.
	`apply_repo_tag`	Add a tag to artifacts. Add one tag to up to 20 highlights, reels, or insights in one call, keeping the tags each already has. The tag must be global or belong to the same study. Returns the updated `tag_ids` of each artifact, and lists any artifact it could not tag with the reason.
	`remove_repo_tag`	Remove a tag from artifacts. Remove one tag from up to 20 highlights, reels, or insights in one call, keeping their other tags. Returns the updated `tag_ids` of each artifact, and lists any artifact it could not untag with the reason.

get_repo_highlight and get_repo_reel do not return playable video or thumbnail URLs, at the reel level or per clip. To reach recording content, use get_repo_session and get_repo_session_transcript on the referenced session. Candidate names on these responses are masked for consumers without team access to the candidate or without PII permission, matching the masking applied elsewhere in the API.

get_repo_highlight returns a used_in array that lists every reel and insight using the highlight, reels first. Each entry has a type (reel or insight), id, and title. To open one, pass its id to get_repo_reel as the token or to get_repo_insight as the slug. Items you don’t have access to are omitted, and used_in is empty when nothing uses the highlight. Filter artifacts by creation date. search_repo_highlights, search_repo_insights, and search_repo_reels accept two ISO 8601 date or timestamp filters. created_at keeps artifacts created at or after the value. created_before keeps artifacts created before it. Combine them for a bounded window. An invalid date returns a tool error instead of results.

{
  "q": "onboarding",
  "created_at": "2026-09-01",
  "created_before": "2026-10-01T00:00:00Z"
}

"used_in": [
  { "type": "reel", "id": "a1b2c3d4", "title": "Onboarding pain points" },
  { "type": "insight", "id": "onboarding-friction", "title": "Onboarding friction" }
]

Analytics tools

These tools read the reports on your account’s Analytics board, so you can ask questions like “How many studies did we launch each month this quarter?” without opening the app. They return the same numbers the board shows.

Admin-only; Analytics access required. Analytics is included with Enterprise plans and may also be enabled for other accounts. For accounts with MCP access, these tools appear only when Analytics is enabled. Creators and Observers on those accounts see the tools but get a permission error when they run them.

Tool	What it does
`get_report_catalog`	List the reports available on your account, what each one measures, which filters it accepts, and the shapes it can be returned as (for example a single number, a bar chart, or a table). Call this first: a report rejects any filter it doesn’t list, and some reports are listed with a reason they can’t be run yet.
`run_report`	Run one report by its key from `get_report_catalog`. Optionally set a date window (`starts_at`, `ends_at`), a weekly or monthly `interval`, and filters for study status, study type, team, user, or role. Returns the same columns and rows the Analytics board renders, capped at the same row limit.

Template tools

Reuse your account’s saved screener templates instead of rebuilding questions from scratch every time.

Tool	What it does
`list_templates`	Browse all saved templates. Supports pagination.
`search_templates`	Find templates by kind (survey or interview). Each result reports how many questions it carries.
`get_template`	Get a single template by ID, including its full list of questions.
`apply_interview_screener_template`	Copy a template’s questions onto an interview study’s screener.
`apply_survey_screener_template`	Copy a template’s questions onto a survey study’s screener.
`apply_unmoderated_screener_template`	Copy a template’s questions onto an unmoderated study’s screener.

Applying a template replaces all existing questions on that screener, it doesn’t merge or append. If you want to keep existing questions, add to the screener with the type-specific add_*_screener_question tools instead.

Workspace tools

A few helpers surface the building blocks you reference when setting up studies:

Teams (list_teams, get_team, search_teams) — your account’s teams; pass a team ID when creating or assigning a study.
Consent forms (list_consent_forms, search_consent_forms) — consent forms available to attach to a study via consent_form_id.
Candidate segments (list_candidate_segments, get_candidate_segment, search_candidate_segments) — saved candidate filters; use a segment ID with search_candidates.

Common tool call parameters

Most list and search tools support these options:

Pagination: page (default 1), items (default 20, max 100)
Date filtering: a single timestamp per filter (e.g. submitted_at, created_at) that returns records after that point in time. Some tools also take an end bound: created_before on search_repo, search_repo_highlights, search_repo_insights, and search_repo_reels; interview_before on search_participants; and starts_at/ends_at on run_report. search_candidates takes updated_since. There’s no relative-duration syntax.

Security & data handling


Authentication	OAuth 2.1 with PKCE for human-driven clients, no secrets stored on your device. Agents connecting on their own use a secure API token instead: issued once, then used automatically in the background without further logins.
Permissions	Respects your existing Great Question access controls. You only see what you can already see in the product. Highlights involving candidates you are restricted from are anonymized, in the MCP and the public API. Updating or deleting a highlight requires edit permission on its study.
PII hiding	An admin can turn on PII hiding for the MCP in Settings → AI & MCP. It applies to every MCP connection in the workspace, and not to the Great Question app. When it’s on, the MCP masks candidate details; session titles and summaries; highlight titles, text, and descriptions; reel titles, subtitles, and clip text; insight titles and descriptions and the title of the study an insight belongs to; transcript titles and speaker names; names in search results; and calendar invitee names and emails. Signed recording URLs are not returned.
Data scope	Read and write over text-based data. The MCP can create, update, and delete candidates, studies, screeners, blocks, moderators, study messages, and participant shortlists, can create, update, and delete repository highlights, reels, and insights, can create tags and apply or remove them on highlights, reels, and insights, and can send screener invitations. Repository artifacts created through the MCP are saved under the connected user’s name. Recording video stays in the Great Question product unless an account admin explicitly enables API recording delivery (never available on HIPAA accounts, and requires acknowledging that recordings can contain participant PII) — with it enabled, session responses include short-lived signed video URLs for callers whose role permits recording downloads.
Rate limits	Each connection can make up to 60 requests per minute. The limit applies separately to each connection’s credential (OAuth login or agent API token), and requests with no credentials are counted per IP address. A request over the limit returns a `429` error with a `Retry-After` header that says how many seconds to wait.
Data freshness	Real-time. Tools read live data, not a synced copy. Repository and transcript search use search indexes that update shortly after changes, so brand-new content can take a moment to appear there.
Retention	Response content and the inputs you pass to tools are not stored. A record of each call (which tool ran, when, and whether it succeeded) is kept for 90 days. Other request metadata is retained per Great Question’s existing policies.
Third parties	The MCP server runs on Great Question’s infrastructure. No additional third-party processors are introduced. Once data is returned to your MCP client, it’s handled by that client’s data policies.

For full privacy details, see our Privacy Policy.

Troubleshooting

Permission errors? The MCP respects your existing Great Question access controls. If you can’t see certain studies or sessions, check your permissions in the Great Question product. Seeing “Rate limit exceeded”? Each connection is limited to 60 requests per minute. Wait the number of seconds shown in the error, then try again. If an agent hits the limit often, slow down how often it calls tools, or use list and search tools with a larger page size (items, up to 100) so it needs fewer calls. Still need help? Contact us at support@greatquestion.co — median response time is 19 minutes during support hours.

​Available tool calls

​Candidate tools

​Study tools (all types)

​Configuring study setup

​Interview study tools

​Screeners

​Survey study tools

​Screeners

​Survey questions

​Unmoderated study tools

​Blocks

​Screeners

​Scheduling tools

​Interview moderators

​Study message tools

​Participant tools

​Repository search

​Session & Transcript tools

​Response tools

​Artifact tools (Highlights, Insights, Reels & Tags)

​Analytics tools

​Template tools

​Workspace tools

​Common tool call parameters

​Security & data handling

​Troubleshooting

Available tool calls

Candidate tools

Study tools (all types)

Configuring study setup

Interview study tools

Screeners

Survey study tools

Screeners

Survey questions

Unmoderated study tools

Blocks

Screeners

Scheduling tools

Interview moderators

Study message tools

Participant tools

Repository search

Session & Transcript tools

Response tools

Artifact tools (Highlights, Insights, Reels & Tags)

Analytics tools

Template tools

Workspace tools

Common tool call parameters

Security & data handling

Troubleshooting