Minds: Synthetic Market Research Panels MCP Server

**Call this tool only when the user wants a NEW panel / study / survey / research project / focus group, or when no suitable panel exists yet.** Triggers include: "start a new study", "set up a new survey", "create a focus group", "launch new research on X", "build me a panel". Behavior contract — DO NOT DEVIATE: - The agent decides from the conversation whether the user wants a new panel or wants to continue an existing one. This tool is the explicit NEW-panel branch. - NEVER call this tool for a follow-up to a panel just created, selected, or asked. Follow-up cues include "ask them", "also", "and which...", "what about...", "another question", and pronouns referring to the current audience. Use ask_panel for one direct follow-up or plan_panel_study for a broader/multi-question follow-up; both can reuse the active panel when panelId/panelName is omitted. - If the user describes a research goal and no suitable panel exists 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. SHARING CONTRACT — panels are PRIVATE by default. No public link is created unless the caller passes `isLinkSharingEnabled: true`, which you should do only when the user explicitly asked for a shareable/public link. Enabling it also publishes every attached group and every Mind inside them, so never enable it to "be helpful". CUSTOMER HANDOFF CONTRACT — applies only when link sharing was enabled. In that case, 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 any shared panel link and the owner workspace link in the response verbatim. A 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.

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.

**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.

**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.

**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. Treat list_research_methods and server validation as the availability authority; execute only methods reported with executable:true.

**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 <name> X", "survey the <group> about Y", "what does <group> think", "poll <group>". 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.

**Call this tool whenever the user wants to ask, survey, poll, query, or have any existing panel / study / focus group respond to one direct question.** Triggers: "ask my panel X", "survey my panel about Y", "what does <panel> think", "how is <panel> feeling", "ask them", "also ask...", "what about...", "poll the group". 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. - Follow-ups belong to the existing panel. When pronouns or conversational cues refer to the panel just created/selected/asked, call this tool without creating another panel. Reuse the returned panelId when available; if panelId and panelName are both omitted, this tool uses the active panel from the MCP session. - 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 <panel>"). 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 only if none exists, or list_panels when the intended panel is genuinely ambiguous. 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.

**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 <panel>", "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. - "Export it/the results/the study" is a follow-up on the active panel. Reuse the returned panelId when available; if panelId and panelName are omitted, this tool uses the active panel from the MCP session. Do not create a new panel to export existing results. - 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.

**Call this tool when the user describes a POPULATION or AUDIENCE rather than naming specific Minds.** Triggers include: "build me a panel of <demographic>", "create a group representing <segment>", "make personas for <audience>". 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, only if link sharing was explicitly enabled, on the public share link. - 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=false` when the user wants file-only grounding. This skips Exa completely rather than merely hiding web results. - Pass the population description as `brief` (legacy `text` is also accepted). - Optional `groupCreationMode` controls 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 as `datasetSegmentation` with `groupCreationMode="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`). SHARING CONTRACT — groups are PRIVATE by default. No public link is created unless the caller passes `isLinkSharingEnabled: true`, which you should do only when the user explicitly asked for a shareable/public link. Note that the persisted grounding (distributions, sources, summary) becomes publicly readable too, so never enable it to "be helpful". CUSTOMER HANDOFF CONTRACT — applies only when link sharing was enabled. In that case, 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 any shared group link and the workspace link in the response verbatim. Never strip or modify URLs from this tool's output.

**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.

**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.

**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. When this is a broader follow-up about the panel just created, selected, or asked, keep using that panel. Reuse its panelId when available; if panelId and panelName are omitted, the active panel from the MCP session is used. Do not call create_panel merely because the follow-up needs a research plan. 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. Check list_research_methods for current availability and execute only methods whose returned contract says executable:true; never hard-code a method's availability in the conversation. - 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.

**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.

**Call this tool to create or checkpoint an unfinished Quick or Custom Study plan without starting research.** It saves the objective, context, selected Audiences, method, questions, and sources in the same durable planning state used by the Minds sidebar. To revise an existing draft, pass its exact draftId and expectedRevision from list_study_drafts; stale revisions are rejected by the API. This tool never creates a panel and never starts a Study.

**Call this tool when the user asks to resume, find, list, or inspect unfinished study plans.** Omit draftId to list all durable study drafts. Pass an exact draftId to retrieve the complete saved planning state for one draft. Drafts are distinct from existing panels and completed or running studies; do not claim a draft has started.