QUESTIONSTAR

Get Survey Structure

get_survey

Read-onlyIdempotent

Returns the survey structure for a survey code: questions with their variable names (Q1, Q2.3 for a checkbox option, Q), question texts, types and answer options with numeric codes, plus the page layout: each question carries page (1-based) and pageTitle, and pages lists every page in order (number, title, questionCount, isEnd, marksComplete) INCLUDING pages that are still empty. logic lists the survey's stored rules in the authoring vocabulary — display rules (target question, show|hide, match, conditions) and jumps (source question, operator, value, target page number or 'end') — audit them before adding new ones; logic.errors lists BROKEN rules (their source question/option or target page was deleted) — each needs the user's decision: delete the rule block or redefine it. languages lists the survey's default language and every configure_survey_language layer (code, own name, direction, isDefault, translated/fallback key counts). archived:true means the survey sits in the recoverable bin (it is hidden from list_surveys; the user restores it in the app). Use the variable names to interpret responses and address answers when creating or updating a result case; use the page layout to place questions (add_question's page) and to plan branching (a branching source must sit on an earlier page than its targets). This structure is also the key to interpreting raw responses from list_survey_responses when you run your own analysis. shareURL is the canonical link respondents open and previewURL opens the survey in test mode (nothing is stored) - these are the canonical survey URLs; a survey URL assembled from other parts is not a supported link.

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": {
      "code": "<code>"
    },
    "name": "get_survey"
  }
}

Input Schema

Name	Required	Description	Default
`code`	Yes	Survey publication code — the 8-character code from the survey's public link (e.g. 1a2b3c4d), as returned by list_surveys. A survey ID (the GUID 'ID' from list_surveys) is accepted too and is resolved to that survey's code.

Output Schema

Name	Required	Description	Default
`id`	No
`code`	No
`name`	No
`logic`	No
`pages`	No
`archived`	No
`metaType`	No
`shareURL`	No
`languages`	No
`questions`	No
`deleteDate`	No
`previewURL`	No
`surveyState`	No
`creationDate`	No
`lastChangedDate`	No

Schema Changelog

Changes observed during successful MCP inspections.

First observedOct 17, 2026

TDQS

A4.4/5.0

Behavior5/5

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantial non-obvious behavior: pages list INCLUDES empty pages, logic.errors flags rules broken by deleted sources/targets and requires a user decision, archived:true means the survey is hidden from list_surveys and only restorable in-app, and assembled URLs are not supported links. This is context an agent cannot get from structured fields.

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?

The opening clause front-loads the purpose and every clause carries concrete information with no filler, but the entire body is one dense paragraph covering five distinct concerns (structure, pages, logic, languages, archived, URLs) that would scan far better as sections or bullets.

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?

Despite an output schema existing (so return values needn't be explained), the description still enumerates the fields an agent must reason over and ties them to downstream tools (add_question, list_survey_responses). For a single-parameter read tool with full annotation coverage, nothing needed to invoke or use it correctly is missing.

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

Parameters3/5

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

Schema description coverage is 100% and the single 'code' parameter is fully documented in the schema (including ID-to-code resolution). The description adds no parameter-level detail beyond what the schema provides, so the baseline of 3 applies.

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 ('Returns the survey structure for a survey code') and enumerates the exact contents (questions/variable names, page layout, logic, languages, archived flag, share/preview URLs). An agent can distinguish this from list_surveys and list_survey_responses immediately.

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

Usage Guidelines4/5

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

Gives concrete usage contexts and routes to siblings: use variable names to interpret responses and address answers when creating/updating a result case, use page layout to place questions via add_question's page and to plan branching, and audit logic before adding new rules. It names alternatives (list_surveys, list_survey_responses, add_question) but stops short of an explicit 'do not use this when...' exclusion.

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

All QUESTIONSTAR 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?