Skip to main content
Glama
Sign In

QuestionPunk

by io.github.questionpunk
OverviewDiscussionsAdmin

Question Create

question_create

Add one question at a position in a 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. Choice labels belong in item.textItemDetails.answer_options as an array of strings; item.itemDetails holds behavior settings such as multiple_selection. Example single choice: {"text":"How easy was setup?","answer_type":"multiple_choice","required":true,"textItemDetails":{"answer_options":["Easy","Difficult"]}}.

Call survey_get first for versions.current (pass it as surveyVersion) and the question count; to add at the end, surveyItemIndex = that count. The result returns the next surveyVersion for your next edit. To add several questions at the end, use question_create_bulk (one call). You write the question text; this tool generates nothing. On a published survey the new question is live at once.

For AI interviews use answer_type 'ai_moderated_interview': it supersedes ai_interview and ai_audio_interview. Set itemDetails.modality to 'text' (default) or 'voice'; put interviewGoal, greetingInstruction and avoidTopics in item.textItemDetails; its other settings match the two older types below.

For a numbered scale use answer_type 'opinion_scale'; a 0 to 10 scale needs itemDetails { min_value: 0, max_value: 10 }. itemDetails { nps: true } also labels the ends "Not at all likely" and "Extremely likely" in English.

Older AI Interview questions (answer_type: 'ai_interview') take:

  • itemDetails.length: Number of exchanges (default: 5, used in fixed_count mode)

  • itemDetails.reference_questions: Array of UUIDs of PREVIOUS questions. The AI interviewer will see the respondent's answers to these questions and use them as context.

  • itemDetails.personality: { kind: 'preset', code: 'expert_interviewer' | 'friendly_interviewer' | 'focus_group_moderator' | 'researcher' | 'detective' | 'stubborn_interrogator' | 'comedian' } or { kind: 'custom', id: '' }

  • itemDetails.thinkingMode: 'fast' (default) or 'slow' for deeper reasoning

  • itemDetails.questionMode: 'fixed_count' (default) | 'ai_decides' | 'time_based'

  • itemDetails.aiDecidesConfig: { minQuestions: number, maxQuestions: number, stoppingGuidance?: string } (for ai_decides mode)

  • itemDetails.durationMinutes: number (for time_based mode, default: 10)

  • itemDetails.advancedSettings: { temperature?: number, maxTokens?: number, enableFollowUpProbing?: boolean, responseStyle?: 'concise'|'detailed'|'conversational' }

  • itemDetails.aiModel: { type: 'direct', model: '' } (optional; the app picks a default)

  • itemDetails.showContinueButton: boolean (show start button before interview, default: false)

  • itemDetails.aiFailureBehavior: 'complete_survey' (default) | 'pause_survey' | 'skip_to_next' | 'skip_question'

  • itemDetails.endOnStopRequest: boolean (when the respondent clearly asks to stop, the interviewer asks once whether to end or keep going and a clear yes ends the interview, default: true; false = it runs to its configured length)

Older AI Audio Interview questions (answer_type: 'ai_audio_interview') take:

  • itemDetails.timeoutMs: Session timeout in ms (default: 300000)

  • itemDetails.recordingMode: 'none' | 'audio' | 'video'

  • itemDetails.sessionConfig: { type, sttModel, ttsModel } voice pipeline config

  • itemDetails.promptMode: 'standard' (default) | 'custom'

  • itemDetails.showContinueButton: boolean (default: false)

  • itemDetails.greetingInstruction: string (initial greeting text)

  • itemDetails.interviewGoal: string (goal for the AI interviewer)

  • itemDetails.avoidTopics: string (topics to avoid)

For usability tests (answer_type: 'usability_test'), the question starts with one empty website task, screen share required and voice moderation. Describe tasks in itemDetails.guidedTask.tasks[] ({ id, order, scenario, targetType: 'website' | 'prototype' | 'native_app' | 'none', ... }); fetch the question with survey_get and edit it with question_update. A Figma prototype task uses targetType 'prototype', its Figma presentation link (https://www.figma.com/proto/..., kept unchanged with its query parameters) as targetUrl, and an optional figmaPrototype { startNodeId?: 'n:m', goalNodeIds?: ['n:m', ...] (at most 10) } naming the start screen and goal screens by Figma node id; goal screens are observations in recorded sessions, never automatic task completion.

Signature, file_upload, photo_response and consent questions get working defaults; for consent, set item.textItemDetails.statement and agree_label.

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>",
      "surveyItemIndex": "<surveyItemIndex>",
      "item": "<item>"
    },
    "name": "question_create"
  }
}

Input Schema

NameRequiredDescriptionDefault
itemYes
langYesLanguage code of the text you write; one of the survey's languages (survey_get), usually its primary one
surveyIdYesSurvey ID (from survey_list)
surveyVersionYesCurrent survey version: versions.current from survey_get, or the surveyVersion your last edit returned. A stale version is rejected (WRONG_VERSION). The result returns the next one as surveyVersion.
surveyItemIndexYes0-based position to insert the question. Use the current question count to add it at the end.
surveyItemGroupIdNoOptional group ID to create question inside

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.5/5.0
Behavior4/5

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

Annotations only say it is a non-destructive, non-idempotent, open-world write. The description adds real behavior: stale versions are rejected with WRONG_VERSION, the call returns the next surveyVersion, a question added to a published survey goes live immediately, and the tool generates no content itself. It does not discuss permissions or error cases beyond WRONG_VERSION, so it stops short of a 5.

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

Conciseness2/5

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

The core instruction is front-loaded, but the body is a sprawling reference manual: the older ai_interview and ai_audio_interview option lists are extremely long, and several points (scale ranges, answer_options placement) are restated in multiple paragraphs. Much of the enumeration duplicates what the schema and its descriptions already say.

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 tool with a nested item object, 5 required parameters and an output schema, the description covers the workflow, the versioning contract, and the type-specific configuration that an agent could not infer. Nothing needed 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.

Parameters5/5

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

Schema coverage is already high (83%), yet the description still clarifies semantic grouping that the schema cannot convey — which settings go in item.itemDetails versus item.textItemDetails, how answer_options holds choice labels, and worked examples for opinion_scale, rating, NPS, AI interview variants and usability tasks. This materially reduces misuse of the nested objects.

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 resource: "Add one question at a position in a survey." It distinguishes itself from the sibling question_create_bulk (for several questions) and defers task editing to question_update, so an agent can route correctly without opening a 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?

Gives an explicit prerequisite workflow (call survey_get for versions.current and the question count), a concrete appending rule (surveyItemIndex = current count), and named alternatives for batching and usability-test task editing. It also states an exclusion: find-a-time polls cannot be created here.

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

All QuestionPunk toolsInspect
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