QuestionPunk

Question Create Bulk

question_create_bulk

Add several questions after the existing ones, in one call; the usual way to fill a new survey. Scales: opinion_scale itemDetails { min_value: 0 or 1 (default 1), max_value: 5 to 10 (default 10), nps: true for a 0 to 10 Net Promoter Score }, end labels in textItemDetails { min_value_label, max_value_label }; rating itemDetails { scale: 5 to 11 (default 5) }, end labels in textItemDetails { min_label, max_label }. Find a time polls (itemDetails.find_a_time, find_a_time_zone) can't be created or re-zoned here: add them in the QuestionPunk editor. Each choice question requires textItemDetails.answer_options as an array of option strings. itemDetails holds non-translatable behavior settings, as in question_create (see it for AI interview and other types). You write the questions; this tool generates nothing. To insert at a position use question_create. The result returns surveyVersion for your next edit. Questions are written one by one: if one fails, the earlier ones stay saved, so read the survey with survey_get before retrying, or you will create duplicates.

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>",
      "surveyVersion": "<surveyVersion>",
      "lang": "<lang>",
      "items": "<items>"
    },
    "name": "question_create_bulk"
  }
}

Input Schema

Name	Required	Description
`lang`	Yes	Language code of the text you write; one of the survey's languages (survey_get), usually its primary one
`items`	Yes	Array of questions to create
`surveyId`	Yes	Survey ID (from survey_list)
`surveyVersion`	Yes	Current survey version (versions.current from survey_get or survey_create). This tool reads the latest version itself before writing; the result returns the next one as surveyVersion.
`fillInterviewItems`	No	Has no effect here. To give an AI interview earlier answers as context, set its itemDetails.reference_questions.

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedNov 7, 2026

TDQS

A4.7/5.0

Behavior5/5

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

Annotations only declare the safety profile (not read-only, not idempotent, open-world), but the description adds the critical non-atomic write behavior: questions are written one by one, earlier ones stay saved on failure, and retrying without re-reading survey_get creates duplicates. It also notes the tool re-reads the latest version itself and returns the next surveyVersion, plus that it generates no content.

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

Conciseness3/5

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

The purpose and the sibling distinction are front-loaded well, but the middle collapses into a dense run-on catalog of per-type detail joined by semicolons, which is hard to scan. The partial-failure warning, arguably the most important sentence, is buried at the very end rather than near the top.

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 bulk mutation with a large enum of answer types, the description covers placement, atomicity, versioning, type-specific itemDetails, and where to go when the tool cannot do the job. With an output schema present it need not explain return values, and versioning is already addressed.

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 goes beyond it by documenting scale constraints (opinion_scale min/max defaults, nps 0-10, rating 5-11) and end-label fields in textItemDetails that the schema does not describe. It also clarifies that itemDetails holds non-translatable behavior settings and that choice types require answer_options.

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?

The description opens with a specific verb, resource, and placement scope: 'Add several questions after the existing ones, in one call.' It explicitly distinguishes itself from question_create ('To insert at a position use question_create'), so an agent can route between the two without reading either schema.

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?

It names the preferred context ('the usual way to fill a new survey'), the alternative for positional inserts (question_create), and a hard exclusion ('Find a time polls ... can't be created or re-zoned here: add them in the QuestionPunk editor'). It also points to question_create for AI interview and other types it does not elaborate.

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?