MCP tools reference

Every tool the Surbee MCP server exposes, with its parameters and whether it changes your workspace.

Every tool acts on the workspace of the account that connected the app. Survey ids come from get_all_surveys or find_surveys. Tools marked Changes workspace write to your account. Tools marked Destructive cannot be undone, and apps that confirm tool calls will ask you before running them.

Parameters marked with an asterisk are required. For tools that take survey_id, survey_ids or all_surveys, give one of the three.

Workspace

ToolWhat it doesParameters
get_all_surveysLists every survey with its status, dates and share link.include_archived
find_surveysFinds surveys from a loose description by searching titles, descriptions, questions and options.query*
get_survey_detailsOne survey: whether it is published, its response count, pages, and every question with its id, type, options and required flag.survey_id*

Build and edit

ToolWhat it doesParameters
create_surveyBuilds a new survey or AI interview from a brief with Surbee's builder agent and saves it as a draft. Returns the editor link. Takes up to a minute.title, brief, kind (intelligent or traditional)Changes workspace, uses credits
edit_surveyChanges an existing survey with the builder: add, remove or rewrite questions, reorder, restyle, or change an AI interview's voice and tone.project_id, changesChanges workspace, uses credits
update_survey_detailsRenames a survey or changes its description.project_id*, title, descriptionChanges workspace
update_questionChanges one question's wording, helper text, required flag or options.project_id, question_id, label, description, required, optionsChanges workspace
publish_surveyPublishes a survey and returns its public link.project_id*Changes workspace
share_surveyReturns the share link, QR code and embed code for a published survey.project_id*, format (all, link, qr, embed)
delete_questionsDeletes questions from a survey.project_id, question_ids, summary*Destructive
delete_surveyDeletes a survey and all its responses.project_id, summaryDestructive

The kind on create_survey defaults to intelligent, an AI interview that asks its own follow-up questions. Use traditional for fixed question lists, forms, quizzes and scores tracked over time.

Responses

ToolWhat it doesParameters
query_responsesLists individual responses with filters, newest first by default. Returns ids for get_response_details.survey_id, limit (max 100), offset, flagged_only, min_completion_time_seconds, max_completion_time_seconds, device, order_by (created_at, completion_time, fraud_score), order_direction, date_from, date_to
get_response_detailsOne response in full: every answer, time spent per question, device, Cipher quality, flag reasons and your verdict.response_id*
get_time_series_dataResponse counts over time, for trends.survey_id, group_by (hour, day, week, month), date_from, date_to, flagged_only

Analysis

These compute the same numbers as the Insights page. Preview responses are never counted.

ToolWhat it doesParameters
get_survey_statsHeadline numbers: responses, completion rate, first and last response, quality split.survey_id, date_from, date_to
compare_surveysPuts the headline numbers for several surveys side by side.survey_id, survey_ids, all_surveys, date_from, date_to
get_dropoffWhere people stop answering, question by question.survey_id, survey_ids, all_surveys, date_from, date_to
analyze_questionThe answer breakdown for one question, optionally split by another question.question*, survey_id, survey_ids, all_surveys, segment_by, trusted_only
count_respondentsCounts people who match answer conditions, such as rated 4 or more and chose Monthly.conditions*, match (all, any), quality (trusted, review, flagged, not_flagged), device, survey_id, survey_ids, all_surveys
find_similar_answersFinds open answers that mean the same thing as a description.description*, question, limit, survey_id, survey_ids, all_surveys
get_themesGroups open answers into themes with counts and examples.survey_id*
find_group_differencesFinds where groups of respondents answer differently.survey_id*
get_key_driversFinds which answers move an outcome question most.survey_id*

Cipher and quality

ToolWhat it doesParameters
get_cipher_summaryHow many responses Cipher trusted, sent for review or flagged, and the most common reasons.survey_id, survey_ids, all_surveys
explain_responsesExplains in plain words why responses were flagged, with the questions involved.survey_id*, response_id, only_flagged, limit
run_evaluationHas simulated respondents take a survey and reports confusing wording, missing options, bias and broken flow. Takes about a minute.project_id*, mode (human_like, edge_case, stress_test, all)Uses credits

Results

Every tool returns JSON as text. Results that point at a survey include editor_url, a link to open it in Surbee. When a tool cannot do what was asked, for example because the survey was not found, the result is marked as an error and says why.