--- title: "Minds MCP Tools Reference" description: "[zh] Canonical Minds MCP tool reference for Audiences and Studies." canonical_url: "https://getminds.ai/mcp/zh/tools" last_updated: "2026-09-30T12:16:00.444Z" --- # Minds MCP Tools Reference 工具数量取决于部署配置：常规发现返回23个工具，启用 `list_model_connections` 后为24个；注册的规范工具分别为42个或43个。请以所连接服务器的 `tools/list` 响应为准。 The [Minds MCP server](/mcp/overview) advertises 23–24 curated tools through ordinary `tools/list` discovery and registers 42–43 canonical tools in total. The product model is deliberately small: an **Audience** is a reusable collection of Minds, while a **Study** is the research workspace that contains one or more Audiences, questions, evidence, results, and exports. Compatibility names containing `group` or `panel` remain callable, but new integrations must use the Audience and Study names documented here. The **Advertised** label below means ordinary clients discover the tool automatically. **Explicit** means the canonical tool is registered and callable by integrations that can configure or invoke a known tool name, but it is omitted from the curated discovery surface. Read the [agent operating guide](/mcp/agents) before autonomous use. 只有当 API 返回 `isPublic: true` 或 `isLinkSharingEnabled: true`，并提供共享 ID 时，MCP 才会返回 Study 或 Audience 的公开链接。撤销共享后保留的 ID 不代表链接仍然有效。请原样使用返回的 URL。 名称查找最多搜索最新的 1,000 条可见 Minds、Audiences 或 Studies。对于更早的记录，请使用相应列表工具的 `limit` 和 `offset` 浏览，再传入准确的 ID。不完整或格式错误的列表响应会返回错误，而不是声称不存在匹配记录。 ## Curated advertised surface
Domain Tools
Minds export_mind
Audiences list_audiences , import_audience_sources , get_audience_limits , create_audience_from_brief , ask_audience , export_audience , duplicate_audience
Studies list_studies , list_model_connections , create_study , ask_study , get_study_status , export_study , duplicate_study , export_heatmap , study_heatmap
Guided research plan_study_questions , run_study_questions , get_study_run , list_research_methods , list_study_drafts , save_study_draft , list_study_templates , manage_study_template , get_study_summary
## Minds & Audiences ### list_minds Browse Minds owned by the authenticated user one page at a time. Preserve `nextOffset` to continue; `searchQuery` returns the best fuzzy match among the newest 1,000 Minds. **Parameters:** - `searchQuery` (optional): Best fuzzy name match among the newest 1,000 Minds - `limit` (optional): Page size, default 20, maximum 100 - `offset` (optional): Entries to skip, default 0; use the previous result’s `nextOffset` **Example:** ```text "List my AI minds about marketing" ``` ### create_mind Create a new Mind — a synthetic expert, consumer persona, or digital twin. **Parameters:** - `name` (required): Name of the Mind - `mode` (required): Training mode — `keywords`, `clone`, `link`, or `manual` - `type` (optional): Type — `creative`, `expert`, or `user` (default: `expert`) - `discipline` (optional): Area of expertise - `keywords` (optional): Topics for training (required for `keywords` mode) - `personaContext` (optional): Person to model (required for `clone` mode) - `contextLink` (optional): URL to train from (required for `link` mode) - `description` (optional): What this Mind specializes in - `includeWebSearch` (optional): Set `false` to skip automatic web research; use `manual` for a strictly source-only Mind - `idempotencyKey` (optional UUID): Choose one key before creating and reuse it with the same inputs for retries, including after timeouts. Use a fresh key for another Mind. The result returns the operation key in `structuredContent.idempotencyKey`. Without an explicit key, only identical calls within 10 seconds in the same server process are coalesced; cross-process or later retries need the returned key.
Mode Description Required Fields
keywords Train from topic keywords keywords
clone Create a digital twin of a person personaContext
link Train from website content contextLink
manual Manual configuration None
### chat_with_mind Send one message to a Mind and get its response. Use `mindId` for an exact selection or `mindName` for the best fuzzy match among the newest 1,000 Minds. Browse `list_minds` by offset to find older Minds and pass their exact IDs. Use `manage_chat` for a persistent multi-turn conversation. **Parameters:** - `mindId` (optional): Mind UUID (use this OR `mindName`) - `mindName` (optional): Name with fuzzy matching (e.g., "my marketing expert") - `message` (required): Message to send - `sourcePolicy` (optional): `auto` or `knowledge_only` - `modelConnection` (optional): Verified caller-team connection ID and revision ### get_mind_status Check training progress after creating a Mind. **Parameters:** - `mindId` (required): Mind UUID ### export_mind Export a Mind profile. This tool is **Advertised**. **Parameters:** - `mindId` or `mindName`: Exact UUID or the best fuzzy name match among the newest 1,000 Minds; use an exact UUID for older Minds - `format` (optional): `md`/`markdown` (default, returned inline), `pdf`, `docx`, or `pptx` The tool polls asynchronous generation internally. A successful result includes `filename`, `mimeType`, and either inline Markdown `content` or binary `contentBase64`, plus the Mind’s workspace link. Preserve these fields when saving the export. ### list_audiences List visible Audiences one page at a time. Preserve `nextOffset` to continue; `searchQuery` returns the best fuzzy match within the newest 1,000 entries. **Parameters:** - `searchQuery` (optional): Filter by name using fuzzy search - `limit` (optional): Page size, default 20, maximum 100 - `offset` (optional): Number of entries to skip, default 0 - `includeMinds` (optional): Include member Minds, default `false` ### create_audience Create a reusable Audience from existing Minds. **Parameters:** - `name` (required): Audience name (e.g., "Marketing Experts") - `mindIds` (required): Mind IDs to add — use `list_minds` to find IDs ### import_audience_sources 结果为私有数据，不缓存。工具会验证返回的文件数量和顺序、来源策略、快照校验和以及分布的来源引用，然后才报告成功。预览或创建时，请保持返回的快照不变。缺失或属于其他账户的文件会被视为输入错误；存储故障返回 `502`，不包含提供商内部详情。遇到存储故障或无效确认时，可重试相同的导入；基于内容寻址的上传会保留现有文件。 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. 通过 `files: [{ name, content }]` 导入 UTF-8 `.txt`、`.md`、`.csv` 或 `.json` 来源。`existingFiles` 和 `groundingJson` 可选。此工具可被发现，不创建 Audience，也不独立验证提供的分布。 ### get_audience_limits 工具会先验证账户和团队归属、数值上限以及完整且无重复的创建模式集合，再报告限制。每个 Audience 的上限为零表示工作区被锁定，而不是数据缺失。响应为私有且不可缓存。系统会重新检查凭据是否被阻止；无法查询使用权限时返回 `503`，不会凭空给出免费计划额度。 选择规模前，读取当前账户的 Audience 规模和创建模式限制。可用 `mode` 筛选。请区分自动规模上限与明确指定数量的上限。此工具可被发现。 ### 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. 使用 `groundingPreview: true` 在创建前审阅档案和来源调查结果。创建时发送相同的输入与 `memberCount`，并原样返回 `reviewedGroundingJson` 和 `reviewedGroundingSha256`。如果工具返回待完成的 `structuredContent.operation`，请再次调用 `create_audience_from_brief`，仅传入 `operationId`，其值为该操作的 `jobId`。这会继续现有操作，不会创建第二个 Audience 或重复收费。完成的结果包含 `structuredContent.preview` 或 `structuredContent.audience`。 创建的 Audience 在几秒内即可使用，同时其网络研究在后台继续进行。所创建 Audience 上的结构化字段 `research` 会说明这一点（`phase: "researching"`），重新读取操作时由 `readiness.research` 报告。Study 可以立即运行：有来源的证据会自动替换 Audience 的明确假设，其 Minds 在两次运行之间重新校准，绝不会在运行期间进行。请参阅[两阶段创建](/docs/api/audiences)。 ### preview_audience_dataset_segmentation 预览请求最多接受 256 KiB 的 JSON。所有响应（包括拒绝响应）均为私有且不可缓存。无效 JSON 或字段返回 `400`，请求或数据集超限返回 `413`，Team 资格或上传访问被拒绝返回 `403`。权益查询失败返回 `503`；意外的下载、分类或分析故障返回通用 `500`。省略 `segmentationColumns` 会选择默认的人群和细分变量，而不是所有非标识符字段。MCP 在描述分析前验证完整聚合响应，并核对总行数、选定变量和报告的发现计数。未声明字段会被省略。旧响应缺少关系或依赖计数时，显示为未报告，而不是零。此预览只审核源数据集，不会创建群体或验证其后续分配。 经授权的 Minds 上传文件通过存储访问检查读取。所有网络回退（包括 Minds 主机上的 URL）均使用公共 URL 防护并验证重定向目标；同源 URL 不会绕过私有网络保护。下载仍受 50 MiB 流式大小上限和 30 秒超时限制。失败的 HTTP 响应会在返回错误前被取消。 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. 结果会显示 Audience 的覆盖计数（`sourced`、`proxy`、`assumed`、`missing` 维度）及其后台研究状态（`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. 传入 `deepen: { topics? }` 时，工具会深入研究该 Audience：调查覆盖情况报告为缺失或假设的每个标准维度，以及最多 8 个给定主题（每个不超过 120 个字符），将结果添加到已保存的 grounding 中（对于同一维度，更有力的证据替换较弱的证据；其他所有图表都会保留），并重新校准成员。`deepen` 不能与 `query` 或分布同时使用，并且在 Audience 的后台研究仍在进行时会被拒绝。 ### list_formations 在第一页（`offset: 0`），恢复流程按从旧到新的顺序检查最多100个待处理的构建。某一次尝试失败不会阻止对其他已选构建的尝试，也不会阻止返回列表。请查看构建状态，并重新打开第一页以重试待处理的工作。 `list_formations` 和使用 `action: "list"` 的 `manage_formation` 接受可选的 `limit`、`offset`。每次调用返回一页，默认及最多 100 条。`hasMore` 为 true 时请使用 `pagination.nextOffset` 继续。`list_formations` 的 `totalCount` 是全部可见条目总数，不是本页显示数量。末尾之后的空页不表示 Audience 没有 Formation。无效的续页元数据会产生工具错误。应用和 Study 小组件会收集所有摘要页后再显示完整列表，不会把后续请求失败造成的部分结果作为完整分类。 你可以列出任何有权查看的 Audience 的 Formation，包括共享 Formation 和你自己的私有 Formation。MCP 会拒绝格式错误的列表或缺失的成员计数，而不会将其报告为空列表或零成员。只有 `ready` 状态的计数才是最终值；`building` 和 `failed` 状态的计数均为暂定值。`total: 0` 的空白首页表示没有你可见的 Formation；打开列表时，仅为 Audience 编辑者创建默认分组。v1 列表响应（包括拒绝响应）均为私有且不可缓存。访问查询、初始化或列表存储的意外故障返回通用 `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 工具会轮询原始导出任务，仅在完整文件可用时返回成功。请保留 `filename`、`mimeType` 以及 Markdown `content` 或二进制 `contentBase64`。内联 Markdown 上限为 100,000 个字符，截断时会标记 `_[truncated]_`。取消会停止轮询；未完成的导出会返回错误，请勿使用 `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 ` (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 列出已认证团队的活动模型连接。出现在列表中不代表连接已验证：选择前请检查能力标志和 `verifiedAt`。将 `pagination.nextCursor` 作为下一次请求的 `cursor`。只返回已声明的连接元数据和能力字段，不包含提供商凭据、原始探测结果或未声明的诊断信息。无效响应或无法前进的游标会产生错误。发现连接时出现意外存储故障会返回通用 `500`。仅当所连接的服务器启用了模型连接功能时，才会公开此工具。 ### 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:** ```text "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` 将个体回答的读取和返回结果限制为该问题；工具仍会读取 Study 历史的元数据。执行状态查询会遍历所有相关游标页。如果执行列表读取失败或不完整，工具会返回错误，而不会将部分状态作为成功结果返回。 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 Report queued, running, failed and partial work as such. A polling timeout does not authorize a new submission. ### get_study_analytics Compute statistical analytics across a Study's question history. **Returns:** - **Scale questions**: Mean, median, standard deviation, consensus, Audience rankings - **Categorical questions**: Distribution, dominant category, cross-Audience divergence - **Qualitative questions**: Theme clustering, shared themes, diversity index **Parameters:** - `studyId` (optional): Study UUID - `studyName` (optional): Study name (fuzzy matched) ### export_study Export Study results as a report. **Parameters:** - `studyId` (optional): Study UUID - `studyName` (optional): Study name (fuzzy matched) - `format` (optional): `pdf` (default), `docx`, `pptx`, `csv`, `xls`, `sav`, `md`, or `markdown` - `kind` (optional): `executive_brief`, `full_report` (default), or `raw_data` - `length` (optional): `brief`, `standard`, or `detailed` - `force` (optional): Regenerate instead of returning a cached artifact
Format Description
pdf Branded PDF report
docx Editable Word report
pptx Editable presentation
csv CSV workbook export
xls Excel workbook export
sav SPSS raw-data export
md / markdown Markdown report
### duplicate_study Copy a Study through `POST /api/v1/studies/{studyId}/duplicate`. This tool is **Advertised**. **Parameters:** - `studyId`: Study to duplicate; you must be able to open it - `name` (optional): Name of the copy; defaults to ` (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 使用 `studyId` 或 `studyName`、`messageId` 及 `action: "get"`（默认）或 `"start"` 读取或启动热力图。可选 `assetKey` 指定该问题的图像/视频。启动需要 Premium，每个 Mind 消耗一次回答；已完成分析会被复用。此工具可被发现。 ### 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`. ### run_study_questions 仅在用户明确确认后运行最新草稿修订版。高级方法需要 `advancedMethodOptIn: true`。目录中可执行的方法包括 Conjoint、MaxDiff、NPS、top/bottom box、关键驱动因素、TURF、Gabor-Granger、Van Westendorp、Kano、偏好排序和分群比较。承诺执行前，请检查 `list_research_methods`、`executable: true` 和所需配置。 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`. `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` 表示该方法会在执行时根据配置生成确定性的题目和回答规范；模板保存的题目并不是完整的实际执行问卷。无效的目录响应会被视为错误，而不是空目录。`includePlanned: false` 会排除计划中的方法，但仍显示实验性方法及其不可执行状态。 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. `visual-asset-analysis` 和 `recommendation-synthesis` 目录条目仍为实验性，不能作为这些具名规划方法执行。`fallbackMethodId` 表示可供审阅的替代方法，并非允许自动替换。图像、视频、网站研究及素材热力图有独立的支持路径。对已分配给 Study 问题的素材使用 `study_heatmap`。规划条目不可执行，不代表 MCP 无法分析视觉素材。 ### list_study_drafts 列出活动 Study 草稿，或通过 `draftId` 获取完整的已保存计划。`draft` 可从已保存的步骤和修订号继续；`starting` 表示启动正在进行。按 ID 读取也可能返回无法恢复的 `consumed` 完成记录。无效或不完整的 API 响应是错误，不应被当作空列表或保存成功的证明。 ### save_study_draft 创建时，可在首次请求前选择 `idempotencyKey`（去除首尾空格后 1–200 个字符），结果不确定时重复使用同一个键。重复使用该键会返回现有的已保存草稿，而不会应用新的规划输入。更新时请省略该键，改用 `draftId` 和当前的 `expectedRevision`。不使用键时，重复创建请求可能生成不同的草稿。 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. 底层 v1 端点返回私有且不可缓存的响应。创建/更新 JSON 请求上限为 1 MiB，版本化 `payload` 另有 512 KiB 上限；consume 请求上限为 4 KiB。无效输入返回 `400`，超大输入返回 `413`，意外存储故障返回通用 `500`。未改变的快照保留 `revision` 和 `updatedAt`。保存结果不确定时，请先检查已保存状态再重试；保存本身不会启动研究。 ### 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 响应必须包含完整的模板标识、修订、权限和有效配置。按准确的 `templateId` 读取时，必须返回同一模板。响应缺失、格式无效或标识不匹配均为错误；只有有效的空列表才表示没有返回模板。 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 v1 模板端点返回私有且不可缓存的响应。保存或更新的 JSON 请求体上限为 1 MiB，使用的请求体上限为 4 KiB（超限返回 `413`）；保存的配置仍限制为 512 KiB。格式错误的 JSON 或无效输入返回 `400`。预期的所有权、版本或文件拒绝保留文档规定的状态；意外的存储或提供商故障返回通用 `500`。 工具在报告成功前会验证每次写入的确认响应：保存或更新必须返回预期的完整模板，删除必须返回 `success: true`，使用必须返回 Study 草稿。重试使用操作可能返回已有的 `starting` 或 `consumed` 草稿；工具不会将其描述为新建的可编辑草稿。如果确认响应不完整，请在重试前检查已保存的模板或草稿，并保留原始请求 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 使用 `regenerate_image` 时，传入 `force: true` 可替换现有肖像；否则会跳过已有图片的 Mind。可选的 `personaContext`（去除首尾空格后 1–16,000 个字符）可引导肖像生成，而不改变系统提示词。API 确认缺失或响应结构无效时会返回错误，并建议重试前检查当前状态。请求返回不代表后台训练、图片生成、知识摄取或细分已完成；请检查返回的状态和计数。
Action Required Effect
get mindId Read one Mind
update mindId Update supported name , description , discipline , systemPrompt , sourcePolicy , tags , or sharing state
delete mindId , explicit confirmation Delete one Mind through canonical cleanup
delete_many mindIds (1–100), explicit confirmation Batch-delete confirmed Minds and report independent outcomes
retrain mindId Queue retraining with a complete stored knowledge-index rebuild
regenerate_image mindId Regenerate the profile image
regenerate_prompt mindId Regenerate the system prompt
regenerate_embeddings mindId Queue a full rebuild of the stored knowledge vectors
get_training mindId Read training status
get_patterns mindId Read raw patterns when permitted
### manage_mind_knowledge `action: "list"` 支持可选的 `limit`（1–100）和 `offset`（0 或更大）。默认每页最多 100 条。检查 `data.pagination.hasMore` 并增加 offset 以继续获取；`data.total` 表示整个集合的条目数。排序和一致性限制见[知识分页说明](/docs/api/zh/knowledge)。 All actions require `mindId`.
Action Additional inputs Effect
list limit , offset List items
add One of link , keywords , or file ; optional description , regeneratePrompt Queue knowledge ingestion
update itemId and supported fields Update an item
delete itemId , explicit confirmation Delete an item
status itemId Read processing status
enrich keywords Run keyword enrichment
patterns — Read knowledge patterns
`file` has `{ name, url, type? }`. The URL must be public, short-lived signed, or a Minds workspace-upload URL. Retrieval is SSRF-guarded, time-bounded, and limited to 50 MB; do not embed base64 binary data. ### manage_audience All actions require `audienceId`.
Action Additional inputs Effect
get — Read Audience details and grounding
get_progress — Read settled build progress
follow / unfollow — Save or unsave a visible Audience
update name , visibility/team-sharing fields as needed Update supported Audience fields
delete Explicit confirmation Delete the Audience
add_member / remove_member mindId Change Audience membership
regenerate_images Optional force , limit , dry Regenerate member images or preview the operation
### manage_formation `preview` 的 `userInput` 和 `priorHypothesis` 均可省略。空文本使用默认请求；文本去除首尾空白后最多 2000 个字符。转发的 JSON 不得超过 64 KiB。MCP 验证返回的数量、标志、阶段及符合创建规则的假设，删除未知字段，并对无效响应返回工具错误。预览不会保存 Formation。 对于 `get`，MCP 会验证返回的 Formation ID 和详情字段，删除已存储的诊断信息，并使用安全的错误提示。无效或与请求不匹配的详情响应会返回工具错误。使用成员分配前请读取 `status`：重新计算期间可能仍保留上一次完成的分组。 对于 `create`，请审核 2–15 个文本非空的分组，确保去除空白后的 ID 和标签分别唯一。不要使用保留 ID `unanswered`、`__unanswered`、`__other`。`name` 为可选项，转发的 JSON 不得超过 64 KiB。用户分组若少于两个包含成员的主要子组，则会失败；使用前请检查状态。创建错误请参阅 [Audience API](/docs/api/audiences)。 All actions require `audienceId`.
Action Additional inputs Effect
list — List Formations
get formationId Read a Formation
preview userInput , priorHypothesis (可选) Return a non-persisted JSON hypothesis
create name , reviewed hypothesis Persist and compute a Formation
delete formationId , explicit confirmation Delete a Formation
recompute formationId Recompute assignments
A hypothesis contains `intent` and `subgroups[]` with `id`, `label`, and `definition`. The UI consumes NDJSON progress and this tool requests JSON from the same v1 preview endpoint. ### manage_study Requires `studyId`. `action: "get"` reads a Study and returns its workspace link. `action: "delete"` requires explicit confirmation and deletes it. 所有者还可以使用 `action: "set_link_sharing"` 并提供必填布尔值 `isLinkSharingEnabled`，或使用 `action: "invite"` 并提供 1–100 个 `emails` 及可选 `role`（默认 `member`，或 `admin`）。仅在用户明确要求时启用公开共享：关联的 Audiences 和 Minds 也将可被公开读取。公开访问启用时，结果包含 `sharedStudyUrl`。邀请结果包含 `emailFailures`；API 响应成功不保证每封邮件均已送达。 ### manage_chat
Action Required Effect
create One of mindId , mindIds , or audienceIds ; optional name , description Create a stateful chat
send_message chatId , message ; optional role Append a message and get the next response
delete chatId , explicit confirmation Delete chat history
若要延续现有 Study 回答，`create` 还接受单个 `mindId` 和 `responseThread: { studyId, messageId }`。服务器会保留已获授权的先前上下文和文件。 ### manage_study_draft `draftId` 必须为草稿的 UUID。`action: "delete"` 删除草稿，并要求 API 返回无内容的成功响应。`action: "consume"` 要求正数 `expectedRevision`，并可在 `studyId` 中提供 Study 的 UUID。此操作关闭规划状态，不会启动或验证研究。活动草稿的过期修订会被拒绝；对已消耗草稿重试会返回其现有结束记录，不会更改关联的 Study。工具要求返回匹配草稿且状态为 `consumed` 的响应，并将格式错误的确认视为错误。结果不确定时，请先检查已保存状态再重试。 ## 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](/settings/api-keys) or through an independently authenticated REST administration flow.