---
title: "Minds MCP Tools Reference | Minds"
canonical_url: "https://getminds.ai/mcp/tools"
last_updated: "2026-09-30T10:59:21.328Z"
meta:
  description: "Reference for Minds MCP tools that create Audiences, plan cohesive multi-question Studies, run research, summarize evidence, and export reports."
  "og:description": "Reference for Minds MCP tools that create Audiences, plan cohesive multi-question Studies, run research, summarize evidence, and export reports."
  "og:title": "Minds MCP Tools Reference | Minds"
  "twitter:description": "Reference for Minds MCP tools that create Audiences, plan cohesive multi-question Studies, run research, summarize evidence, and export reports."
  "twitter:title": "Minds MCP Tools Reference | Minds"
---

Minds

Minds Team # **Minds MCP Tools Reference** Reference for Minds MCP tools that create Audiences, plan cohesive multi-question Studies, run research, summarize evidence, and export reports. Tool availability depends on deployment configuration: ordinary discovery exposes 23 tools, or 24 when `list_model_connections` is enabled, with 42 or 43 canonical tools registered respectively. Treat the connected server’s `tools/list` response as authoritative. The [Minds MCP server](https://getminds.ai/mcp/overview) advertises 23–24 curated tools through ordinary `tools/list` discovery and registers 42–43 canonical tools in total. The product model is deliberately small: an **Audience** is a reusable collection of Minds, while a **Study** is the research workspace that contains one or more Audiences, questions, evidence, results, and exports. Compatibility names containing `group` or `panel` remain callable, but new integrations must use the Audience and Study names documented here. The **Advertised** label below means ordinary clients discover the tool automatically. **Explicit** means the canonical tool is registered and callable by integrations that can configure or invoke a known tool name, but it is omitted from the curated discovery surface. Read the [agent operating guide](https://getminds.ai/mcp/agents) before autonomous use. MCP returns a public Study or Audience link only when the API reports `isPublic: true` or `isLinkSharingEnabled: true` and supplies a share ID. A retained share ID after revocation is not an active link. Use returned URLs exactly as provided. Name-based lookup searches at most the newest 1,000 visible Minds, Audiences or Studies. For an older record, browse the corresponding list tool with `limit` and `offset`, then pass its exact ID. Incomplete or malformed list responses return an error rather than claiming that no matching record exists. ## Curated advertised surface | Domain | Tools |
| --- | --- | | Minds | `export_mind` | | Audiences | `list_audiences`, `import_audience_sources`, `get_audience_limits`, `create_audience_from_brief`, `ask_audience`, `export_audience`, `duplicate_audience` | | Studies | `list_studies`, `list_model_connections`, `create_study`, `ask_study`, `get_study_status`, `export_study`, `duplicate_study`, `export_heatmap`, `study_heatmap` | | Guided research | `plan_study_questions`, `run_study_questions`, `get_study_run`, `list_research_methods`, `list_study_drafts`, `save_study_draft`, `list_study_templates`, `manage_study_template`, `get_study_summary` | ## Minds & Audiences ### list_minds Browse Minds owned by the authenticated user one page at a time. Preserve `nextOffset` to continue; `searchQuery` returns the best fuzzy match among the newest 1,000 Minds.**Parameters:**- `searchQuery` (optional): Best fuzzy name match among the newest 1,000 Minds - `limit` (optional): Page size, default 20, maximum 100 - `offset` (optional): Entries to skip, default 0; use the previous result’s `nextOffset`**Example:**```
"List my AI minds about marketing"
```### create_mind Create a new Mind — a synthetic expert, consumer persona, or digital twin.**Parameters:**- `name` (required): Name of the Mind - `mode` (required): Training mode — `keywords`, `clone`, `link`, or `manual`- `type` (optional): Type — `creative`, `expert`, or `user` (default: `expert`) - `discipline` (optional): Area of expertise - `keywords` (optional): Topics for training (required for `keywords` mode) - `personaContext` (optional): Person to model (required for `clone` mode) - `contextLink` (optional): URL to train from (required for `link` mode) - `description` (optional): What this Mind specializes in - `includeWebSearch` (optional): Set `false` to skip automatic web research; use `manual` for a strictly source-only Mind - `idempotencyKey` (optional UUID): Choose one key before creating and reuse it with the same inputs for retries, including after timeouts. Use a fresh key for another Mind. The result returns the operation key in `structuredContent.idempotencyKey`. Without an explicit key, only identical calls within 10 seconds in the same server process are coalesced; cross-process or later retries need the returned key. | Mode | Description | Required Fields |
| --- | --- | --- | | `keywords` | Train from topic keywords | `keywords` | | `clone` | Create a digital twin of a person | `personaContext` | | `link` | Train from website content | `contextLink` | | `manual` | Manual configuration | None | ### chat_with_mind Send one message to a Mind and get its response. Use `mindId` for an exact selection or `mindName` for the best fuzzy match among the newest 1,000 Minds. Browse `list_minds` by offset to find older Minds and pass their exact IDs. Use `manage_chat` for a persistent multi-turn conversation.**Parameters:**- `mindId` (optional): Mind UUID (use this OR `mindName`) - `mindName` (optional): Name with fuzzy matching (e.g., "my marketing expert") - `message` (required): Message to send - `sourcePolicy` (optional): `auto` or `knowledge_only`- `modelConnection` (optional): Verified caller-team connection ID and revision ### get_mind_status Check training progress after creating a Mind.**Parameters:**- `mindId` (required): Mind UUID ### export_mind Export a Mind profile. This tool is **Advertised**.**Parameters:**- `mindId` or `mindName`: Exact UUID or the best fuzzy name match among the newest 1,000 Minds; use an exact UUID for older Minds - `format` (optional): `md`/ `markdown` (default, returned inline), `pdf`, `docx`, or `pptx` The tool polls asynchronous generation internally. A successful result includes `filename`, `mimeType`, and either inline Markdown `content` or binary `contentBase64`, plus the Mind’s workspace link. Preserve these fields when saving the export. ### list_audiences List visible Audiences one page at a time. Preserve `nextOffset` to continue; `searchQuery` returns the best fuzzy match within the newest 1,000 entries.**Parameters:**- `searchQuery` (optional): Filter by name using fuzzy search - `limit` (optional): Page size, default 20, maximum 100 - `offset` (optional): Number of entries to skip, default 0 - `includeMinds` (optional): Include member Minds, default `false`### create_audience Create a reusable Audience from existing Minds.**Parameters:**- `name` (required): Audience name (e.g., "Marketing Experts") - `mindIds` (required): Mind IDs to add — use `list_minds` to find IDs ### import_audience_sources Results are private and non-cacheable. The tool verifies the returned file count/order, source policy, snapshot checksum and distribution references before reporting success. Keep the returned snapshot unchanged for preview or creation. Missing or foreign files are input errors; storage outages return `502` without provider details. Retry the same import after a storage failure or an invalid acknowledgement: content-addressed uploads preserve existing files. The MCP HTTP request body is limited to 24 MiB, including JSON escaping and protocol fields; oversized requests return HTTP `413` with a JSON-RPC error. Source-import file and total-content limits still apply separately. Import supplied UTF-8 `.txt`, `.md`, `.csv`, or `.json` sources using `files: [{ name, content }]`. Optional `existingFiles` and `groundingJson` preserve reviewed source context. This advertised tool creates no Audience and does not independently verify supplied distributions. ### get_audience_limits The tool validates account/team provenance, numeric ceilings and a complete, unique set of creation modes before reporting limits. A zero per-Audience cap is a workspace lock, not missing data. Responses are private and non-cacheable. Blocked credentials are revalidated; an unavailable entitlement lookup returns `503` without inventing a free-plan allowance. Read this account’s Audience size and creation-mode limits before choosing a size. Optional `mode` filters the result. Distinguish the automatic sizing ceiling from the explicit-count ceiling. This tool is advertised. ### create_audience_from_brief Create a grounded synthetic audience from a population brief, source links, keywords, and research files. This tool is **Advertised** and private by default. Important parameters include: - `brief` (preferred) or legacy `text`: Population description - `name`: Audience name - `links`, `keywords`, `files`: Research context - `includeWebSearch`: Set `false` for file-only grounding - `memberCount`: Requested cohort size, subject to plan allowance - `audienceCreationMode`: `balanced`, `segment_coverage`, or `benchmark_depth`- `datasetSegmentation`: Reviewed output from `preview_audience_dataset_segmentation`- `cohortAllocation`: Deterministic marginal/joint allocation configuration - `isLinkSharingEnabled`: Enable only after an explicit request for a public link Identical arguments are idempotent for approximately six hours. After a timeout, retry the same arguments to recover the original Audience. Deeper creation modes are Team-plan workflows; inspect the effective mode returned by the server rather than assuming the request was accepted unchanged. While creation runs, every open workspace for the authenticated owner is notified through the user-scoped lifecycle stream and re-reads the same durable creation state. The UI therefore displays the same Drafting, Creating, and Ready states for UI, REST, and MCP creation. Repeating identical arguments reuses that lifecycle instead of duplicating the Audience. Use `groundingPreview: true` to review profiles and source findings before creation. Return `reviewedGroundingJson` and `reviewedGroundingSha256` unchanged with the same inputs and `memberCount` to create the accepted composition. If the tool returns a pending `structuredContent.operation`, call `create_audience_from_brief` again with only `operationId` set to its `jobId`. This resumes the existing operation without creating or charging for a second Audience. Completed results contain `structuredContent.preview` or `structuredContent.audience`. A created Audience is usable within seconds while its web research continues in the background. The structured `research` field on the created Audience says so (`phase: "researching"`), and `readiness.research` reports it when an operation is read back. Studies can run right away: sourced evidence replaces the Audience's stated assumptions automatically, and its Minds are recalibrated between runs, never during one. See [two-phase creation](https://getminds.ai/docs/api/audiences). ### preview_audience_dataset_segmentation Preview requests accept at most 256 KiB of JSON. Responses, including refusals, are private and non-cacheable. Invalid JSON or fields return `400`, an oversized request or dataset returns `413`, and Team eligibility or upload-access refusals return `403`. Entitlement lookup failures return `503`; unexpected download, classifier or analysis failures return a generic `500`. Omitting `segmentationColumns` selects the default population and segmentation variables, not every non-identifier field. MCP validates the complete aggregate response and reconciles row totals, selected variables and reported discovery counts before describing the analysis. Undeclared fields are omitted. Older responses without relationship or dependency counts are described as unreported, not zero. This is a review of the source dataset: it does not create a cohort or verify its eventual allocation. Authorized Minds uploads are read through their storage-access checks. Every network fallback, including a URL on the Minds host, uses the public-URL guard and validates redirect destinations; same-origin URLs do not bypass private-network protection. Downloads retain a 50 MiB streaming limit and a 30-second timeout. Failed HTTP responses are cancelled before an error is returned. Inspect a CSV, XLS, or XLSX respondent dataset before representative cohort creation. This is an **Explicit** Enterprise workflow.**Parameters:**- `file.name`: Original spreadsheet filename - `file.url`: Public, signed, or Minds workspace-upload URL - `segmentationColumns` (optional): Reviewed column keys from a previous preview The tool classifies file content, uses all completed respondent rows, identifies structural versus held-out variables, and recommends a representative Mind count. It never creates one Mind per respondent. Screeners and questionnaire programming grids are rejected as respondent data and should be passed directly to `create_audience_from_brief`. ### get_audience Read an Audience's members, grounding, source metadata, sharing state, and Formations. This is an **Explicit** tool.**Parameters:** pass `audienceId` or `audienceName`. Name lookup is fuzzy, so do not call `list_audiences` first solely to resolve a natural user reference. The result shows the Audience's coverage counts (`sourced`, `proxy`, `assumed`, `missing` dimensions) and its background research state (`research`). ### ask_audience Ask one existing Audience a direct research question. This tool is **Advertised**. It creates a private one-Audience Study, submits the question, and returns immediately; poll `get_study_status` for results.**Parameters:**- `audienceId` or `audienceName`- `question` (required) - `name` (optional): Internal Study name - `attachments` (optional): Reusable file/image context with a `url` or storage `path` Use `ask_study` when the user already has a multi-Audience Study. Each `ask_audience` call creates a new private wrapper Study. ### recalibrate_audience Refresh and replace an Audience's stored grounding from authoritative web research, then re-allocate the members' cohort profiles to match the refreshed distributions — the same distributions-to-members logic the drafting flow uses. The instruction's reach decides how deeply members change, covering demographic, psychographic, behavioral, and firmographic amendments alike: composition or evidence edits ("make men 40%", "add an income distribution") touch only members whose allocation cell actually changed; trait changes ("now they're all vegan", "SMB owners instead of enterprise buyers") make members evolve in place — same Mind, same name and portrait, rewritten role and description, knowledge retrained; population pivots ("now African consumers") rebuild every member in place — same Mind, new persona and portrait, knowledge wiped and retrained — so studies, shares, and chat history keep working while the Minds genuinely become the new audience. No Minds are deleted; retraining runs asynchronously and the Audience shows build progress until it finishes. An additive instruction ("and now add 10 African consumers") grows the roster instead: new members are generated for the added audience within the plan's member limits. While the research runs the Audience reports a **Calibrating…** state in the app and via `get_audience`. This is an **Explicit** tool and owner-only.**Parameters:** `audienceId` or `audienceName`, plus optional `instruction` for a user adjustment on top of the original brief (for example "add an income distribution"), or `query` only when the user wants to steer research away from the original brief entirely. Pass `deepen: { topics? }` to go deeper: the tool researches every standard dimension the coverage reports as missing or assumed, plus up to 8 given topics (each up to 120 characters), adds the findings to the saved grounding (stronger evidence replaces weaker for the same dimension; every other chart stays) and recalibrates the members. `deepen` cannot be combined with `query` or distributions, and is refused while the Audience's background research is still running. ### validate_audience Check an Audience against real, published surveys: the tool finds surveys whose respondents best match the Audience, asks its Minds the same questions, and scores how close their answers are to the published answers. This is an **Explicit** tool: it is registered and callable by name for MCP clients that call tools directly, but it is not yet listed in assistants' tool discovery. The same capability is available now through the v1 API and the Audience's Validation tab. It writes, and it may search the web for fitting surveys.**Parameters:**- `audienceId` or `audienceName`: Exact UUID or fuzzy-matched Audience name - `action` (optional): `start` (default) or `cancel`- `benchmarkIds` (optional): 1–5 listed surveys to validate against; without them, the best-fitting published surveys are found - `batchId`: The validation to stop; required for `cancel`- `idempotencyKey` (optional UUID): Reuse the same key when retrying a start, so the retry returns the same validation instead of starting another The result gives the batch ID and status, says whether the run uses an included validation or synthetic responses, and tells the assistant to poll `get_audience_validation`. The Audience needs at least 10 ready Minds. A run usually takes 10 to 60 minutes and can be cancelled before any survey is asked. See [Audience validation in the API](https://getminds.ai/docs/api/audiences) for costs, limits, and failure codes. ### get_audience_validation Read an Audience's validations. This is an **Explicit**, read-only tool, callable by name but not yet listed in assistants' tool discovery; the same results are available through the v1 API and the Audience's Validation tab.**Parameters:**- `audienceId` or `audienceName`- `batchId` (optional): One validation to read With `batchId`, the result gives the status, progress, the combined score and its 95% range when available, each survey with its score, range, who it asked relative to the Audience, and its source, and which questions were left out and why. Without `batchId`, it gives the Audience's overall validity, its latest validation, the included validations left this month, and ready Minds against the minimum. A score of 100 means the Minds' answers match the published answer shares exactly. Report each survey's score, its range when available, and who the survey asked, rather than the combined score alone. An unstated survey respondent count leaves the point comparison usable but makes its sampling uncertainty unavailable. Affected question and headline ranges, noise-floor estimates and KPI intervals are `null`, including on older saved results. A combined or overall score still includes every eligible point comparison; its range is `null` when any contributor lacks a range. Preserve that distinction in the answer: report the score and the source caveat, and do not invent a range, treat `null` as zero, or recalculate precision from a legacy assumed `n: 100`. A reported 95% range is a model-based uncertainty estimate, not proof of representativeness or coverage of every survey-design effect. ### list_formations On the first page (`offset: 0`), recovery checks at most 100 pending builds, oldest first. One failed attempt does not stop attempts for the other selected builds or prevent the list from being returned. Check build status and reopen the first page to retry pending work.`list_formations` and `manage_formation` with `action: "list"` accept optional `limit` and `offset`. Each call returns one page, with a default/maximum of 100. Follow `pagination.nextOffset` while `hasMore` is true. For `list_formations`, `totalCount` is the full visible total, not the number shown. An empty page beyond the end does not mean the Audience has no Formations. Malformed continuation metadata produces a tool error. The app and Study widget collect all summary pages before publishing a complete list; a failed continuation does not become a partial breakdown. You can list Formations on any Audience you can view, including shared Formations and your own private ones. MCP rejects malformed lists or missing membership counts instead of reporting an empty list or zero members. Counts are final only for `ready` Formations; `building` and `failed` counts are provisional. An empty first page with `total: 0` means no Formations are visible to you; opening it seeds defaults only for Audience editors. The v1 list response is private and non-cacheable, including refusals. Unexpected access-lookup, seeding or list-storage failures return a generic `500`. List persisted Formations for an Audience. This is an **Explicit** tool. Pass `audienceId` or `audienceName`. ### export_audience Export an Audience brief through the canonical v1 API and unified branded renderer. This tool is **Advertised**.**Parameters:**- `audienceId` or `audienceName`: Exact UUID or fuzzy-matched Audience name - `format` (optional): `md`/ `markdown` (default), `pdf`, `docx`, or `pptx`- `force` (optional): Regenerate instead of returning a cached artifact The tool polls the original export job and returns success only when a complete artifact is available. Preserve `filename`, `mimeType`, and Markdown `content` or binary `contentBase64`. Inline Markdown is capped at 100,000 characters and marked `_[truncated]_` when shortened. Cancellation stops polling; an unfinished export is an error, so check again without `force=true`. ### duplicate_audience Copy an Audience through `POST /api/v1/audiences/{audienceId}/duplicate`. This tool is **Advertised**.**Parameters:**- `audienceId`: Audience to duplicate; you must be able to edit it - `name` (optional): Name of the copy; defaults to `<name> (copy)`- `idempotencyKey` (optional): Reuse the key a failed or timed-out call returned, so a retry cannot create a second copy Returns the new Audience in `data`, its `audienceUrl` and the `idempotencyKey`. Every member Mind is copied as a new, independent Mind with its knowledge and embeddings, together with the Audience's grounding, sources, Formations and finished validations. The copied Minds count toward the plan's Mind allowance. An Audience that is still being built is refused; retry once it is ready. ## Studies (Multi-Mind Research) ### list_model_connections List active model connections for the authenticated team. A listed connection is not necessarily verified: inspect its capability flags and `verifiedAt` before selecting it. Pass `pagination.nextCursor` as the next request’s `cursor`. Only declared connection metadata and capability fields are returned; provider credentials, raw probes and undeclared diagnostics are omitted. Malformed responses or non-advancing cursors are errors. Unexpected discovery storage failures return a generic `500`. The tool is advertised only when model connections are enabled on the connected server. ### create_study Create a Study workspace and attach one or more existing or inline Audiences.**Parameters:**- `name` (required): Study name - `audienceConfigs` (optional): New Audiences to create inline — each with `name` and `mindIds`- `audienceIds` (optional): Existing Audience IDs to attach**Example:**```
"Create a Study called 'Brand Perception Study' with two Audiences:
 - 'Marketing Experts' containing my SEO and Content Marketing minds
 - 'Consumer Insights' containing my Gen Z and Millennial minds"
```### ask_study Submit exactly one standalone research question to all selected Audiences in a Study. Treat the entire `question` value as respondent-visible input. The system may classify or reformat it, but any text in this field can reach the selected Minds and influence their answers. Put only the question, stimulus, and respondent-facing instructions here. For a questionnaire, survey, battery, section, cohesive question set, or any request with two or more known questions, use `plan_study_questions` once with the complete set—never call `ask_study` question by question.**Parameters:**- `studyId` (optional): Study UUID - `studyName` (optional): Study name (fuzzy matched) - `question` (required): Research question - `audienceIds` (optional): Only query specific Audiences ### list_studies List Studies with their Audience composition and question counts, one page at a time. Preserve `nextOffset` to continue; `searchQuery` returns the best fuzzy match within the newest 1,000 entries.**Parameters:**- `searchQuery` (optional): Filter by name using fuzzy search - `limit` (optional): Page size, default 20, maximum 100 - `offset` (optional): Number of entries to skip, default 0 ### get_study_status`questionId` limits individual-answer reads and returned results to that question; the tool still reads the Study transcript metadata. Run status reads follow all relevant cursor pages. A failed or incomplete run-list read returns a tool error instead of successful partial status. Get detailed Study information including in-progress questions, completed results, and export status.**Parameters:**- `studyId` (optional): Study UUID - `studyName` (optional): Study name (fuzzy matched) - `questionId` (optional): Return one question's results - `exportKind`, `exportFormat`, `exportJobId` (optional): Use the exact kind, format and job ID returned by `export_study` to inspect that artifact A question that `askIf` skipped for every Mind reports `status: "not_asked"`. It is settled, not failed or pending. Report queued, running, failed and partial work as such. A polling timeout does not authorize a new submission. ### get_study_analytics Compute statistical analytics across a Study's question history.**Returns:**- **Scale questions**: Mean, median, standard deviation, consensus, Audience rankings - **Categorical questions**: Distribution, dominant category, cross-Audience divergence - **Qualitative questions**: Theme clustering, shared themes, diversity index**Parameters:**- `studyId` (optional): Study UUID - `studyName` (optional): Study name (fuzzy matched) ### export_study Export Study results as a report.**Parameters:**- `studyId` (optional): Study UUID - `studyName` (optional): Study name (fuzzy matched) - `format` (optional): `pdf` (default), `docx`, `pptx`, `csv`, `xls`, `sav`, `md`, or `markdown`- `kind` (optional): `executive_brief`, `full_report` (default), or `raw_data`- `length` (optional): `brief`, `standard`, or `detailed`- `force` (optional): Regenerate instead of returning a cached artifact | Format | Description |
| --- | --- | | `pdf` | Branded PDF report | | `docx` | Editable Word report | | `pptx` | Editable presentation | | `csv` | CSV workbook export | | `xls` | Excel workbook export | | `sav` | SPSS raw-data export | | `md` / `markdown` | Markdown report | ### duplicate_study Copy a Study through `POST /api/v1/studies/{studyId}/duplicate`. This tool is **Advertised**.**Parameters:**- `studyId`: Study to duplicate; you must be able to open it - `name` (optional): Name of the copy; defaults to `<name> (copy)`- `idempotencyKey` (optional): Reuse the key a failed or timed-out call returned, so a retry cannot create a second copy Returns the new Study in `data`, its `workspaceUrl` and the `idempotencyKey`. The copy keeps every question, answer, chart, heatmap, summary and finished run over the same Audiences; a schedule is copied paused. Audiences are referenced, not copied; use `duplicate_audience` to copy them. A Study with a live run is refused. ### study_heatmap Read or start an asset heatmap with `studyId` or `studyName`, `messageId`, and `action: "get"` (default) or `"start"`. Optional `assetKey` selects an image/video assigned to that question. Starting analysis requires Premium and consumes one response per Mind; completed analysis is reused. This tool is advertised. ### export_heatmap Export a completed website heatmap as the same ZIP archive available in the web app. The archive includes a unified-renderer PDF report, Markdown, source images, and metadata. This tool is **Advertised**.**Parameters:**- `studyId` or `studyName`: Study identifier - `messageId` (required): Completed Study message containing the website heatmap - `force` (optional): Regenerate instead of returning the cached archive ## Guided Research Planning ### plan_study_questions Create or revise one durable, versioned research-plan draft. Use it for every broader objective, questionnaire, survey, battery, section, cohesive question set, visual-asset analysis, structured research output, or named method. Put every question already known into one `request`; the planner may organize them into named modules or sections, but the agent must never create one plan or run per question. Do not use it for a standalone export or a request to show existing results differently; use `export_study` or `get_study_summary` for those requests. The free-form `request` is planner input and is not sent verbatim to Minds. The tool returns one cohesive plan with the exact proposed respondent-visible question text, named modules when useful, captured intent, main source, methods, semantic outputs, and explicit `confirmationQuestions`. The assistant must present the complete draft and those questions—including any framing warning—and must not claim the research has started. If the user changes anything, call the tool again with `draftPlanId` and `revision`. Items are answered in order: each Mind sees its own earlier answers in the run (never another Mind's answers or any aggregate), so an item may build on an earlier one. Plan the order as you would for a fielded survey. For skip logic, give an item in `questions` (or in `draft.edits.questions`) an `askIf` condition instead of "if not, answer N/A" wording: - `questionId`: ID of an earlier `categorical` or `multiselect` item in the same plan - `answerIn`: ask only Minds whose own answer includes any of these options - `answerNotIn`: ask only Minds whose own answer includes none of these options Give exactly one of `answerIn` or `answerNotIn`, using the earlier item's option labels exactly. A condition naming an unknown or later item, an item that is not a choice question, or an option that item does not offer is rejected before the draft is saved. Minds that are not asked are recorded as not asked and excluded from that item's results. See [skip logic with askIf](https://getminds.ai/docs/api/studies) for the full rules. ### run_study_questions Confirm and run the exact latest draft revision only after explicit user confirmation. Advanced methods require `advancedMethodOptIn: true`. The catalog includes executable Conjoint, MaxDiff, NPS, top/bottom box, key drivers, TURF, Gabor-Granger, Van Westendorp, Kano, ranked preferences, and segment comparison. Check `list_research_methods` for `executable: true` and the required configuration before promising a method. Items are answered in order, as one respondent would: every Mind answers an item in parallel, and each Mind sees its own earlier answers in this run, never another Mind's. An item may build on an earlier one and order effects can arise as in a fielded survey; to control them, rotate item order across separate runs when the design calls for it. Items with `askIf` are asked only of Minds whose own earlier answer matched. After the run, answers that contradict the same Mind's other answers are flagged for review and never changed. If the Study-answer allowance is already exhausted, the tool returns a structured `plan_limited` error and the study does not start. Tell the user plainly that an upgrade is required; do not describe the survey as queued or completed. ### get_study_run Read durable status, question progress, the immutable confirmed plan, the separate server-prepared execution plan, the exact respondent-visible question audit, method stages, response artifacts, and deterministic method calculations for a study started by `run_study_questions`. A routed item's response artifact carries `routing` with `askedCount`, `notAskedCount` and `notAskedMindIds`. Its answers, counts and percentages cover only the Minds that were asked. An item that no Mind was asked settles as an artifact with `kind: "not_asked"`: finished, not failed. Report a routed item's base as the asked Minds, and do not describe not-asked Minds as missing answers. After the run finishes, `answerConsistency` summarizes the per-Mind contradiction check: `status` (`checked`, `incomplete` or `failed`), `checkedMinds`, `flaggedMinds`, `flagCount`, `uncheckedMinds` and, when some flags could not be saved, `unsavedItems`. Flagged artifacts carry `answerConsistency.flags` with `mindId`, `withItem` and `reason`. The check runs after the summary is written, so it can appear on a later poll after `completed`. Present flags as items to review; the answers themselves are unchanged.`plan_limited` means an in-progress survey stopped before all questions completed. Preserve its partial artifacts, state how many questions completed, and tell the user to upgrade before starting a follow-up run for the remainder. ### list_research_methods`preparesQuestionsAtExecution: true` means the method derives deterministic questions and response contracts from its configuration at execution; saved template questions are not the complete executed instrument. Invalid catalog responses are errors, not an empty catalog. `includePlanned: false` excludes planned methods but still shows experimental methods with their non-executable status. List versioned methods with `executable`, availability, complexity, configuration requirements, semantic outputs, and fallbacks. Use this when the user explicitly asks for MaxDiff, NPS, Kano, TURF, pricing methods, Conjoint, or methodological options. A represented method is not necessarily runnable; only `executable: true` is an execution promise. Keep the default workflow simple when users do not ask for methodological complexity. The catalog entries `visual-asset-analysis` and `recommendation-synthesis` remain experimental and cannot execute as those named planner methods. Their `fallbackMethodId` identifies an alternative to review, not permission to silently substitute it. Image/video/website research and asset heatmaps have separate supported paths; use `study_heatmap` for an asset already assigned to a Study question. A non-executable planner entry does not mean MCP cannot analyze visual assets. ### list_study_drafts List active Study drafts or retrieve the complete saved planning state by `draftId`. A `draft` can be resumed from its saved step and revision; `starting` means launch is already in progress. An exact-ID read can return a `consumed` tombstone, which cannot be resumed. Invalid or incomplete API responses are errors, not an empty list or proof of a successful save. ### save_study_draft For creation, choose an optional `idempotencyKey` (1–200 characters after trimming) before the first request and reuse it after an uncertain result. Reusing the key returns the existing saved draft rather than applying new planning inputs. Omit it when updating: use `draftId` and the current `expectedRevision` instead. Without a key, repeated creation requests can create separate drafts. Create or revise a durable Study planning draft without starting research. A revision requires the exact `draftId` and `expectedRevision`; the tool saves a closed set of planning inputs into the same versioned Custom planner state used by the Minds sidebar. The backing v1 endpoints return private, non-cacheable responses. Create/update JSON requests are limited to 1 MiB, with a separate 512 KiB cap on the versioned `payload`; consume requests are limited to 4 KiB. Invalid input returns `400`, oversized input `413`, and unexpected storage failures a generic `500`. An unchanged snapshot preserves `revision` and `updatedAt`. Check saved state before retrying an uncertain save; a save itself does not start research. ### get_study_summary Retrieve the persisted semantic summary, or refresh it when `refresh: true`. Blocks are flexible evidence descriptors rather than fixed UI components. Preserve heatmap outputs for website, image, ad, and video analysis. ### list_study_templates The response must contain complete template identities, revisions, permissions and valid configurations. An exact `templateId` read must return that same template. Missing, malformed or mismatched responses are errors; only a valid empty list means no templates were returned. List owned and team-shared Study templates, or supply `templateId` to read one template including its current revision and stored configuration. This tool is **Advertised**. Reading a template does not launch research. ### manage_study_template The v1 template endpoints return private, non-cacheable responses. Save/update JSON bodies are limited to 1 MiB, and use bodies to 4 KiB (`413` above the limit); the saved configuration remains limited to 512 KiB. Malformed JSON or invalid input returns `400`. Expected ownership, revision and asset refusals retain their documented status; unexpected storage/provider failures return a generic `500`. The tool validates each write acknowledgement before reporting success: save/update must return the expected complete template, delete must return `success: true`, and use must return a Study draft. A retried use may return an existing `starting` or `consumed` draft; it is not described as a newly editable draft. If the acknowledgement is incomplete, inspect saved templates or drafts before retrying, and preserve the original request ID. Save, update, use or delete a Custom Study template. This tool is **Advertised**. Set `action` to `save`, `update`, `use` or `delete`; non-save actions require `templateId`. Provide the matching `save`, `update` or `use` object for that action. Only owners can update, delete or change team sharing. Use the current revision for updates and use. Preserve `save.requestId` for retry-safe creation; `use.requestId` must be a fresh UUID for each intended draft and reused only for a retry of that same request. `use` creates an independent editable draft to finish in the web app; it never starts research. Audiences and context are entered fresh. Review changes and confirm destructive actions before executing them. ## Explicit lifecycle tools These seven registered canonical tools expose the remaining v1 research lifecycle. They are intentionally omitted from the 23–24-tool curated discovery list until their product presentation is reviewed. An integration that calls one explicitly must supply the canonical schema and honor destructive/confirmation annotations. ### manage_mind For `regenerate_image`, pass `force: true` to replace an existing portrait; otherwise a Mind that already has an image is skipped. Optional `personaContext` (1–16,000 characters after trimming) steers the portrait without changing the system prompt. Missing or invalid API acknowledgement envelopes produce an error with advice to inspect current state before retrying. A returned request does not establish completion of background training, images, knowledge ingestion or segmentation; inspect the returned status and counts. | Action | Required | Effect |
| --- | --- | --- | | `get` | `mindId` | Read one Mind | | `update` | `mindId` | Update supported `name`, `description`, `discipline`, `systemPrompt`, `sourcePolicy`, `tags`, or sharing state | | `delete` | `mindId`, explicit confirmation | Delete one Mind through canonical cleanup | | `delete_many` | `mindIds` (1–100), explicit confirmation | Batch-delete confirmed Minds and report independent outcomes | | `retrain` | `mindId` | Queue retraining with a complete stored knowledge-index rebuild | | `regenerate_image` | `mindId` | Regenerate the profile image | | `regenerate_prompt` | `mindId` | Regenerate the system prompt | | `regenerate_embeddings` | `mindId` | Queue a full rebuild of the stored knowledge vectors | | `get_training` | `mindId` | Read training status | | `get_patterns` | `mindId` | Read raw patterns when permitted | ### manage_mind_knowledge For `action: "list"`, pass optional `limit` (1–100) and `offset` (0 or greater). The default page contains at most 100 items. Read `data.pagination.hasMore` and advance the offset to continue; `data.total` describes the entire collection. See [knowledge pagination](https://getminds.ai/docs/api/knowledge) for ordering and consistency limits. All actions require `mindId`. | Action | Additional inputs | Effect |
| --- | --- | --- | | `list` | `limit`, `offset` | List items | | `add` | One of `link`, `keywords`, or `file`; optional `description`, `regeneratePrompt` | Queue knowledge ingestion | | `update` | `itemId` and supported fields | Update an item | | `delete` | `itemId`, explicit confirmation | Delete an item | | `status` | `itemId` | Read processing status | | `enrich` | `keywords` | Run keyword enrichment | | `patterns` | — | Read knowledge patterns |`file` has `{ name, url, type? }`. The URL must be public, short-lived signed, or a Minds workspace-upload URL. Retrieval is SSRF-guarded, time-bounded, and limited to 50 MB; do not embed base64 binary data. ### manage_audience All actions require `audienceId`. | Action | Additional inputs | Effect |
| --- | --- | --- | | `get` | — | Read Audience details and grounding | | `get_progress` | — | Read settled build progress | | `follow` / `unfollow` | — | Save or unsave a visible Audience | | `update` | `name`, visibility/team-sharing fields as needed | Update supported Audience fields | | `delete` | Explicit confirmation | Delete the Audience | | `add_member` / `remove_member` | `mindId` | Change Audience membership | | `regenerate_images` | Optional `force`, `limit`, `dry` | Regenerate member images or preview the operation | ### manage_formation For `preview`, both `userInput` and `priorHypothesis` are optional. Blank input uses the default request; text is trimmed and limited to 2000 characters. The forwarded JSON must fit within 64 KiB. MCP validates returned counts, flags, phase and the creation-compatible hypothesis, removes unknown fields, and returns a tool error for malformed responses. Preview does not persist a Formation. For `get`, MCP validates the returned Formation ID and detail fields, removes stored diagnostics, and uses safe failure messages. Malformed or mismatched detail responses return a tool error. Read `status` before using subgroup assignments: recompute can retain the previous completed buckets while building. For `create`, review 2–15 buckets with non-empty text, distinct IDs and distinct labels after trimming. Do not use the reserved IDs `unanswered`, `__unanswered`, or `__other`. `name` is optional. The forwarded JSON must fit within 64 KiB. A user-created split with fewer than two populated primary buckets fails; inspect the returned status before using it. See the [Audience API](https://getminds.ai/docs/api/audiences) for creation errors. All actions require `audienceId`. | Action | Additional inputs | Effect |
| --- | --- | --- | | `list` | — | List Formations | | `get` | `formationId` | Read a Formation | | `preview` | `userInput`, `priorHypothesis` (optional) | Return a non-persisted JSON hypothesis | | `create` | `name`, reviewed `hypothesis` | Persist and compute a Formation | | `delete` | `formationId`, explicit confirmation | Delete a Formation | | `recompute` | `formationId` | Recompute assignments | A hypothesis contains `intent` and `subgroups[]` with `id`, `label`, and `definition`. The UI consumes NDJSON progress and this tool requests JSON from the same v1 preview endpoint. ### manage_study Requires `studyId`. `action: "get"` reads a Study and returns its workspace link. `action: "delete"` requires explicit confirmation and deletes it. The owner can also use `action: "set_link_sharing"` with required boolean `isLinkSharingEnabled`, or `action: "invite"` with 1–100 `emails` and optional `role` (`member`, the default, or `admin`). Enable public sharing only on an explicit user request: attached Audiences and Minds also become publicly readable. The sharing result includes `sharedStudyUrl` when public access is active. Invitation results include `emailFailures`; a successful API response does not guarantee every email was delivered. ### manage_chat | Action | Required | Effect |
| --- | --- | --- | | `create` | One of `mindId`, `mindIds`, or `audienceIds`; optional `name`, `description` | Create a stateful chat | | `send_message` | `chatId`, `message`; optional `role` | Append a message and get the next response | | `delete` | `chatId`, explicit confirmation | Delete chat history | For a follow-up on an existing Study response, `create` also accepts one `mindId` and `responseThread: { studyId, messageId }`. The server retains the authorized prior context and assets. ### manage_study_draft Requires the draft UUID in `draftId`. `action: "delete"` deletes the draft and requires an empty successful API acknowledgement. `action: "consume"` requires a positive `expectedRevision` and accepts an optional Study UUID in `studyId`. It closes planning state; it does not start or verify research. A stale revision is rejected for an active draft; retrying an already consumed draft returns its existing tombstone without changing the linked Study. The tool requires a matching consumed draft response and reports malformed acknowledgements as errors. Check saved state before retrying an uncertain result. ## Deliberate exclusions API credential creation, rotation, and revocation are not exposed through MCP because an MCP session must not control its own bearer credential. Manage keys only in authenticated [account settings](https://getminds.ai/settings/api-keys) or through an independently authenticated REST administration flow. [Minds](https://getminds.ai/)© 2026 Minds. Your target audience. AI-driven and grounded in transparent evidence. Build within minutes. [Minds on X (Twitter)](https://x.com/mindsai_co) [Minds on LinkedIn](https://www.linkedin.com/company/mindsaicompany/) [Minds on Instagram](https://www.instagram.com/getminds.ai/)Minds is part of [![ESOMAR](https://getminds.ai/images/newsroom/logos/esomar-logo.svg)ESOMAR](https://esomar.org/) [![GreenBook](https://getminds.ai/images/newsroom/logos/greenbook.svg)GreenBook Directory](https://greenbook.org/company/Minds) [![Insight Platforms](https://getminds.ai/images/newsroom/logos/insight-platforms.png)Insight Platforms](https://www.insightplatforms.com/platforms/minds/) [![Capterra](https://getminds.ai/images/newsroom/logos/capterra.svg)Capterra](https://www.capterra.com/p/10046203/Minds/) [![G2](https://getminds.ai/images/newsroom/logos/g2.svg)G2](https://www.g2.com/products/minds/reviews) [![CSSDA Best UX Design Award](https://getminds.ai/images/newsroom/logos/cssda-best-ux-award.png)CSSDA Best UX Design Award](https://www.cssdesignawards.com/) [![CSSDA Best Innovation Award](https://getminds.ai/images/newsroom/logos/cssda-best-innovation-award.png)CSSDA Best Innovation Award](https://www.cssdesignawards.com/) [![CSSDA Best UI Design Award](https://getminds.ai/images/newsroom/logos/cssda-best-ui-award.png)CSSDA Best UI Design Award](https://www.cssdesignawards.com/)