SurveyMonkey

Get details about a specific question. **PREREQUISITES:** - survey_id: Get this from `search_surveys` - page_id: Get this from `get_pages(survey_id)` - question_id: Get this from `get_questions(survey_id, page_id)` Args: survey_id: The ID of the survey containing the question (get from search_surveys) page_id: The ID of the page containing the question (get from get_pages) question_id: The ID of the question to retrieve (get from get_questions) Returns: Dictionary containing question details

get_question

Get a complete statistical summary of all responses to a survey. Returns pre-computed, numerically accurate counts, percentages, and statistics for every question — with human-readable choice labels already resolved. **TRIGGER PHRASES — use this tool when the user asks:** - "How many people said/chose/answered/picked/selected yes/no/X..." - "What percentage/proportion..." - "What are the results/statistics/numbers..." - "Summarize/analyze the responses..." - "What's the average/mean rating..." - "Show me the breakdown/distribution..." - "How did people respond to..." - "Count of people who..." - "Did more people choose X or Y..." - "What's the most/least popular/common answer..." - "How popular was option X..." - Any counting, tallying, comparison, or aggregation of response data **DO NOT use get_responses, get_pages, or get_questions for counting or aggregation.** Those tools return raw data that requires manual iteration. Use THIS tool for any numerical analysis of responses. **WORKFLOW:** 1. search_surveys → get survey_id 2. get_response_summary(survey_id) → returns ALL questions with headings and counts 3. Find the relevant question in the results by its heading text 4. Report the counts/percentages directly to the user You do NOT need get_pages or get_questions first. This tool already returns every question's heading, answer text, counts, and percentages in one call. **Supported question types:** - single_choice / multiple_choice: per-choice counts, percentages, and stats - matrix: per-row breakdown with choice counts and stats - open_ended: answered/skipped counts only (no text content) **Required OAuth scopes:** responses_read_detail Args: survey_id: The ID of the survey (string or int) status: Filter responses by status (completed, partial, disqualified, overquota) Returns: Dictionary containing: - data (list): Per-question summaries with choice text, counts, percentages - total_responses (int): Total responses included in the summary

get_response_summary

Get details about a specific survey. **PREREQUISITE:** You need a survey_id. To get survey IDs, use `search_surveys` first which returns a list of surveys with their `id` fields. **USE THIS WHEN:** User already has a survey ID and wants its details. **DO NOT USE WHEN:** User doesn't know their survey ID - use `search_surveys` first. **IF search_surveys FAILS:** Tell the user there's a temporary issue and to try again later. Do NOT suggest looking at URLs, web UI, or other methods to find the survey ID. **RETURNS:** Survey metadata including: id, title, href, preview URL, is_owner, date_modified, date_created, language, nickname, folder_id, and question_count. Owner user ID is not returned. Args: survey_id: The numeric ID of the survey (get this from search_surveys) Returns: Dictionary containing survey details (preview, is_owner, dates, language, nickname, folder_id, question_count, and core id/title/href).

get_survey

Get survey responses with full answer data. Retrieves responses for a survey including all answer details. Supports pagination for surveys with many responses. Automatically enriches responses with question headings and answer choice text. **IMPORTANT — TOOL SELECTION:** For counting, percentages, averages, or any numerical analysis of responses, use get_response_summary instead. It returns pre-computed, accurate statistics. This tool (get_responses) returns raw individual response records and is appropriate for reading specific respondent answers or qualitative text content. **Required OAuth scopes:** responses_read, responses_read_detail **Plan limitations:** Basic plan accounts are limited to the first 25 responses. Attempting to retrieve beyond this limit will return an UpgradeRequired error. To access all responses, upgrade to a paid plan. **PARTIAL ANALYSIS DISCLOSURE — MANDATORY:** This tool returns PAGINATED results. The response includes: - ``data``: Response records for this page only - ``page``: Current page number - ``per_page``: Records per page (default: 10, max: 100) - ``total``: Total responses across ALL pages **YOU MUST ALWAYS:** 1. Check if ``total > len(data)`` — this means the analysis covers only a SUBSET of responses 2. If partial, ALWAYS tell the user BEFORE presenting any analysis: "Note: I retrieved {len(data)} of {total} total responses. This analysis covers only {len(data)} responses." 3. NEVER present partial analysis as if it covers all responses 4. NEVER say "Based on all 270 responses" when you only retrieved 100 5. If total is large (e.g., >50) and the user wants analysis or statistics, note: "I retrieved {len(data)} of {total} total responses. For accurate statistics across all {total} responses, use get_response_summary instead." **REQUIRED response format when total > len(data):** ✓ "Note: Analyzing {len(data)} of {total} total responses (page {page}):" ✓ "I retrieved {len(data)} responses out of {total} total — here's what they show:" ✗ "Based on the survey responses:" (WRONG — implies complete coverage) ✗ "The survey results show:" (WRONG — doesn't disclose partial data) Args: survey_id: The ID of the survey (string or int) page: Page number for pagination (default: 1, minimum: 1) per_page: Number of responses per page (default: 10, max: 100) Returns: Dictionary containing: - data (list): List of response objects with enriched answer data - page (int): Current page number - per_page (int): Number of items per page - total (int): Total number of responses Example success response: { "data": [ { "id": "12345", "survey_id": "67890", "pages": [ { "id": "page_1", "questions": [ { "id": "q1", "heading": "How satisfied are you?", "family": "single_choice", "answers": [ { "choice_id": "123", "choice_text": "Very Satisfied" } ] } ] } ] } ], "page": 1, "per_page": 10, "total": 42 }

get_responses

Returns information about the MCP server. Returns: Dictionary containing server information

get_server_info

Get pages for a survey. **PREREQUISITE:** You need a survey_id. To get survey IDs, use `search_surveys` first. **USE THIS WHEN:** User needs page IDs from a survey. The returned `id` field for each page is what `get_questions`, `get_page`, and other page-related tools need. **NEVER use for response analysis.** If the user asks how many people answered, what percentage chose X, or any counting/aggregation of responses, use get_response_summary instead — it already returns all question headings and pre-computed counts in one call without needing page_id or question_id. **ID HIERARCHY:** - `search_surveys` → survey_id - `get_pages(survey_id)` → page_id (this tool) - `get_questions(survey_id, page_id)` → question_id Args: survey_id: The ID of the survey (get this from search_surveys) page: Page number for pagination (default: 1) per_page: Number of pages per page (default: 50, max: 100) Returns: Dictionary containing pages list and pagination info

get_pages

Get questions for a specific page in a survey. **PREREQUISITES:** - survey_id: Get this from `search_surveys` - page_id: Get this from `get_pages(survey_id)` - REQUIRED **IMPORTANT:** page_id is REQUIRED. Questions are anchored under pages in the SurveyMonkey Public API. To get all questions in a survey, first call `get_pages()` then call this for each page. **NEVER use for response analysis.** If the user asks how many people answered, what percentage chose X, or any counting/aggregation of responses, use get_response_summary instead — it already returns all question headings and pre-computed counts in one call without needing page_id or question_id. **ID HIERARCHY:** - `search_surveys` → survey_id - `get_pages(survey_id)` → page_id - `get_questions(survey_id, page_id)` → question_id (this tool) Args: survey_id: The ID of the survey (get from search_surveys) page_id: The ID of the page (get from get_pages - REQUIRED) page: Page number for pagination (default: 1) per_page: Number of questions per page (default: 50, max: 100) Returns: Dictionary containing questions list and pagination info

get_questions

Bulk operation: reorder ALL questions on a page. BLOCKED when the survey has responses. Requires a list of ALL question IDs. **USE THIS WHEN:** - User provides a COMPLETE LIST of question IDs in a new order - User wants to move a GROUP of questions (e.g., "move demographic questions to end") - User wants to reorganize the entire page order **WORKFLOW for "move X questions to end" requests:** 1. Call get_questions to get ALL questions on the page 2. Identify which questions match the user's criteria (e.g., demographic type) 3. Reorder the list with matching questions at the end 4. Call this tool with the complete reordered list **NEVER use for single-question operations.** If user mentions just ONE question (like "move question 123 to first"), use edit_question instead. **KEY RULE:** This tool requires ALL question IDs on the page. You must: 1. First call get_questions to get the current list 2. Reorder the IDs as needed 3. Pass the complete reordered list to this tool Args: survey_id: The ID of the survey page_id: The ID of the page to update question_order: List of ALL question IDs on the page in desired order (must include every question) Returns: Dictionary with updated questions list for the page, or partial failure info

reorder_questions

Get a list of surveys for the authenticated user. **DISCOVERY NOTE:** This is the PRIMARY tool for discovering survey IDs. When a user asks "how do I get a survey ID" or "what's my survey ID", use this tool first. The returned `id` field is what other tools need. **USE THIS WHEN:** User wants to see, view, list, or browse their surveys, OR when user needs to find a survey ID. **TRIGGER PHRASES:** - "show my surveys" - "list my surveys" - "what surveys do I have?" - "view my questionnaires" - "how many surveys do I have?" - "get all my surveys" - "how do I get a survey ID?" - "what's my survey ID?" - "find my survey called..." **IF THIS TOOL FAILS:** Tell the user there's a temporary issue and to try again later. Do NOT suggest looking at URLs, web UI, or other methods to find survey IDs. **AUTHENTICATION:** Requires a valid bearer token in the Authorization header. The token is automatically extracted from the request context. **PAGINATION HANDLING - MANDATORY:** This tool returns PAGINATED results (default 10 per page). The response includes: - `data`: Array of surveys returned in this page - `page`: Current page number - `per_page`: Maximum surveys per page (default: 10, max: 100) - `total`: Total number of surveys across ALL pages **YOU MUST ALWAYS:** 1. Check if `total` > `len(data)` - this means results are PARTIAL 2. If partial, ALWAYS tell the user: "You have {total} surveys. Showing {len(data)} of {total}." 3. NEVER say "Here are your surveys" or "Here are all X surveys" when showing partial results 4. For "how many" questions, ALWAYS report the `total` field value, NOT len(data) **REQUIRED RESPONSE FORMAT when total > len(data):** ✓ "You have 35 surveys total. Here are the first 10:" ✓ "Showing 10 of 35 surveys:" ✗ "Here are your surveys:" (WRONG - doesn't indicate partial results) ✗ "Here are your 10 surveys:" (WRONG - implies this is all of them) **QUERY PARAMETER - WHEN TO USE:** The `query` parameter filters surveys by title/nickname matching. **USE query parameter WHEN user says:** find, search, look for, locate, + specific topic - "find surveys about cats" → query="cats" - "search for customer feedback" → query="customer feedback" - "look for NPS surveys" → query="NPS" - "find my satisfaction surveys" → query="satisfaction" **DO NOT use query parameter WHEN user says:** list, show, view, display, get all - "list my surveys" → NO query parameter - "show all my surveys" → NO query parameter - "what surveys do I have" → NO query parameter **DECISION RULE:** If the user mentions a TOPIC to search for, use query. If they just want to see their surveys, don't use query. Args: query: Optional search term that will match survey titles and nicknames with fuzzy matching page: Page number for pagination (default: 1, minimum: 1) per_page: Number of surveys per page (default: 10, max: 100) filters: Optional filters. Valid keys: - start_date: ISO 8601 date-time string (e.g. 2024-01-01T00:00:00Z) - end_date: ISO 8601 date-time string (e.g. 2024-12-31T23:59:59Z) - folder_id: integer folder ID - survey_state: one of "DRAFT", "OPEN", "CLOSED" sort_by: Optional sort field choose from: [ date_modified, title, nickname, survey_state, response_count ] sort_order: Optional sort order (asc/desc) Returns: Dictionary containing surveys search results and pagination info Example response: { "data": [ { "id": "123456789", "title": "Survey title 1234", "nickname": "", "survey_state": "OPEN", "folder_id": 0, "response_count": 0, "date_modified": "2026-02-12T12:00:00Z", "href": "https://api.surveymonkey.com/v3/surveys/125166945" } ], "page": 1, "per_page": 10, "total": 50 } Note: In this example, `total` (50) > `len(data)` (1), indicating 49 more surveys on subsequent pages. Error responses: - {"error": "missing_auth", "message": "Missing Authorization header"} - {"error": "invalid_auth", "message": "Invalid Authorization header format..."} - {"error": "unauthorized", "message": "Invalid or expired access token"} - HTTP 401 - {"error": "forbidden", "message": "Token lacks required scopes"} - HTTP 403 - {"error": "api_error", "message": "...", "status_code": N} - Other HTTP errors - {"error": "timeout", "message": "Request timed out"} - {"error": "service_error", "message": "Failed to connect to SurveyMonkey API"}

search_surveys

Update survey properties like title or nickname. BLOCKED when the survey has responses. **USE THIS WHEN:** User wants to rename a survey, change the survey title, or update survey properties. **TRIGGER PHRASES:** - "rename the survey to..." - "change the survey title to..." - "update the survey name..." - "call this survey..." - "set the survey nickname..." **IMPORTANT:** Call this tool directly to make the change. Do not just read information first - take action immediately when the user requests a rename or title change. Args: survey_id: The ID of the survey to update patch: Dictionary with fields to update. Common fields: - title: New survey title (string) - nickname: Optional survey nickname (string) Returns: Dictionary containing the updated survey details Example: update_survey(survey_id="123456", patch={"title": "Customer Feedback Q1 2026"})

update_survey