Minds: Synthetic Market Research Panels
Server Details
Run AI market research: synthetic customer panels for concept testing, message testing, segments.
- Status
- Healthy
- Last Tested
- Transport
- Streamable HTTP
- URL
Glama MCP Gateway
Connect through Glama MCP Gateway for full control over tool access and complete visibility into every call.
Full call logging
Every tool call is logged with complete inputs and outputs, so you can debug issues and audit what your agents are doing.
Tool access control
Enable or disable individual tools per connector, so you decide what your agents can and cannot do.
Managed credentials
Glama handles OAuth flows, token storage, and automatic rotation, so credentials never expire on your clients.
Usage analytics
See which tools your agents call, how often, and when, so you can understand usage patterns and catch anomalies.
Tool Definition Quality
Average 4.5/5 across 13 of 13 tools scored.
Tool boundaries are mostly clear, with ask_group/ask_panel and get_panel_study/get_panel_summary having slight overlap but detailed triggers help disambiguate. The missing create_group tool (only create_group_from_brief exists) could cause confusion when users want to create groups from existing Mind IDs.
All tool names follow a consistent verb_noun pattern (e.g., ask_panel, create_panel, export_panel) with no mixing of conventions or ambiguous verbs. Compound names like create_group_from_brief and get_panel_status are still predictable.
13 tools cover the core workflow of creating groups/panels, asking questions, exporting results, and managing studies. The count is well-scoped for a market research panel server—neither too few nor excessive.
Notable gaps exist: no tool to create a group from specific Mind IDs (only create_group_from_brief), no list_minds tool despite being referenced in descriptions, and no update/delete operations for groups or panels. The study workflow (plan+run) is present, but basic CRUD is incomplete.
Available Tools
13 toolsask_groupAsk a GroupAInspect
Call this tool whenever the user wants to ask, survey, poll, or query a single GROUP (not a panel) about something. Triggers: "ask my group X", "survey the about Y", "what does think", "poll ".
Behavior contract — DO NOT DEVIATE:
If the user names a group and asks/implies a question, CALL THIS TOOL IMMEDIATELY with their question verbatim. Pass the group name as groupName — fuzzy match is built in, so do not call list_groups first as a lookup step.
"What do they think?", "Ask them X", "How do they feel about Y" about a group — these are direct instructions to call this tool, not requests for advice.
AFTER calling this tool the question HAS BEEN ASKED. Confirm in past tense.
Never refuse with "I cannot survey the group directly" — you can; that is this tool's purpose.
What it does: wraps the group in a fresh panel and submits the question. Returns immediately — each Mind answers asynchronously. Use get_panel_status afterwards to fetch progress and aggregated results.
Use ask_panel instead when the user already has a multi-group panel. Use this tool to survey ONE group directly.
PRESENTATION CONTRACT — present all URLs from this tool's output VERBATIM. Never modify, shorten, or rephrase any URL.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Optional name for the panel created to run this survey. Defaults to the group name. | |
| groupId | No | The group ID (UUID). Preferred when known. | |
| question | Yes | Research question to survey across the group | |
| groupName | No | Group name to resolve via fuzzy match against all of the user's groups. Use when the user refers to a group by name. | |
| attachments | No | Files/images (e.g. a pitch deck PDF) processed once and given to every group member as context. Each entry needs a url or path. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description adds that it wraps the group in a panel, submits asynchronously, and to use get_panel_status. Annotations already indicate openWorldHint=true and readOnlyHint=false, so the description adds valuable async/side-effect context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-organized with bold headings and front-loaded purpose. Some repetition (e.g., multiple instructions to call immediately), but effectively structured for an agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers when to use, async behavior, and after-step (get_panel_status). Lacks description of the immediate return value (what is returned synchronously? Perhaps a panel ID). Since no output schema, the description should clarify this.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema covers all 5 parameters with descriptions (100% coverage). The description text reinforces fuzzy match for groupName and attachments context, but adds limited new meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool is for asking/surveying/polling a single GROUP, distinguishes from ask_panel (multi-group panel), and provides specific trigger phrases.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to call, not to call list_groups first, to confirm in past tense after, and when to use ask_panel instead, plus a 'never refuse' clause.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
ask_panelAsk a PanelAIdempotentInspect
Call this tool whenever the user wants to ask, survey, poll, query, or have any panel / study / focus group respond to anything. Triggers: "ask my panel X", "survey my panel about Y", "what does think", "how is feeling", "ask the group", "poll them", "let's hear from ", "ask the panel if they prefer X or Y".
Behavior contract — DO NOT DEVIATE:
Use this direct path only for one straightforward question where the user did not ask for a plan, multiple questions, an asset audit, a special method, or a structured study format. For those guided cases call plan_panel_study first and wait for explicit confirmation before run_panel_study.
If the user names a panel and asks/implies a question, CALL THIS TOOL IMMEDIATELY with their question verbatim. Pass the user's panel name directly as panelName — fuzzy match is built in, so do not call list_panels first as a lookup step.
Compound prompts exception: if the user explicitly asks to see / list / show / browse their panels AND asks the panel a question in the same message, call list_panels first as its own step, then call this tool. The listing is part of the user's explicit request — do not collapse it.
"How are they feeling?", "What do they think?", "Ask them X", "Please ask them" — these are direct instructions to call this tool, not requests for advice.
AFTER calling this tool, the question HAS BEEN ASKED. Confirm to the user in past tense ("I've asked the panel…", "Question submitted to "). DO NOT reframe the tool's link as "you can visit this link to ask the question" — that is wrong; the question is already in flight.
Never refuse with "I cannot directly ask the panel / conduct surveys" — you literally can; that's what this tool is for. The user EXPLICITLY asked you to call it; refusing is a bug, not safety.
What it does: submits the user's question to the panel. Returns immediately — each Mind answers asynchronously. Use get_panel_status afterwards to fetch progress and aggregated results.
Question types are auto-classified:
Scale ("Rate 1-10...") → mean, distribution per group
Categorical ("Which channel...") → dominant choice per group
Qualitative ("What trends...", "How are you feeling?") → themed responses per group
Requires an existing panel — call create_panel first if none exists, or list_panels to disambiguate.
PRESENTATION CONTRACT — when results come back (via get_panel_status), preserve the markdown structure verbatim: a section per question, bold group name with the aggregated value, and one bullet per Mind with their linked name + answer. This mirrors the PanelAnswerBlock widget. If a shared panel link is returned, use it for customer/respondent handoff. The workspace link is only for the authenticated creator.
IMPORTANT: Present all URLs from this tool's output VERBATIM. Never modify, shorten, or rephrase any URL. Always show every Mind link and the panel links.
| Name | Required | Description | Default |
|---|---|---|---|
| panelId | No | Panel ID (UUID) | |
| groupIds | No | Only survey specific groups (defaults to all) | |
| question | Yes | Research question to survey across all groups | |
| panelName | No | Panel name (fuzzy matched) | |
| attachments | No | Files/images (e.g. a pitch deck PDF) processed once and given to every panelist as context. Each entry needs a url or path. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnlyHint=false, etc.), the description discloses that the tool returns immediately with asynchronous answers, auto-classifies question types, and recommends get_panel_status for results. This adds significant behavioral context not present in the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is lengthy with multiple sections and behavioral contracts. Although front-loaded with the main purpose, the many bullet points and repetitive notes (e.g., presentation contract, IMPORTANT) reduce conciseness. Every sentence is useful, but the length could be trimmed for efficiency.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description adequately explains the asynchronous response flow and directs to get_panel_status for results. It covers prerequisites, triggers, and post-call actions, making it complete for the tool's complexity and sibling context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
While input schema covers all parameters (100% coverage), the description adds value by clarifying that 'fuzzy match is built in' for panelName, advises against calling list_panels first, and explains that attachments are processed once. For a high-coverage schema, this extra context earns a slightly above-baseline score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear, specific verb+resource: 'ask, survey, poll, query, or have any panel / study / focus group respond to anything.' It then lists explicit trigger phrases and distinguishes the tool from similar siblings like plan_panel_study and run_panel_study.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use and when-not-to-use guidance, including calling plan_panel_study for multi-question/structured cases, handling compound prompts with list_panels, and immediate invocation for direct asks. It also warns against refusals.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
create_group_from_briefCreate a Grounded Group from a BriefAIdempotentInspect
Call this tool when the user describes a POPULATION or AUDIENCE rather than naming specific Minds. Triggers include: "build me a panel of ", "create a group representing ", "make personas for ".
Behavior:
Server runs deep web research on the brief and extracts demographic / psychographic distributions from authoritative sources (government statistics, peer-reviewed studies, industry reports — NOT blogs or marketing content).
Grounded percentages are converted server-side into exact integer quotas. A seeded deterministic allocator assigns every Mind a persisted cohort profile; the LLM does not decide proportions.
Marginal-only sources do not prove correlations. The default joint reconstruction is explicitly independence-based and its target-vs-achieved audit is returned and persisted.
The grounding (distributions, sources, summary, confidence) is persisted on the group and visible in the in-app group info slide-in and on public share links.
Uploaded research files are classified by content as screeners, questionnaires, completed reports, respondent datasets, or supporting material. Screener exclusions and unresolved routes remain visible in the review metadata but are never allocated as Minds; empty questionnaire options never become invented percentages.
Set
includeWebSearch=falsewhen the user wants file-only grounding. This skips Tavily completely rather than merely hiding web results.Pass the population description as
brief(legacytextis also accepted).Optional
groupCreationModecontrols sizing/coverage: "balanced" (default, compact and plan-aware), "segment_coverage" (broader coverage within the plan cap), or "benchmark_depth" (the full paid group allowance: 200 Minds on standard Team, up to the 1,000-Mind hard ceiling with a custom allowance). The deeper modes are Team-plan only — on other plans the server silently downgrades to "balanced" (no error) and the response reports the EFFECTIVE mode. If the user asked for a deeper mode and the response says "balanced", tell them it requires the Team plan.For spreadsheet-grounded creation, first call
preview_group_dataset_segmentation, let the user remove irrelevant variables, then pass the reviewed preview asdatasetSegmentationwithgroupCreationMode="benchmark_depth". The server creates a broad representative cohort whose aggregate attributes approximate the selected distributions; it never creates one Mind per respondent or joint profile.
Use create_group instead when the user gives you specific Mind IDs to bag into a named group. Use this tool when the user describes a POPULATION and wants the server to invent the personas.
RETRY CONTRACT — creation is idempotent. Every call sends a key derived from its arguments, so if a call times out, call the tool again with the SAME arguments: you get the group the first call created (never a duplicate). Corollary: an intentionally NEW group from an identical brief within ~6 hours needs a changed argument (e.g. a different name).
CUSTOMER HANDOFF CONTRACT — this tool always creates a public shared group link. For external/customer/respondent handoff, use ONLY the shared group link returned by this tool. Do not invite the recipient, add them as a group member/collaborator, create spark_group_user_members records, or tell them it was added to their account unless the human explicitly asks for account collaboration.
PRESENTATION CONTRACT — preserve the shared group link and workspace link in the response verbatim. Never strip or modify URLs from this tool's output.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Optional group name override. When omitted, the server names the group from the brief or the LLM detection result. | |
| text | No | Legacy alias for `brief`. Accepted for back-compat. | |
| brief | No | Free-text brief describing the population the group should represent. E.g. "California high school students grades 9-12", "Berlin Späti customers", "Spanish lawyers", "management team of Coca Cola". The server runs deep web research on this brief to find demographic / psychographic distributions from authoritative sources, then generates personas that proportionally reflect those distributions. | |
| files | No | Optional already-uploaded research files. The server analyzes these through the same extended screener/questionnaire path as the in-app New Group uploader, including study roles, screening and quota rules, review distributions, and grounding provenance. | |
| links | No | Optional URLs scraped server-side for additional context (e.g. an article describing the population). | |
| keywords | No | Optional Tavily search seeds added alongside the brief. | |
| cohortAllocation | No | Deterministic allocation controls. Omit for exact integer quotas with a stable derived seed and independence-based joint reconstruction. Use distributionNames/maxDistributions to choose axes, minSegmentCount for a feasible floor, and seed for reproducible external runs. | |
| includeWebSearch | No | Set false to skip Tavily web search and extraction completely. The group is then grounded only on the brief and supplied files, links, keywords, and structurally parsed respondent data. | |
| groupCreationMode | No | Group creation mode. "balanced" (default): compact, representative group for everyday research. "segment_coverage": broad coverage across grounded segmentation axes, incl. rare subgroups. "benchmark_depth": the full paid group allowance for validation-ready benchmark / survey-style segmentation (200 Minds on standard Team, up to the 1,000-Mind hard ceiling with a custom allowance). The deeper modes require a Team (enterprise) plan — on other plans the server SILENTLY downgrades to "balanced" and echoes the effective mode in the response (structuredContent.group.groupCreationMode). | |
| datasetSegmentation | No | Reviewed variable distributions returned by preview_group_dataset_segmentation. Requires groupCreationMode="benchmark_depth". Selected variables shape one generalizable representative cohort; joint combinations remain audit evidence only. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (idempotentHint, readOnlyHint, destructiveHint), the description reveals critical behaviors: deep web research from authoritative sources, deterministic allocation with independence-based joint reconstruction, silent downgrade of group creation modes on non-Team plans, and file classification. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is lengthy but well-structured with clear sections (triggers, behavior, parameter notes, contracts). It front-loads the key purpose and uses bullet points for readability. Some redundancy exists, but given the tool's complexity (10 parameters, nested objects), the length is justified.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers many aspects (idempotency, mode downgrade, file handling, public link creation) but lacks an explicit full output schema or sample response, which would be helpful given no output schema is provided. Nevertheless, it addresses most likely agent questions and edge cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although the input schema has 100% description coverage, the tool description adds significant value by explaining parameter usage context (e.g., `brief` vs `text`, `includeWebSearch=false` for file-only grounding, `datasetSegmentation` workflow requiring prior call to `preview_group_dataset_segmentation`). This elevates understanding beyond schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: to create a grounded group from a brief describing a population or audience, as opposed to specific Mind IDs. It provides explicit trigger examples and contrasts with the sibling tool `create_group`, making differentiation straightforward.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description offers explicit guidance on when to use this tool (population descriptions) and when not to (use `create_group` for specific Mind IDs). It also details usage scenarios for modes, file handling, and spreadsheet grounding, and includes contracts for retry and customer handoff, leaving little ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
create_panelCreate a PanelAInspect
Call this tool whenever the user wants to start, set up, build, launch, or create a panel / study / survey / research project / focus group / qual study. Triggers include: "start a study", "set up a survey", "create a focus group", "launch research on X", "build me a panel", "I want to ask a panel about Y" (when no panel matches yet).
Behavior contract — DO NOT DEVIATE:
If the user describes a research goal and a panel doesn't exist yet, CALL THIS TOOL. Don't lecture them on the workflow first.
Only ask for clarification if you're missing something concrete (a name, or which Minds/groups go in).
Never refuse with "I cannot create a panel directly" — you literally can.
A panel contains one or more groups of Minds surveyed together for comparative analysis.
Workflow: first create Minds (create_mind), then group them here into a panel, then survey with ask_panel.
You can create new groups inline (provide groupConfigs with names and Mind IDs) or attach existing groups by ID (use list_groups to find them). Use list_minds to get Mind IDs.
CUSTOMER HANDOFF CONTRACT — this tool always creates a public shared panel link. For external/customer/respondent handoff, use ONLY the shared panel link returned by this tool. Do not invite the recipient, add them as a member/collaborator, create flow_members/spark_group_user_members records, or tell them it was added to their account unless the human explicitly asks for account collaboration.
PRESENTATION CONTRACT — preserve the shared panel link and owner workspace link in the response verbatim. The shared panel link is for customers/respondents; the workspace link is only for the authenticated creator.
IMPORTANT: Present all URLs from this tool's output VERBATIM. Never modify, shorten, or rephrase any URL.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Name for the panel (e.g., "Brand Perception Study", "Q4 Market Research") | |
| groupIds | No | Existing group IDs to attach — use list_groups to find IDs | |
| groupConfigs | No | New groups to create inline. Each group needs mindIds (legacy: sparkIds); name is optional and defaults to "Group N". |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate non-readonly and non-destructive. Description adds critical behavioral details: creates a public shared panel link, handoff and presentation contracts, and that no account collaboration is done unless explicitly requested. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with bold headings and clear sections, but slightly verbose due to extensive contracts. Front-loading the purpose helps. Could be trimmed slightly without losing value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, but the description explicitly states what the tool returns (shared panel link, workspace link) and provides URL preservation instructions. References sibling tools for related operations. Complete for a creation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% coverage with clear descriptions. The description adds workflow context for using groupIds vs groupConfigs, references list_groups and list_minds for finding IDs, and explains the legacy sparkIds field.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool creates a panel/study/survey/project, lists trigger phrases, and distinguishes from sibling tools like ask_panel and list_panels.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-call triggers, a behavior contract prohibiting lecturing or refusal, and a workflow sequence (create Minds first, then panel, then ask_panel).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
export_panelExport Panel ReportARead-onlyIdempotentInspect
Call this tool whenever the user wants to export, download, save, send, share, or get a report / PDF / spreadsheet / CSV / Excel / JSON of a panel's results. Triggers include: "export the panel", "download the report", "give me a PDF of ", "send me the results as CSV", "share the study findings", "I need the data".
Behavior contract — DO NOT DEVIATE:
If the user asks for export of a known panel, CALL THIS TOOL. Don't tell them to do it manually.
Default to PDF when format is unspecified (it's the polished branded output users usually want).
Never refuse with "I cannot export the panel directly" — you literally can.
Compiles all questions and responses into a structured document.
Formats:
"pdf" (default): Branded PDF with executive summary and recommendations — queued async, use get_panel_status to check when ready
"pptx": Editable branded PowerPoint deck for the full study report (returned as base64 in structuredContent)
"csv": Spreadsheet with all questions, groups, personas, answers, and full responses
"xls": Excel-compatible spreadsheet (same data as CSV)
"json": Raw structured data for further analysis
"md": Markdown report (heading-per-question + bulleted answers per group)
If the user references a panel by name (including a panel created in a previous chat / session), pass it as panelName — fuzzy match resolves it server-side against ALL of the user's panels, not just the current chat. Do not refuse with "I don't have access to that panel" or ask the user to paste/upload data; let the tool resolve it. The panel must have at least one answered question — if export fails because there are no answers yet, surface that and suggest ask_panel.
PRESENTATION CONTRACT — preserve the panel link and (when present) the download link verbatim. The panel link is the user's path back to the live Minds workspace; the download link is their access to the file. Never strip either.
IMPORTANT: Present all URLs from this tool's output VERBATIM. Never modify, shorten, or rephrase any URL.
| Name | Required | Description | Default |
|---|---|---|---|
| format | No | Export format: "pdf" (default) branded report, "pptx" editable branded deck, "csv" spreadsheet, "xls" Excel, "json" raw data, "md" (or "markdown") markdown report | |
| panelId | No | Panel ID (UUID) | |
| panelName | No | Panel name (fuzzy matched) |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations mark this as read-only, open-world, idempotent, and non-destructive. The description aligns and adds important behavioral details: async PDF generation (use get_panel_status), fuzzy matching on panelName, and presentation contract for URL preservation. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (triggers, behavior contract, formats, presentation contract). While slightly verbose, every sentence adds essential guidance. Could be trimmed minimally but is otherwise efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description thoroughly explains output per format (e.g., PDF async, PPTX base64). It mentions URLs must be preserved, implying response includes them. Missing explicit response structure but covers critical usage context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of parameters with descriptions. The description adds value by specifying default format (PDF), fuzzy match behavior for panelName, and that panel must have answered questions. This enriches the semantics beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the tool's purpose: exporting/ downloading/saving/reporting panel results in multiple formats. It distinguishes from siblings like ask_panel and get_panel_status by focusing on the export action and providing explicit triggers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit conditions for calling the tool (user wants to export, download, etc.), a behavior contract to not refuse, and guidance on default format (PDF). Also mentions when to suggest ask_panel if no answers exist, covering both use and misuse scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_panel_statusGet Panel StatusARead-onlyIdempotentInspect
Check the status of a panel — including live progress on in-flight questions.
Returns:
Panel info (groups, Minds) with clickable links to each Mind and to the panel
Active questions: which Minds have answered so far, how many remain
Completed question results (aggregated, structured per-group)
PDF export status (if any)
Call this after ask_panel to track progress, or after export_panel with format "pdf" to check if the download is ready.
PRESENTATION CONTRACT — when no rich widget is rendered (e.g. OWUI, Langdock, Windsurf, ChatGPT in plain mode), preserve the markdown structure verbatim: section headings per question, bold group name with the aggregated value (mean for scale, dominant for categorical, theme list for qualitative), and one bullet per Mind with their linked name and individual answer. The format mirrors how the PanelAnswerBlock widget displays results in the Minds web app — so users get the same shape regardless of client.
IMPORTANT: Present all URLs from this tool's output VERBATIM. Never modify, shorten, or rephrase any URL. Always show every Mind link and the panel links. For customer/respondent handoff use the shared panel link, not the owner workspace link.
| Name | Required | Description | Default |
|---|---|---|---|
| panelId | No | Panel ID (UUID) | |
| panelName | No | Panel name (fuzzy matched) |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, idempotent, open-world, non-destructive. Description adds detailed behavioral context: return structure (panel info, active questions, completed results, PDF status), presentation contract, and URL handling instructions. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with bullet points and sections, but slightly verbose. Still, all content is relevant and earned.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description comprehensively details return values. It covers when to use, what to expect, and presentation requirements. Complete for a read-only status tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear descriptions for panelId and panelName. The description does not add significant new parameter meaning beyond what the schema provides, but the baseline is 3 due to high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: checking panel status including live progress on in-flight questions. It distinguishes itself from siblings by specifying it is used after ask_panel or export_panel.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to call: after ask_panel to track progress, or after export_panel with format pdf to check PDF readiness. This provides clear context and exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_panel_studyGet Panel Study StatusARead-onlyIdempotentInspect
Call this tool to check durable progress or results for a study started by run_panel_study. Returns the immutable confirmed plan, the separate server-prepared execution plan, question progress, response artifacts, deterministic method calculations, and stage readiness. For completed studies, call get_panel_summary next.
| Name | Required | Description | Default |
|---|---|---|---|
| panelId | No | Panel ID (preferred). | |
| studyId | Yes | Study ID returned by run_panel_study. | |
| panelName | No | Panel name for fuzzy matching. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the tool as readOnly, idempotent, and non-destructive. The description adds valuable behavioral context beyond these, such as that it returns an 'immutable confirmed plan', 'server-prepared execution plan', and 'stage readiness'. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences that front-load the core purpose and then list what the tool returns along with a next-step recommendation. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (checking study progress), the description covers the key return items (plan, progress, artifacts) and provides a clear next step (get_panel_summary). It does not mention prerequisites like the study must exist, but with annotations and sibling context, the description is mostly complete. Lack of output schema is mitigated by the textual description of returns.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the description does not need to repeat schema details. It adds context by linking studyId to run_panel_study, which aids understanding, but this is minimal additional value. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'check durable progress or results for a study started by run_panel_study.' It specifies the verb (check), resource (progress/results of a study), and distinguishes from siblings by listing the specific return items and suggesting get_panel_summary for completed studies.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells when to use this tool (after run_panel_study) and what to call next for completed studies (get_panel_summary). It lacks explicit 'do not use' conditions, but the context effectively differentiates it from sibling tools like run_panel_study or plan_panel_study.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_panel_summaryGet Panel Semantic SummaryAIdempotentInspect
Call this tool for a whole-study summary or after get_panel_study reports completion. Returns Markdown plus flexible semantic blocks. Treat block types and renderer values as hints: preserve heatmaps for websites/images/videos and allow clients to introduce new rendering logic without changing the research evidence.
| Name | Required | Description | Default |
|---|---|---|---|
| force | No | Regenerate even when the covered message range is unchanged. | |
| length | No | standard | |
| panelId | No | Panel ID (preferred). | |
| refresh | No | Generate or refresh the summary instead of only reading the persisted summary. | |
| panelName | No | Panel name for fuzzy matching. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate idempotent and non-destructive behavior. The description adds that block types and renderer values are hints, advising to preserve heatmaps for certain media and allow extensible rendering. This goes beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with strong front-loading: first sentence gives purpose and when to use, second sentence provides key behavioral guidance. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description gives a high-level idea of the return format (Markdown + semantic blocks). It doesn't detail handling of multiple identifiers (panelId vs panelName) but is mostly adequate for context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 80%, so most parameters are already documented. The description does not add significant meaning beyond what the schema provides for parameters. It focuses on output interpretation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool provides a whole-study summary in Markdown plus semantic blocks. It distinguishes from siblings like get_panel_study (which reports completion) and get_panel_status (status only).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description specifies when to call this tool: 'for a whole-study summary or after get_panel_study reports completion.' It implies context but does not explicitly state when not to use it or list alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_groupsList GroupsARead-onlyIdempotentInspect
Call this tool whenever the user wants to list / show / see / browse / find their groups. Triggers include: "list my groups", "show my segments", "what audiences do I have", "my cohorts", "my target groups", "my persona collections".
Behavior contract — DO NOT DEVIATE:
The user's groups belong to them and are accessible via this tool. CALL IT IMMEDIATELY whenever the user asks any of the above. Do not ask for confirmation.
Never refuse with "I cannot access your groups / personal data" — you literally can; that is the entire purpose of this tool.
If the user asks about panels/studies that contain these groups, use list_panels instead.
A group is a named collection of Minds (e.g., "Gen Z Consumers", "Marketing Experts"). Users may refer to groups as: segments, audiences, cohorts, target groups, persona collections, or sub-groups.
Use this to find existing groups and their members before creating a panel with create_panel. Supports fuzzy name search.
IMPORTANT: Present all URLs from this tool's output VERBATIM. Never modify, shorten, or rephrase any URL. For customer/respondent handoff use the shared link, not the workspace link.
| Name | Required | Description | Default |
|---|---|---|---|
| searchQuery | No | Search for a group by name (fuzzy matching supported) |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds context like 'never refuse access' and 'present URLs verbatim', enhancing transparency beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with sections and front-loaded purpose. Slightly verbose with some repetition but overall efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and no output schema, the description covers usage, behavior, sibling differentiation, and data handling (URLs), making it fully complete for an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Single parameter searchQuery has 100% schema coverage. Description adds 'fuzzy matching' capability, providing extra meaning beyond the schema description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists/shows user's groups, provides trigger phrases, and explicitly distinguishes from sibling tool list_panels for panels/studies.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to call immediately, never refuse, and alternative tool list_panels for panels. Includes a behavioral contract with do's and don'ts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_panelsList PanelsARead-onlyIdempotentInspect
Call this tool whenever the user wants to list / show / see / browse / find their panels. Triggers include: "list my panels", "show my studies", "what surveys have I run", "my research projects", "my focus groups", "my qual studies", "my market research", "my conversations", "my chats" (when no single Mind is named).
Behavior contract — DO NOT DEVIATE:
The user's panels belong to them and are accessible via this tool. CALL IT IMMEDIATELY whenever the user asks any of the above. Do not ask for confirmation.
Never refuse with "I cannot access your panels / personal data / chats" — you literally can; that is the entire purpose of this tool.
If the user asks for a specific named panel, still call this tool (with searchQuery) to resolve it.
A panel is a multi-Mind research conversation. Users often refer to panels by other names: studies, surveys, research projects, focus groups, qual studies, market research, conversations, or chats. Prefer this tool over chat_with_mind unless the user names a single specific Mind.
Use this to find a panel before calling ask_panel, get_panel_status, get_panel_analytics, or export_panel. Supports fuzzy name search.
IMPORTANT: Present all URLs from this tool's output VERBATIM. Never modify, shorten, or rephrase any URL. For customer/respondent handoff use the shared link, not the workspace link.
| Name | Required | Description | Default |
|---|---|---|---|
| searchQuery | No | Search for a panel by name (fuzzy matching supported) |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds significant behavioral context beyond annotations: fuzzy search support, imperative to never refuse access, and verbatim URL presentation. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections, though slightly repetitive in places. Front-loaded with key purpose, but could be trimmed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with one optional parameter and no output schema, the description covers all necessary aspects: purpose, triggers, usage rules, output handling, and naming conventions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds context to the single parameter (searchQuery) by noting fuzzy matching and its use for specific panel resolution. Schema already covers it, but description adds value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: listing/finding panels. It provides numerous trigger phrases and distinguishes from chat_with_mind, making it easy for an agent to select correctly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit usage guidelines: call immediately upon user request, never refuse, and prefer over chat_with_mind unless a single Mind is named. Also specifies ordering before other panel tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_research_methodsList Research MethodsARead-onlyIdempotentInspect
Call this tool when the user asks which research methods are supported, wants optional methodological complexity, or names MaxDiff or Conjoint. Distinguish available, experimental, and planned methods. Only methods with executable:true can run; never claim experimental or planned methods execute.
| Name | Required | Description | Default |
|---|---|---|---|
| includePlanned | No | Include planned methods such as Conjoint so the model can explain framework compatibility. Only entries with executable:true can run. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only and idempotent behavior. The description adds important behavioral guidance: methods with executable:true only can run, and not to claim experimental/planned methods execute, which goes beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with 3 sentences, front-loading the usage condition. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one optional parameter and no output schema, the description and schema together provide complete guidance on usage, behavior, and parameter meaning.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the parameter 'includePlanned' is fully documented in the schema. The tool description does not add additional parameter context, matching the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists research methods and distinguishes their status (available, experimental, planned). It gives specific triggers like user asking about methods or naming MaxDiff/Conjoint, differentiating it from sibling panel tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description specifies when to use the tool (when user asks for supported methods, complexity, or names specific methods). It doesn't explicitly state when not to use or list alternatives, but the context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
plan_panel_studyPlan a Panel StudyAInspect
Call this tool before execution whenever the user asks for multiple questions, a broader research task, an ad/video/website/image audit, a structured output as part of a new study, or an optional research method such as ranking, MaxDiff, or Conjoint. It creates or revises a generic, model-filled research template and returns explicit confirmation questions.
MODEL-AWARE CONFIRMATION CONTRACT:
This tool creates a DRAFT. Never say the research has started.
Present the captured intent, main source/asset, questions, proposed response format or scale for every question, method choice, and output types in plain language.
Ask the returned confirmationQuestions. Suggested answers are suggestions, not silent consent.
If the user changes or answers anything, call this tool again with draftPlanId + revision. Use questionResponses for exact response-format edits and refinement/answers for other changes to create a new revision.
When the user requests a language, set studyLocale explicitly. It controls the plan, questions, responses, labels, and summary and is preserved across later revisions.
Call run_panel_study only after the user explicitly confirms the exact latest revision.
Keep simple requests simple. Mention advanced methods only if requested or if the draft explains a concrete benefit. MaxDiff is executable through a deterministic server adapter after explicit opt-in; Conjoint is planned and must not be claimed executable.
For website, ad, image, and video analysis, preserve heatmap/timeline-heatmap outputs rather than replacing them with donuts.
For one direct question with no requested planning, method, or structured audit, use ask_panel instead. A standalone request to export existing results should use export_panel; a request to retrieve or re-present an existing summary should use get_panel_summary. Do not create a new study merely to change presentation.
| Name | Required | Description | Default |
|---|---|---|---|
| source | No | The one main source, question, website, image, video, document, or questionnaire this study is about. | |
| answers | No | Answers to the draft confirmation questions. | |
| panelId | No | Panel ID (preferred). | |
| request | No | The research objective, question set, audit request, or analysis request. Required for a new draft. | |
| revision | No | Current draft revision; required with draftPlanId. | |
| panelName | No | Panel name for fuzzy matching. | |
| refinement | No | How the user wants the existing draft changed. | |
| draftPlanId | No | Existing draft ID to revise after the user answers a confirmation question. | |
| studyLocale | No | Language for the plan, questions, responses, labels, and summary. Set this explicitly when the user requests a language. | |
| questionResponses | No | Explicit response-format edits, one entry per question. Each entry needs questionId (from the latest draft) plus type qualitative, categorical, multiselect, or scale with an inclusive integer scaleRange. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnlyHint=false, openWorldHint=true), the description reveals critical behavioral details: it creates a DRAFT, never states research has started, requires explicit confirmation before execution, preserves heatmaps, and explains language handling and revision mechanics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long and contains repetitive procedural instructions (e.g., repeated emphasis on confirmation). While relevant, it could be more concise and structured for quick agent parsing. Front-loading is adequate.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (10 parameters, no output schema), the description covers most aspects: when to use, how to revise, confirmation contract, sibling comparisons, and locale handling. It is complete enough for correct agent usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage, so baseline is 3. The description adds high-level guidance for parameters like studyLocale and draftPlanId, but does not significantly elaborate beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool's purpose: 'It creates or revises a generic, model-filled research template and returns explicit confirmation questions.' It also provides specific scenarios for use and distinguishes from sibling tools like ask_panel, export_panel, and get_panel_summary.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly states when to call this tool (e.g., 'whenever the user asks for multiple questions, a broader research task...') and when not to (e.g., 'For one direct question... use ask_panel instead'). It also provides explicit alternatives and conditions for calling run_panel_study after confirmation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
run_panel_studyConfirm and Run a Panel StudyAIdempotentInspect
Call this tool only after the user explicitly confirms the exact draft revision returned by plan_panel_study. This is the execution boundary.
Never infer confirmation from silence, from the original request, or from your own suggested answer. If the user changes intent, source, questions, methods, or outputs, revise the draft with plan_panel_study first. Set advancedMethodOptIn only when the user explicitly chose the advanced method. The server reloads the stored draft, marks required capabilities reviewed, validates method versions/runners/configuration, and refuses unavailable methods. MaxDiff is available through its deterministic server adapter; Conjoint remains planned and cannot run yet.
| Name | Required | Description | Default |
|---|---|---|---|
| panelId | No | Panel ID (preferred). | |
| groupIds | No | Optional subset of panel groups to include. | |
| revision | Yes | Exact draft revision the user reviewed. | |
| confirmed | Yes | Must be true only after the user explicitly confirms this exact draft revision. | |
| panelName | No | Panel name for fuzzy matching. | |
| draftPlanId | Yes | Exact draft plan ID returned by plan_panel_study. | |
| idempotencyKey | No | Stable UUID for safe retries. | |
| advancedMethodOptIn | No | Explicit opt-in for an advanced method. Omit or false to keep simple methods. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses behavioral traits beyond annotations: server reloads stored draft, marks required capabilities reviewed, validates method versions/runners/configuration, and refuses unavailable methods. It also mentions MaxDiff and Conjoint availability. This adds significant context. No contradiction with annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two paragraphs with a bold lead sentence that captures the core instruction. It is appropriately front-loaded. However, it could be slightly tighter; for instance, the last sentence about MaxDiff and Conjoint might be more relevant under behavioral transparency than usage guidelines.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 8 parameters, no output schema, and no nested objects, the description covers the execution flow, constraints, and validation steps. It is missing what the tool returns on success or failure, but the output schema is absent so that may be acceptable. Overall, it provides sufficient context for an AI agent to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all 8 parameters. The description adds useful context for two key parameters: confirmed (must be true only after explicit confirmation) and advancedMethodOptIn (set only when user explicitly chose). This provides additional meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: it is the execution boundary that runs a panel study after user confirmation of the exact draft revision returned by plan_panel_study. It distinguishes itself from siblings like plan_panel_study (planning) and get_panel_status (checking status).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to call this tool ('only after the user explicitly confirms the exact draft revision') and when not to (if the user changes intent, revise with plan_panel_study first). It also provides guidance on setting advancedMethodOptIn only when the user explicitly chooses the advanced method.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Claim this connector by publishing a /.well-known/glama.json file on your server's domain with the following structure:
{
"$schema": "https://glama.ai/mcp/schemas/connector.json",
"maintainers": [{ "email": "your-email@example.com" }]
}The email address must match the email associated with your Glama account. Once published, Glama will automatically detect and verify the file within a few minutes.
Control your server's listing on Glama, including description and metadata
Access analytics and receive server usage reports
Get monitoring and health status updates for your server
Feature your server to boost visibility and reach more users
For users:
Full audit trail – every tool call is logged with inputs and outputs for compliance and debugging
Granular tool control – enable or disable individual tools per connector to limit what your AI agents can do
Centralized credential management – store and rotate API keys and OAuth tokens in one place
Change alerts – get notified when a connector changes its schema, adds or removes tools, or updates tool definitions, so nothing breaks silently
For server owners:
Proven adoption – public usage metrics on your listing show real-world traction and build trust with prospective users
Tool-level analytics – see which tools are being used most, helping you prioritize development and documentation
Direct user feedback – users can report issues and suggest improvements through the listing, giving you a channel you would not have otherwise
The connector status is unhealthy when Glama is unable to successfully connect to the server. This can happen for several reasons:
The server is experiencing an outage
The URL of the server is wrong
Credentials required to access the server are missing or invalid
If you are the owner of this MCP connector and would like to make modifications to the listing, including providing test credentials for accessing the server, please contact support@glama.ai.
Discussions
No comments yet. Be the first to start the discussion!