QuestionPunk

Responses Read

responses_read

Read-onlyIdempotent

Read survey responses as JSON so YOUR model can analyze, summarize or code them itself (no QuestionPunk AI credits are used). Returns { survey, questions: [{id, index, label, text, answer_type}], conditions?: [{key, label, arms}], responses: [{id, status, startedAt, completedAt, responseType, language, conditions?: {: arm}, answers: {: answer}}], page: {limit, cursor, nextCursor, total} }. conditions appears only when the survey randomly assigns respondents to A/B arms (e.g. two wordings of a question): the top-level list names each condition and its arms, and each response's conditions gives the arm it was in per key (null if none was assigned; a value not in arms is an arm renamed or removed since). To compare arms, group responses by that value. No other URL parameters are returned. Answers are rendered exactly as in the CSV export (choice labels by default; matrix = list of "Row: value"; AI interviews = list of {question, answer} turns); unanswered questions are omitted and answers over 4,000 characters are truncated with a marker. Page through with cursor = the previous page.nextCursor until it is null (up to 200 responses per page, default 50; a page may end early to stay small). To code one open-text question across many responses, pass questionIds: [thatQuestionId] (only responses that answered it are returned). For counts only, use responses_get_counts instead.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "surveyId": "<surveyId>"
    },
    "name": "responses_read"
  }
}

Input Schema

Name	Required	Description
`limit`	No	Responses per page (default 50, max 200)
`cursor`	No	page.nextCursor from the previous call; omit for the first page
`status`	No	completed, abandoned (left before the end) or in_progress. Omit for all.
`dateEnd`	No	Only responses started at/before this time, as Unix milliseconds (13 digits)
`surveyId`	Yes	Survey ID (from survey_list)
`dateStart`	No	Only responses started at/after this time, as Unix milliseconds (13 digits; 2025-01-01T00:00Z is 1735689600000)
`questionIds`	No	Only these questions (and only responses that answered at least one of them). Omit for every question.
`studyWaveId`	No	Only responses from this diary-study wave
`answerFormat`	No	Choice answers as labels (default), 1-based numbers, or both
`responseType`	No	Real respondents or synthetic (AI) responses. Omit for both.
`suspiciousLevel`	No	Fraud-check filter. 'clean' excludes suspicious responses; 'flagged' is high + medium.
`surveyRevisionId`	No	Only responses collected on this published revision

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedNov 7, 2026

TDQS

A4.4/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile needs no restating. The description nonetheless adds substantial behavior beyond them: truncation at 4,000 characters, omission of unanswered questions, early page termination, and the meaning of arms/conditions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose and return shape, then filters and paging, then the sibling pointer. Dense but nearly every clause carries information; the conditions/arms explanation is the longest block and could be tightened slightly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 12-parameter read tool with an output schema, the description covers return shape, filtering semantics, paging, truncation edge cases and the alternative tool. Nothing an agent needs to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning: how cursor values are produced, that questionIds returns only respondents who answered, and exactly how answers are rendered (labels, "Row: value" for matrix, interview turns). Enum values such as answerFormat and suspiciousLevel are largely left to the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ("Read survey responses as JSON") plus a differentiating rationale ("so YOUR model can analyze, summarize or code them itself"). It immediately separates itself from sibling tools like responses_get_counts and implies a raw-data role versus responses_list/response_get_details.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit alternative and the condition that selects it ("For counts only, use responses_get_counts instead") and a specific workflow trigger for the questionIds parameter ("To code one open-text question across many responses"). Pagination mechanics are spelled out ("cursor = the previous page.nextCursor until it is null").

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All QuestionPunk tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?