Minds MCP Tools Reference

Planning, runs, summaries, heatmaps and templates expose separate operation tools. For these Study operations, reads require flows:read; write operations require flows:write. These strict inputs reject another operation’s selectors. The previous combined names remain callable for compatibility but are omitted from discovery.

Tool names, titles and counts on this page are read from the live server. Treat the connected server’s tools/list response as authoritative.

The Minds MCP server advertises 50 curated tools through ordinary tools/list discovery and keeps 77 canonical tools callable 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. Legacy aliases containing group, panel or spark are still accepted, but new integrations must use the Audience, Study and Mind 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

The live table lists every advertised tool by product area, followed by the canonical tools that stay callable by name without being advertised and the legacy aliases still accepted.

Minds & Audiences

list_minds

Browse the Minds the authenticated user can open one page at a time: their own and those shared with them directly, with their team, or through an Audience or Study. Each Mind is marked as owned or shared. 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

get_shared_mind_knowledge

Advertised, read-only tool. Pass the required shareId UUID from a shared Mind URL. It reads the same public references and stored sphere assessments as the shared page through the endpoint below. It requires authentication and the sparks:read scope, but no Mind edit permission. Missing or revoked shares return 404; uploads, source bodies and private metadata are excluded. Reading does not start training or collection.

GET /api/v1/minds/shared/{shareId}/knowledge

Parameters:

• shareId (required): Share UUID from the shared Mind link

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
• reporting (optional): Exact teamId and optional reporting query; separate from name 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_creation_progress

Read one Audience creation operation and its members’ training progress by operationId. This tool is Advertised and read-only: it never starts or retries creation. Use it to follow a pending operation returned by create_audience_from_brief instead of calling the creation tool again.

Parameters:

• operationId (required): Operation UUID returned by create_audience_from_brief

render_audience_review

Read-only: show exactly one operationId (UUID) or a non-empty operationIds list (UUIDs). For several Audiences, start all operations first and render them together once as separate tabs. Reuse the widget through research, review, revision and creation; status polling does not open another widget.

submit_audience_review

App-only/private: the review widget submits operationId, the current reviewSha256, confirm, and edits containing brief, name, memberCount, excludedDistributions and targetOverrides. It accepts no files. A stale checksum is rejected; changed brief, name or size requires a new review before confirmation. Agents must not claim to invoke this tool when the host does not expose it.

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, recover the same operation and its current review or accepted Audience; do not start another brief. Deeper creation modes (segment_coverage and benchmark_depth) are Pro-plan workflows; on other plans the request is built as balanced instead of being refused. Inspect the effective audienceCreationMode returned by the server rather than assuming the request was accepted unchanged. The result's withheldFromMemberKnowledge lists supplied sources that shaped the grounding but were kept out of the Minds' knowledge, each with a reason (respondent_dataset, study_report, questionnaire, screener, distribution_source, tabular or unclassified); see files kept out of the Minds' knowledge.

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.

New briefs always produce a review before creating an Audience or Minds, including when preview: false is requested. Keep the returned operationId and resume that operation rather than resubmitting the brief. Show one review widget, wait for explicit acceptance, then submit the unchanged reviewed draft ID/checksum or grounding snapshot/checksum. Revisions must be reviewed again before confirmation.

A created Audience is usable within seconds. What its first phase leaves missing or assumed is recorded for shared background research instead of being researched per Audience. The structured research field on the created Audience is phase: "researched" after a normal creation and phase: "researching" only while the Audience's own research runs (for example to finish a research step that timed out, or over your own files and links); readiness.research reports it when an operation is read back. Studies can run right away. 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 Pro 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 and accepts the request for durable preparation. A preparing receipt does not mean a question has been submitted to the Minds. Follow progress with get_study_status, using the returned studyId and questionId (the logical clientRequestId), not operationId. Report submission, queueing, answering or completion only when this request's receipt or progress establishes that stage; do not repeat ask_audience merely to check progress.

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 advertised tool supports owner actions and customer-authorized staff composition amendments.

The tool returns a durable operation immediately. Follow get_audience_creation_progress: audienceRecalibration.status reports progress, result retains the grounding and member counts, and error retains a safe terminal refusal or failure. Optional requestKey (1–128 characters) makes retries with identical input replay the same operation, including after completion; changed input with that key is refused. Acceptance does not mean the roster update or member training has finished. Pass recalibrationId: operation.id to get_audience_creation_progress to read that exact receipt after later edits have started.

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
• files (optional): Survey files as { name, url }, read together as one survey; conversationFiles passes files attached in the chat
• population (optional): Which reported group in the files to validate against
• findSurveys (optional): With files, true also searches for published surveys; without it, only the files are used
• benchmark (optional): Aggregated results you supply as JSON, in the v1 format. One that does not fit is refused with BENCHMARK_INVALID and its issues, before anything starts or is spent
• 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 (one per Mind per question), returns the remaining response balance in responses, and tells the assistant to poll get_audience_validation. The Audience needs at least 10 ready Minds. To score the finished Audience rather than one still settling, wait until get_audience_creation_progress or manage_audience with action: "get_progress" reports readiness.fullyTrained: true and a research phase other than researching. Minds answer validation questions without retrieving their knowledge documents or searching the web. 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, the synthetic responses left (responses), and ready Minds against the minimum.

A selected Mind whose profile changes or that leaves the Audience is omitted from the affected questions. The survey can score the remaining selected Minds when at least 10 remain and every remaining selected Mind answered exactly once. Outside respondents, duplicate answers, undeclared missing answers, dropped respondents answering, and invalid drop declarations prevent scoring. The saved selection count stays unchanged; use each question's actual answer base for its percentages.

A score of 100 means the Minds' answers match the published answer shares exactly. It is 100 minus the mean absolute gap per option, so it is not a share of correct answers, and a high score can hide a large miss on one option. Report each survey's score, its range when available, and who the survey asked, rather than the combined score alone. For per-question human and synthetic shares and the noise floor, read the validation through the v1 API; see how to read a score.

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. This tool is Explicit: it stays callable by name for teams with model connections, but it is not advertised, because callers without an eligible team would only see it fail.

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

ask_study can return status: "preparing", accepted: true, operationId, clientRequestId, questionId and executionStarted: false, without a run ID. The returned questionId is exactly the logical clientRequestId and can scope progress while preparation continues. operationId identifies the preparation operation, not the question. Accepted interpretation is not evidence that Minds have been asked. A disconnect does not cancel this work.

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

Team reporting is an optional mode of list_studies. Pass reporting: { teamId, query } to use the caller's canonical authorized team-insights HTTP reader, including supported current evidence, all-time organization validation/source inventory, recorded adoption and verified completed activity. It makes no additional research or model calls. Omit query to select the feed; use query.view: "catalog" for the Study catalog or "competition" with an exact scheduleId for a tracker snapshot. Name search cannot be combined with reporting.

Large workspaces can return structuredContent.teamInsights.status:"preparing" with pendingStudies and retryAfterSeconds. Repeat the same reporting read after that delay. No complete totals or page coverage are asserted while it prepares; this is background processing of already saved research, not a new research run. Use query.view:"bootstrap" for a bounded metadata page, and optional query.studyIds for up to 100 exact source IDs. Bootstrap intentionally has empty result/run arrays; metadata page length is not research activity. Prepared reporting.materialization describes processing freshness and current source-version checks. Study visibility and independent entity permissions remain current on each read.

Dashboard tracker activation is deliberately HTTP-only. Users review exact edited questions, authorized Audience filters and a future schedule through GET/POST /api/v1/teams/{teamId}/trackers; no MCP tool activates recurring research through this flow. Preview does not execute or reserve research. After uncertain activation, the same draft/revision/hash receipt is retried. Edits apply to future waves while queued waves retain their instrument. GEO presets measure simulated discovery and keyword intent, not search rankings or actual AI citations. See Dashboard trackers.

{
  "reporting": {
    "teamId": "11111111-1111-4111-8111-111111111111",
    "query": { "view": "feed", "evidence": "current" }
  },
  "limit": 20,
  "offset": 0
}

This is a request-shape example, not a customer request or result. reporting.query.templateIds accepts an array of up to 50 unique exact template UUIDs, matching any supplied identity; it excludes templateId. The HTTP transport serializes that array as one CSV parameter. Preserve the returned coverage.unit, nextOffset and complete: feed pages contain result events, competition pages contain run options and catalog pages contain Studies. Do not add page counts as distinct Study counts.

Optional enrichment can be unavailable or pending; preserve those states and inspect capabilities rather than inventing zeros. Organization saved-range averages and deduplicated source inventory retain independent evidence permissions and coverage. Activity launcher attribution is verified separately from Study ownership. Media references are opaque identities, not permission or URLs; binary media delivery and workspace discovery intentionally remain HTTP-only. Authentication management also remains outside MCP research tools. See Team discovery and reporting for scope, range aggregation, authorization, timing and media details. Client polling does not start background Studies. Optional savedFindings is a whole-filter count of nonempty saved question findings at observation time; it is not a completed-run generation count, and a bounded event page cannot substitute when it is omitted. For answer-based planning estimates pass costBasis: "question-answer-v2", responseUnitCost, replacementRate and currency; the tool checks the host capability before claiming support. comparisonCost retains its legacy per-Study meaning. Gross estimates remain available without optional assumed mindsCost; net stays null when spend is missing. Optional member-authorized valuePlanning uses each matching team budget once and remains separate from measured revenue and research-cost avoidance. Shared owner/admin assumption writes stay HTTP-only.

In a recorded organization inventory, optional mindSourceUrls counts distinct HTTP(S) links from authorized Mind knowledge only. uniqueSourceUrls preserves the union with Audience grounding citations. Older hosts can omit the Mind-only value; do not report the union as a Mind-only count or replace unavailable evidence with zero.

To select only organization validity and current source context, supply reporting.query.organizationAudienceId with view:"feed" and evidence:"current". The Study feed, ROI and separate qualified-evidence scope stay unchanged. The tool requires exact organization.selection.audienceId and a matching one-element audienceIds; older or mismatched hosts return organization-scope-not-supported, without substituting global context. If the host advertises a current organization refresh, the tool preserves organization-scope-pending and retryAfterSeconds:30 for the same read, rather than declaring support absent. An absent referenced Audience returns the canonical unavailable/not-found response. Incomplete independent source rights remain unavailable.

Optional organization.sourceHighlights exposes bounded authorized source links with saved titles or an explicit hostname fallback, kind, usageCount and usageUnit. Audience references count distinct citing distribution-records; Mind sources count retained knowledge-records. The separate rankings describe current retained inventory, not historical Study usage or research quality. At most 20 raw candidates and 8 safe links per kind are projected. Query/signed/private/internal/storage targets are omitted; link availability is not verified. Inspect status, exact selection and window instead of treating missing support as a complete list or zero. See the reporting evidence contract.

The same items can carry optional categoryIds, recognized social_post/youtube_video ingestion tags, and only recorded metadata.isSocialProfile. The tool preserves canonical HTTP values; it does not infer classifications from wording or grant additional source access. Categories require current exact-source goals or content-hash-validated saved assessments/legacy assignments. Missing assignments stay empty; older or proof-window-limited readers may omit these optional fields. Omitted proof is unknown, distinct from an explicit empty assignment that can use official uncategorized presentation. Raw proof metadata, source content and private paths are not exposed. These additions do not change source rankings, usage units, the selected Audience or the bounded source window.

For Audience-filtered enriched feeds, require adoption.audienceCoverage for the exact selectedAudienceId. The tool refuses an older/mismatched adoption projection as adoption-audience-scope-not-supported. The receipt distinguishes fully attributed, partially attributed and unattributed completed runs; incomplete coverage gives confirmed matches only, so zero does not establish no historical activity. Missing adoption while refresh is pending stays unavailable. Mixed-Audience run subsets overlap and must not be added. Distinct result-bearing Studies use question time; completed runs use source-bound saved-answer commit time and may include repeated runs of one Study. Do not force those totals equal or infer historical completions from answers. See Study counts and Audience-filtered completed runs.

For current enriched reporting, completed-run dates additionally require adoption.timeCoverage with basis:"source-bound-saved-answer-commit". The tool refuses older or malformed recap-time adoption as adoption-execution-time-not-supported. With missing execution dates, wire period run totals/template counts remain confirmed dated lower bounds; do not present these numeric fields as complete period totals or infer no activity from zero. The daily series is withheld as an empty array, not a proven empty period. All-time terminal-ID totals can remain available independently from dated run pages. A mutable recap refresh never creates new customer execution or shifts historical response costs. Recorded executionTime accompanies qualified dated run/activity rows.

The optional summary.studyActivity series uses basis:"first-filtered-result-per-study" and UTC. It counts each distinct result-bearing Study once at its first qualifying result within the exact selected filter; daily counts and totalStudies equal summary.studies independently of the returned event page. This is the Studies chart, separate from execution-run receipts. Do not sum usageByDay.studies, which can repeat a Study across days. Missing studyActivity is unavailable.

get_study_status

Saved respondent answers do not necessarily mean qualitative findings are ready. Coded qualitative results remain aggregating until the current canonical result is settled; a stale running collection ledger does not hide already-settled evidence. needs_review is settled uncertainty, not automatically background work. The tool keeps readiness, output and respondent counts from the same read. Continue observing the original question rather than repeating its submission.

For the first progress check on the current request, call get_study_status with the same Study and the returned questionId, which equals clientRequestId. Do not use operationId as the question filter. Read requestPreparations even before any questions exist. For planning_required, retain the original request and returned attachments, create the plan, show its exact saved revision and wait for explicit confirmation before start_study_run. For admitted, follow the existing run and its actual answer progress. Never repeat ask_study merely to observe preparation.

When the files sent to ask_study hold a questionnaire, planning_required carries questionnaire: the questions exactly as the document writes them, with their answer formats and the document's skip rules, already saved as an exact draft. Show it, wait for explicit confirmation, then call start_study_run with that draft.id and draft.revision. To change it, use revise_study_plan with draft.edits; do not plan it again with create_study_plan.

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.

get_study_heatmap

Read saved heatmaps without starting analysis or spending responses. Optional assetKey selects an assigned upload path or normalized URL.

Use get_study_heatmap to report the saved attentionOrders for an image or captured video frame. Explain the selected population and identify contributors with mindIds; quote browsing must not redefine that population. If an older result has no order, leave it unreported rather than ranking heat intensity. Ask for approval before starting a replacement analysis. While a new run is incomplete, read its progress; saved Mind work resumes automatically. Describe video findings only at their returned timestamps and identify the result as a synthetic prediction. The Studies API reference defines attention, attentionOrder, meanRank and the exact frame contract.

start_study_heatmap

Start attention analysis of an assigned image, video or website after explicit approval. Requires a paid plan and one response per Mind; websites are visited publicly. assetKey reuses completed analysis of that asset; omitting it may replace earlier derived results. Question answers are preserved.

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

Renaming, folders and sharing

update_item

Rename a Study or an Audience, or move it into one of your folders. This tool is Advertised.

Parameters:

• type (required): study or audience
• study ({ id } or { name }): The Study, when type is study
• audience ({ id } or { name }): The Audience, when type is audience
• name (optional): New name, 1 to 200 characters; surrounding whitespace is trimmed
• folder (optional): Only when the user asks to file or move the item: the name (any case) or ID of one of their folders. With no folder of that name, a personal folder is created.
• removeFromFolders (optional): true takes the item out of all of the user's folders, only when they ask. Not together with folder.
• confirmSharedFolder (optional): true only after the user confirmed in this conversation filing the item in a shared folder or taking it out of one

Send name, folder or removeFromFolders. Always name the item: update_item and set_sharing do not fall back to a Study used earlier in the session, and naming no item, or an item of the other type, returns an error. The owner and collaborators or team members who can edit the item can rename or file it; viewers cannot. A Study is renamed through PATCH /api/v1/studies/{studyId} and is not renamed automatically afterwards; an Audience through PUT /api/v1/audiences/{audienceId} with the name only. Renaming does not change who can open the item. Sending the same name or folder again changes nothing.

folder moves the item: it is added to that folder and taken out of the user's other personal folders. Shared folders that already hold it keep it, so their members keep access; the result names them, and the item is removed there in the workspace or with removeFromFolders. When several of the user's folders have that name, nothing changes and the tool asks which one is meant; pass its ID. Folder changes use GET /api/v1/folders, POST /api/v1/folders and POST/DELETE /api/v1/folders/{folderId}/items.

Filing the item in a shared folder, or taking it out of shared folders with removeFromFolders, changes who can open it. Without confirmSharedFolder: true the tool changes nothing, not even the name, and returns confirmationRequired: true with sharedFolders (id, name, otherMembers, pendingInvitations). Tell the user who would gain or lose access, including anyone who later accepts a pending invitation, and call again with confirmSharedFolder: true only after they confirm.

structuredContent returns type, id, the workspace url, the saved name when the item was renamed, and with folder the folder it is now in (id, name, created, otherMembers, pendingInvitations; null after removeFromFolders). After a move, sharedFolders lists the shared folders that still hold the item. Requires flows:write and sparks:write.

set_sharing

Turn a Study's or an Audience's public view-only link or team sharing on or off. This tool is Advertised. Hosts ask the user to confirm before it runs; call it only when the user explicitly asks to change who can open the item, never as a side effect or a workaround.

Parameters:

• type, study, audience: As for update_item
• link (optional): true turns the public view-only link on: anyone with it can view the item, and a Study link also opens its Audiences and Minds. false turns it off, and an earlier link stops working.
• team (optional): true shares the item with everyone in the owner's team, without an invitation or notification; false stops it. Only the owner changes team sharing.

Send link, team or both. A Study goes through PUT /api/v1/studies/{studyId}/sharing, which only its owner can change; an Audience through PUT /api/v1/audiences/{audienceId}/sharing, where anyone who can edit the Audience can change its link. The result states who can open the item now; tell the user. structuredContent returns type, id, link, team, listedPublicly, shareUrl (the public link while it is on, otherwise null) and the workspace url. Listing an Audience in the Minds marketplace is not changed here: listedPublicly reports the listing as it is, and it is changed in the Minds workspace. Requires flows:write and sparks:write.

Guided Research Planning

create_study_plan and revise_study_plan observe the same durable preparation as the Studies API. A tool may return status: "pending" with accepted: true, operationId, requestId and executionStarted: false while preparation continues. This is an accepted preparation, not a finished plan or permission to start research. An acceptance-unconfirmed or capability-wait response does not prove acceptance. Plan receipts from create_study_plan, revise_study_plan, get_study_plan and render_study_plan may include an optional workspaceUrl for the authenticated owner workspace. When present, show the complete returned URL verbatim as visible link text beside the widget. This link does not enable public sharing or authorize research to start.

Observe again with the same planning tool, the complete original arguments and the same idempotencyKey; do not create a fresh key or submit only an operation ID. Disconnecting observation does not cancel accepted preparation. Once complete, the original saved-plan review is returned for explicit confirmation. get_study_plan remains a read of an already saved plan, not a new preparation request.

create_study_plan

Create a non-executing draft in an existing Study. Put every known question into one cohesive plan: request designs questions; questions preserves a fixed questionnaire verbatim. stimulus contains sources and attachment assignments; policy contains method, locale and source policies. The intended Audiences must already be attached. Bounded history may prune older revisions.

revise_study_plan

Revise the exact saved draft.id at its current draft.revision, with draft.edits, draft.refinement, draft.answers or draft.questionResponses. Stale revisions fail. Show every respondent-visible question and clarification choice; changes require review again. Each Mind sees only its own earlier answers. askIf applies skip logic; not-asked Minds are excluded from that item’s base.

get_study_plan

Read the latest saved revision and complete review using draftPlanId. No planning, saving or execution occurs.

attach_study_audiences

Attach existing audienceIds without removing other Audiences or creating a plan. Retries return attached and alreadyAttached. With link sharing enabled, attached Audiences and their Minds become publicly readable. Access and plan eligibility are validated first.

render_study_plan

Read-only: show a saved plan with studyId (UUID), draftPlanId (UUID) and revision (positive integer). A stale revision is rejected. The widget displays questions and answer options with confirmation controls. Research starts only after explicit acceptance of that exact revision; refinements require reviewing and confirming the new revision.

start_study_run

Start one stored draft as one durable run with draft.id, draft.revision and confirmed: true only in a later user turn confirming the displayed revision. Advanced methods need advancedMethodOptIn: true. Revision, capability, method and source-readability checks precede execution. Poll the returned runId with get_study_status.

resume_study_run

Resume an existing plan-limited run with runId and confirmed: true after explicit approval and sufficient allowance. Existing answers are preserved; this does not create a replacement run.

cancel_study_question

Stop one standalone question that ask_study or ask_audience started, using the returned runId, or studyId and questionId. It uses the same cancellation receipt as POST /api/v1/runs/{runId}/cancel: a queued question is cancelled immediately (status: cancelled), and an active question stops at its next step (status: cancelling). Follow the same question with get_study_status. A question still being prepared is waited for and stopped once submitted; if preparation continues when the call ends, the result is status: preparing and the call can be repeated. After a delivered forecast, the original run can remain completed or failed while progressive.status: cancelled or reactions.stopped > 0 acknowledges a durable stop of remaining replies or Reactions. The tool returns stopped: true for that acknowledgement; the delivered forecast, saved answers and original run history are kept. Remote-provider stop recovery can still be pending. A fully answered question with no pending work, including one whose summary alone is still being written, or a failed question with nothing stopped remains unchanged and returns an error. Multi-question runs from start_study_run cannot be stopped with this tool; stop them in the workspace.

render_study_results

Read-only: show final results with studyId (UUID) and exactly one questionId (non-empty string) or runId (UUID). Queued, running, partial, failed or incomplete-coverage results are rejected. Poll get_study_status first, then render once after successful completion. Routed not_asked items count as settled rather than failed; the original question count and wording are preserved.

get_study_run

This tool is Explicit: callable by name, not advertised. 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 start_study_run.

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. An item for an Audience validation's fixed respondent selection can include routing.respondentsDropped, each with mindId and reason: "profile_changed" or reason: "not_in_audience". These respondents were omitted from this question and are outside its answer base.

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: Resume an existing plan-limited run with runId and confirmed: true after explicit approval and sufficient allowance. Existing answers are preserved; this does not create a replacement run.

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

read_study_summary

Read saved Markdown, evidence blocks and metadata without starting another summary refresh. The result includes the caller's latest metadata.refresh receipt for the Study, or null, and the current snapshot's metadata.revision and metadata.isGenerating. While generation is pending, any returned text is the previously saved summary. Read again to observe completion; the current snapshot is authoritative even when an older receipt is marked superseded: true.

refresh_study_summary

After explicit approval, use confirmed: true to durably request a whole-Study summary refresh. It returns an accepted operation without waiting for generation to finish. A refresh receipt with status: "pending", accepted: true, operationId, requestId, revision and isGenerating: true means work continues in the background. Observe it with read_study_summary; do not repeat refresh to poll or because the client stopped waiting.

Until completion, returned Markdown and evidence blocks remain the previously saved version. On completion the saved summary is replaced without restore history; questions and answers are preserved and are not rerun. A distinct new refresh can supersede an older one; a receipt with status: "completed" and superseded: true is historical, so use the current snapshot. Optional force regenerates unchanged coverage; length is short, standard or detailed. Refreshing does not create an export artifact or send an email.

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.

save_study_template

Create a new private Custom template using template: { name, configuration, requestId? }. Keep template.requestId for safe retries; attachments shared in chat use top-level conversationFiles.

update_study_template

Update an owned template using templateId and update: { expectedRevision, ...changes }. This replaces saved fields without restore history and can change team sharing; explicit approval is required. Stale revisions fail.

use_study_template

Create an independent editable draft using templateId and use: { expectedRevision, requestId }. Use a fresh UUID for each intended draft and reuse it only for retries. Finish fresh context and Audiences in the web app; this does not change the template or start research.

delete_study_template

Permanently delete one saved Study template owned by the authenticated user. This tool is Advertised and destructive: confirm the exact template with the user before calling it. Studies and drafts already created from the template are unaffected, and teammates with shared access cannot delete a template they do not own.

Parameters:

• templateId (required): Template UUID; owner only

The tool reports success only when the API acknowledges success: true. If the acknowledgement is missing, list saved templates before retrying.

Explicit lifecycle tools

These registered canonical tools expose the remaining v1 research lifecycle. They are intentionally omitted from the 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.

For a staged request, use action: "add" with only mindId and sourceInput: { id, text, files }. id is a UUID, text is required and limited to 10,000 characters, and files is a required array of at most 20 { name, path } objects; supply text or at least one file. Paths must reference existing caller-owned uploads, with the existing 50 MB per-file limit. Do not combine this mode with conversationFiles, file, link, keywords, description or regeneratePrompt.

Repeat the identical request, including its original UUID, to observe data.status: pending means registration is still running; complete returns registered itemIds, possibly empty when no sources were found. The underlying API returns HTTP 202 and 200 respectively. Registration does not establish retrieval readiness: call action: "status" for each item and require readyForRetrieval: true before relying on it. This mode preserves the Mind's current prompt and does not automatically share private uploads. It uses the same source-input contract as the Knowledge API.

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.

The server instructions tell assistants that deleting or archiving Studies, Audiences, Minds or answers, listing an Audience in the Minds marketplace or removing it from there, and billing, plan, refund or payment changes are not available in assistant apps; the user does these in the Minds workspace. Renaming, filing in folders and sharing are available through update_item and set_sharing.

Stripe billing for agents

These canonical billing tools remain callable by name without appearing in the curated advertised list. The browser exposes the same billing actions through WebMCP when supported.

ChatGPT’s published app guidelines currently exclude purchases of digital subscriptions and credits. Existing paid-account research is supported; these billing tools are not part of the ChatGPT advertised surface. Use the HTTP or browser purchase workflow where the client permits it. Explicit MCP callability is not proof that a client discovers or permits checkout. See the OpenAI commerce rules.

get_billing_catalog

A newly registered owner already has Pay as you go with no response allowance or signup grant. Help them choose a response purchase before starting research. An owner leaving Pro confirms the scheduled switch in Minds billing settings; do not interpret a checkout link as cancellation.

Read Stripe prices and purchase eligibility for the authenticated account. For a new Pay as you go workspace, pass billingCountry so the response packs come from the correct Stripe entity; use the same country for checkout. This makes no purchase.

start_billing_checkout

Start a new subscription or response-credit checkout after buyer approval. Pass kind, a stable idempotencyKey, the selected priceId, and explicit legalAcceptance for subscriptions; optional subscription fields are planType, quantity and currency. billingCountry also applies to response-credit purchases for new Pay as you go workspaces. New Starter subscriptions and trials are retired; existing subscription management remains in Minds billing settings. Return the Stripe URL to the buyer and reuse the key after a timeout. Wallet credentials belong to the HTTP payment route, outside MCP tool arguments.

UCP clients can discover the same hosted purchase flow at /.well-known/ucp; see the UCP checkout workflow. It shares the Stripe billing services with these MCP tools and requires a platform-bound OAuth client for its HTTP operations.

Custom response top-ups

For a budget-based purchase, call get_billing_catalog first and take priceId from responseCredits.customTopUp. Supply integer amountMinor to start_billing_checkout: 10000 means 100 units of the returned currency. A retry must keep both the purchase key and this budget unchanged. The hosted Stripe page confirms the payable total before the buyer pays.

Automatic recharge controls

An assistant should first use get_billing_catalog to show the owner the response quote and proposed recharge rules. After the owner chooses those values, call start_billing_checkout with kind: auto_recharge and a stable idempotencyKey. Present the returned Stripe link for personal review and payment-method consent. Creating this link never authorizes the assistant to enable charging on the owner’s behalf. On return, read the catalog again to confirm the saved status; do not infer activation from a tool response or a browser redirect. Manual response purchases remain a separate checkout action.

{
  "kind": "auto_recharge",
  "priceId": "price_from_customTopUp",
  "amountMinor": 10000,
  "thresholdAmountMinor": 500,
  "monthlyAmountLimit": 19992
}

responseCredits.customTopUp.priceId → priceId; amountMinor, thresholdAmountMinor, monthlyAmountLimit = integer minor currency units; for uncapped recharge, omit monthlyAmountLimit and explicitly set uncappedAutoRecharge: true.

POST /api/v1/billing/checkout + Idempotency-Key / start_billing_checkout + idempotencyKey → Stripe Checkout mode=setup.

Pass includeInvoices: true to get_billing_catalog, or includeInvoices=true to GET /api/v1/billing/catalog, to include recent invoices under subscription.invoices. Only the billing owner or an authorized administrator can read that customer’s invoices; the default catalog omits invoice retrieval.

manage_audience_support

Start with list_assigned when acting as support staff, then use the returned exact Audience ID. A customer owner uses grant with the confirmed staff email, task reason, expiry and a stable retry key; revoke withdraws that grant. Submit the agreed composition edit with recalibrate_audience, then read its returned operation using get_audience_creation_progress. Acceptance is pending, not success. If a status read fails, read the same operation again. The Audiences API defines the 30-day ceiling, scope restrictions and checkpoint behavior. activity supplies the request history without starting research.

grant: audienceId, staffEmail, reason, expiresAt, requestKey. revoke: audienceId, grantId. list_access, activity: audienceId, cursor?. list_assigned: cursor?.

structuredContent.data: API data.

recalibrate_audience: audience.id, research.instruction / distributions, requestKey. get_audience_creation_progress: audienceId, recalibrationId = operation.id.

OAuth: sparks:write; get_audience_creation_progress: sparks:read.

Select Audience segments

create_study and attach_study_audiences accept segmentSelections as a list of { audienceId, segments } objects. Each segments list contains up to three { formationId, subgroupId } pairs. ask_audience accepts the pairs directly as segments. The API uses an Audience-ID map instead of this MCP list; labels never determine membership.

Monadic concept test

Each Mind sees one variant and answers the same questions. Review the sample and materials before starting. Assign every file a role, then choose what each question shows. Unassigned files stay researcher-only. Each Mind stays in one variant for the entire run.

• create_study_plan: monadic → monadicPreviewId, allocation, questions.
• get_study_plan: monadicPreviewId.
• start_study_run: study, monadicPreviewId, confirmed: true, advancedMethodOptIn: true.

Starting confirms this allocation, questionnaire and material mapping, including the advanced method. Unsupported timed human task. Edit this question before starting.

API · Guide

Reading prepared findings in an assistant

Call list_studies with reporting.query.consistency="prepared" when a dashboard answer may use a saved snapshot. State its preparation date, and distinguish missing preparation from zero research. For a quick executive overview, request evidence="current" and context="metrics"; retrieve context="activity" separately for execution details and media. Never combine different generationDigest values or business selections. Only a complete source scope supports whole-team KPI or cost claims. This read does not start research. Coverage, invalidation and retry contract.