Minds MCP Tools Reference

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

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.

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.

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

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

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 for ordering and consistency limits.

All actions require mindId.

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.

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 for creation errors.

All actions require audienceId.

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

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 or through an independently authenticated REST administration flow.