Skip to main content
Glama

Minds: Synthetic Market Research Panels

by ai.getminds

Ask One Standalone Question in a Study

ask_study
Idempotent

Submits exactly ONE respondent-visible question in an existing Study. Applicability: one standalone question, or one adaptive follow-up whose wording could not be known before earlier results. Exclusion: never use this operation for a questionnaire, survey, battery, section, cohesive question set, or any request containing two or more known questions—even when every question targets the same Study. The complete known set belongs in one planned and confirmed multi-question block inside the Study and must be submitted once, not question by question. Follow-up questions remain within the existing Study; this operation does not create or enumerate Studies. The full question value may reach respondents and is not planner-only metadata. Scale, categorical, and qualitative questions are classified automatically, and the response includes status and workspace links. The question is classified before it is queued, so the returned status is authoritative: queued or running means it was submitted to respondents, while planning_required means it was declined as an unrefined research objective and nothing was submitted. A planning_required response carries the original request plus a proposed headline and respondent questions for study planning. MCP cannot read or upload a local file:// path. Use a fetchable HTTP(S) URL, a signed URL supplied by the client for the attached file, or an existing Minds workspace upload URL/path. Study tools import external file URLs into durable Minds storage before saving or running. The Study refuses to start if Minds cannot read the asset.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
linksNoWeb pages given to every Mind as evidence for this question through v1 /studies/{studyId}/runs.
modelNoOptional per-request model override. Must be sent together with provider.
panelIdNoStudy ID (UUID; legacy wire field name: panelId). Omit both panelId and panelName only when continuing the active Study from this MCP session.
studyIdNoStudy ID (UUID). Omit with studyName to continue the active Study from this MCP session.
groupIdsNoLegacy alias for audienceIds. Accepted for compatibility.
keywordsNoSearch keywords used to gather evidence for this question through v1 /studies/{studyId}/runs.
providerNoProvider for the model override. Must be sent together with model.
questionYesExactly ONE respondent-visible standalone question or result-dependent adaptive follow-up for every selected Mind. Never concatenate, enumerate, or otherwise place a questionnaire, survey, battery, section, cohesive question set, or two or more known questions in this field. The system may classify or reformat it, but any text here can reach the Minds and influence their answers. Include only the single question, its necessary stimulus, and respondent-facing instructions. Never place planner-only or MCP-client orchestration instructions here.
panelNameNoStudy name (fuzzy matched; legacy wire field name: panelName). Omit both panelName and panelId only when continuing the active Study from this MCP session.
studyNameNoStudy name (fuzzy matched). Omit with studyId to continue the active Study from this MCP session.
attachmentsNoFiles/images processed once and given to every participating Mind. MCP cannot read or upload a local file:// path. Use a fetchable HTTP(S) URL, a signed URL supplied by the client for the attached file, or an existing Minds workspace upload URL/path. Study tools import external file URLs into durable Minds storage before saving or running. The Study refuses to start if Minds cannot read the asset.
audienceIdsNoOptional subset of the Study's Audiences to ask; defaults to all Audiences.
historyModeNoControls prior Study-history carryover for this one direct question. Defaults to none, so this measurement is independent of earlier Study questions. last5 is only for a conversational/adaptive question that requires respondent continuity; it costs roughly 2.4x wall-clock for about 0.6pp of accuracy. followup_only carries history only when the submitted question is classified as a conversational follow-up.
sourcePolicyNoUse knowledge_only to forbid web/request sources and require every answer to be grounded in processed Mind knowledge.

TDQS

A4.2/5.0
Behavior4/5

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

Annotations already establish safety (readOnlyHint=false, idempotentHint=true, not destructive), so the description correctly carries the heavier behavioral burden: it discloses that the question value reaches respondents and is 'not planner-only metadata,' explains pre-queue classification, and defines the authoritative statuses — 'queued or running means it was submitted... planning_required means it was declined.' It also documents file-URL constraints and the Study's refusal to start on unreadable assets. No contradiction with annotations; the description adds meaningful operational context beyond them.

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?

Rich but verbose; the tool description runs roughly 200 words for a genuinely complex operation, and the file-URL constraint messaging is repeated across the main description and multiple schema field descriptions ('MCP cannot read or upload a local file:// path... Study tools import external file URLs into durable Minds storage'). It is front-loaded with purpose and exclusions, which is good, but tighter editing would remove redundancy without losing information.

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

Completeness4/5

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

Despite having no output schema, the description compensates by explaining response status semantics (queued/running vs planning_required) and what a planning_required response carries. For a 14-parameter tool with 3 enums and complex behavioral rules (single-question constraint, classification, URL handling, study-refusal condition), the description is thorough. Only a fuller return-value description would push it to 5.

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%, so the baseline is 3 and the schema does the heavy lifting for all 14 parameters. The description reinforces the single-question constraint for the question field and adds the planning_required response context, but it doesn't add syntax or format details beyond what the schema already documents — appropriate given full coverage.

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 precise verb-resource pair — 'Submits exactly ONE respondent-visible question in an existing Study' — and immediately differentiates from siblings by excluding questionnaires, surveys, batteries, sections, and multi-question sets, while explicitly noting 'this operation does not create or enumerate Studies.' An agent can distinguish this from run_study_questions, create_study, and plan_study_questions without opening their schemas.

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 explicit applicability ('one standalone question, or one adaptive follow-up whose wording could not be known before earlier results') and explicit exclusions ('never use this operation for a questionnaire, survey, battery, section, cohesive question set, or any request containing two or more known questions'). It even routes the agent to the correct alternative: the known set 'belongs in one planned and confirmed multi-question block inside the Study and must be submitted once, not question by question.'

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

All Minds: Synthetic Market Research Panels toolsInspect
Try in Browser
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

A3.9/5.0
Disambiguation3/5

The tool set has three distinct get_panel_* tools and two draft-saving tools (plan_panel_study, save_study_draft) that could be confused, but the detailed descriptions clarify their specific scopes. Most other tools (list, create, export, ask) target clearly different resources or actions.

Naming Consistency5/5

All tool names follow a consistent verb_noun scheme in snake_case (list_, get_, create_, ask_, export_, plan_, run_, save_). Verb choice maps predictably to the operation, making the set easy to navigate.

Tool Count4/5

At 18 tools, the set is slightly above the ideal 3-15 range but well-scoped for a comprehensive research-panel platform. Each tool addresses a distinct part of the workflow, from group/panel creation to study planning, execution, and export.

Completeness4/5

The surface covers the full research lifecycle: create groups/panels, ask questions, monitor status, export artifacts, and plan/run multi-question studies. It lacks update/delete operations for groups and panels, but these are minor gaps that agents can work around for typical research flows.

Resources