Wigolo vs Minds: Synthetic Market Research Panels

create_panel

Call this tool only when the user wants a new panel, study, survey, research project, or focus group. A panel contains one or more Groups of Minds. Attach existing Groups with groupIds, or create Groups inline with groupConfigs. Composite creation is handled by one canonical v1 operation so partial group failures are rolled back. SHARING CONTRACT — panels are private by default. Pass isLinkSharingEnabled: true only when the user explicitly requests a public/shareable link. Enabling it also publishes attached Groups and Minds. IMPORTANT: Preserve returned shared and workspace URLs verbatim.

ask_panel

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

export_panel

Call this tool whenever the user wants to export, download, save, or get a report of a panel's results. The v1 API is the single export implementation for UI and MCP. Supported report kinds are executive_brief, full_report, and raw_data. Supported formats are PDF, DOCX, PPTX, Markdown, CSV, and XLS. PDF is the default. CSV/XLS default to raw_data; other formats default to full_report. PDF exports are asynchronous and return a job ID. Use get_panel_status to poll. Other formats return the generated artifact inline. IMPORTANT: Preserve the panel link and any returned download link verbatim.

export_mind

**Call this tool whenever the user wants to export, download, save, or get a persona profile / report / PDF / Word doc for a single Mind (AI expert, consumer persona, or digital twin).** Triggers include: "export <mind>", "download the persona profile", "give me a PDF of <mind>", "send me <mind> as a Word doc", "profile sheet for <mind>". Behavior contract — DO NOT DEVIATE: - If the user asks to export a known Mind, CALL THIS TOOL. Don't tell them to do it manually. - Never refuse with "I cannot export the Mind directly" — you can. - Default to "md" (markdown) when format is unspecified; it returns the full profile inline. Generates a branded persona profile summarizing who the Mind is, how it thinks, and what it draws on, from the Mind's own data. Formats: - "md" (default): markdown persona profile, returned inline as text - "pdf": portrait branded profile (returned as base64 in structuredContent) - "docx": Word document (returned as base64 in structuredContent) - "pptx": editable branded PowerPoint deck (returned as base64 in structuredContent) If the user references a Mind by name (including one created in a previous chat / session), pass it as mindName — fuzzy match resolves it server-side against ALL of the user's Minds. Do not refuse with "I don't have access to that Mind"; let the tool resolve it. PRESENTATION CONTRACT — present any returned link to the Mind VERBATIM. Never modify, shorten, or rephrase a URL.

export_group

Export a group brief through the same unified branded renderer used by the web app. Supports Markdown, PDF, DOCX, and PPTX. Binary artifacts are returned as base64.

export_heatmap

Export a completed website heatmap from a panel message. Returns the same ZIP archive as the web app, including its unified-renderer PDF report, Markdown, images, and metadata.

list_panels

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

get_panel_status

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.

list_groups

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

create_group_from_brief

**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" (two representatives per limiting grounded audience cell, from a 10-Mind evidence floor up to its 50-Mind mode ceiling), or "benchmark_depth" (five representatives per limiting grounded cell for comparison-ready depth, with the paid allowance as its ceiling). 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.

ask_group

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

plan_panel_study

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