Skip to main content
Glama

read_responses

Read-onlyIdempotent

Read response schema, counts, paginated rows, the export's column privacy catalog, exported survey JSON, or flow SVG for a survey. Rows require confirm: true and accept the Export tab's privacy presets and per-column Drop / Mask / Redact PII choices. The Export tab's named multi-filter views are browser-local and cannot be selected here: use review_decision for server-side review filtering, or page through rows and apply the same AND/OR predicates locally so pagination is not mistaken for the complete survey.

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": {
      "survey_id": "<survey_id>"
    },
    "name": "read_responses"
  }
}

Input Schema

NameRequiredDescriptionDefault
limitNoMax responses when include contains rows (default: 50, max: 200)
cursorNoPagination cursor for rows (response ID from previous call)
confirmNoRequired when include contains rows — ask the survey owner for explicit permission before fetching respondent answers, every call, not just once per session.
includeNoWhat to return. rows requires confirm: true. columns lists every export column's key, sensitivity (identifier, free_text, demographic, device) and what each privacy preset does to it — no response data, so no confirm needed; use it to find the keys for dropped_column_keys / anonymized_question_ids. survey_json is the same versioned Domandata survey document the editor's Export → JSON writes (every block, question, option, and Flow setting, plus survey settings such as unfinished-response handling, the closed link, retention, and export privacy; API keys blanked; close date omitted), and imports back losslessly.
survey_idYesSurvey UUID
privacy_presetNoRows only. Starts from one of the Export tab's "Who is this file for?" presets: as_collected (Just Me), no_direct_identifiers (My Research Team), redacted (Reviewers or Collaborators), public_use (The Public), answers_only (Answers Only). The other privacy options can only add protection on top of it. public_use's rare-combination suppression is not applied here (rows are paginated) — use /api/v1/export or GitHub Sync for that.
review_decisionNoServer-side filter for quality_review.decision. Named multi-filter views in the Export tab are stored in that browser, not on the survey, so they cannot be selected by MCP. For other predicates, page through rows and filter locally; do not treat one page as the full response set.
coarsened_columnsNoRows only. Broaden columns, keyed by column key: number ranges, month/year dates, 3-digit ZIP codes, or rare answers grouped. group_rare needs counts across all responses, so on paginated row reads those columns come back "withheld" — use /api/v1/export or GitHub Sync for it.
use_saved_privacyNoRows only. Start from the survey's saved Export tab privacy choices (see include: ["columns"] → saved_privacy), so rows match what the Export tab would download; the other privacy options add protection on top. The team's export privacy minimum (columns → team_minimum) always applies to rows, with or without this.
pii_redaction_modeNoRows only. Redacts email/phone/SSN-shaped text inside Text Response and Text Chat answers. unintentional leaves a question's own intended answer alone (e.g. an email-validated question); all redacts every match. Default off.
dropped_column_keysNoRows only. Column keys left out entirely: a question id removes that question's answer; a "col:<header>" key removes that flow/JS variable or metadata field. Find keys with include: ["columns"].
redacted_question_idsNoRows only. Limits pii_redaction_mode to these free-text questions (the Export tab's per-column Redact PII). Omit to redact every Text Response / Text Chat answer when pii_redaction_mode is set.
scan_names_and_placesNoRows only. Also redacts people's names, places and organizations found in free-text answers. Default false.
anonymized_question_idsNoRows only. Column keys whose values are masked: a question id replaces that answer with the literal string "anonymized"; a non-question "col:<header>" key (see include: ["columns"]) is removed from the raw row, since raw rows have no column to mask in place.
pseudonymized_column_keysNoRows only. Column keys whose value is replaced by a coded ID (P-XXXXXXXXXXXX): the same original value gets the same code in every export of every survey in the team, so waves still link, and the code can't be reversed outside Domandata. For panel/respondent ID variables and identifying single-answer questions.
include_identifying_questionsNoRows only. false removes Text Response, signature, file upload, audio and chat answers entirely (default true, as typed).

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.8/5.0
Behavior5/5

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

Beyond the readOnly/idempotent annotations, it discloses that rows require confirm: true with owner permission on every call, that the team export privacy minimum always applies, that pseudonymization codes are stable across surveys in the team and non-reversible, and that group_rare columns come back 'withheld' on paginated reads. These are non-obvious operational traits an agent could not infer from the schema alone.

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 the set of returnable artifacts, then constraints and escape hatches. Dense but nearly every clause carries operational information. Minor redundancy: the browser-local multi-filter limitation is restated in both the top-level description and the review_decision parameter description.

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 16-parameter, nested-schema, multi-mode tool, the description covers mode selection, safety gating, privacy layering, known limitations of pagination, and where alternative endpoints are needed. With an output schema present it correctly omits return-value shape and focuses on behavior.

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 baseline would be 3, but the description adds cross-parameter meaning the schema states only per-field: which parameters are 'rows only', that additional privacy options layer on top of a preset or saved_privacy, and how dropped_column_keys/anonymized_question_ids map to question ids vs 'col:<header>' keys. It stops short of full interaction detail (e.g. precedence between use_saved_privacy and privacy_preset beyond 'add protection on top').

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?

Opens with a specific verb and enumerates exactly what can be returned (response schema, counts, paginated rows, column privacy catalog, survey JSON, flow SVG) for a named resource, a survey. An agent can tell this is the export-oriented read tool rather than a survey metadata read like read_survey.

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?

Explicitly states an exclusion ('Export tab's named multi-filter views are browser-local and cannot be selected here') and names the substitute (review_decision, or page-and-filter-locally). It also routes agents to /api/v1/export or GitHub Sync for public_use suppression and group_rare, and points at include:["columns"] to discover keys. When/when-not guidance is fully specified.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources