--- title: "Minds MCP Tools Reference" description: "[ar] Canonical Minds MCP tool reference for Audiences and Studies." canonical_url: "https://getminds.ai/mcp/ar/tools" last_updated: "2026-09-30T14:33:12.251Z" --- # Minds MCP Tools Reference يعتمد عدد الأدوات على إعداد النشر: يعرض الاكتشاف العادي 23 أداة، أو 24 عند تفعيل `list_model_connections`، ويكون عدد الأدوات الأساسية المسجلة 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. يعيد MCP رابطًا عامًا لـ Study أو Audience فقط عندما تشير API إلى `isPublic: true` أو `isLinkSharingEnabled: true` وتوفر معرّف مشاركة. المعرّف المحتفظ به بعد إلغاء المشاركة لا يعني أن الرابط نشط. استخدم عناوين URL المُعادة كما هي. يفحص البحث بالاسم أحدث 1,000 سجل مرئي كحد أقصى من Minds أو Audiences أو Studies. للوصول إلى سجل أقدم، تصفّح أداة القائمة المناسبة باستخدام `limit` و`offset` ثم مرّر المعرّف الدقيق. تعيد استجابات القوائم غير المكتملة أو غير السليمة خطأ بدلًا من الادعاء بعدم وجود سجل مطابق. ## 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. يستورد مصادر UTF-8 من نوع `.txt` أو `.md` أو `.csv` أو `.json` عبر `files: [{ name, content }]`. الحقلان `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` لمراجعة الملفات ونتائج المصادر قبل الإنشاء. أعد `reviewedGroundingJson` و`reviewedGroundingSha256` دون تعديل مع المدخلات نفسها و`memberCount`. إذا أعادت الأداة `structuredContent.operation` قيد الانتظار، فاستدعِ `create_audience_from_brief` مجددًا مع `operationId` فقط، واجعل قيمته `jobId` الخاص بالعملية. يتابع ذلك العملية القائمة دون إنشاء Audience ثانية أو احتساب رسوم مكررة. تحتوي النتائج المكتملة على `structuredContent.preview` أو `structuredContent.audience`. تصبح Audience المُنشأة قابلة للاستخدام خلال ثوانٍ بينما يستمر بحثها على الويب في الخلفية. يوضح ذلك الحقل المنظّم `research` في Audience المُنشأة (`phase: "researching"`)، ويُبلغ عنه `readiness.research` عند إعادة قراءة عملية. يمكن تشغيل Studies فورًا: تحلّ الأدلة ذات المصادر تلقائيًا محل الافتراضات المُعلَنة لـ Audience، وتُعاد معايرة Minds بين عمليات التشغيل، لا أثناءها أبدًا. راجع [الإنشاء على مرحلتين](/docs/api/audiences). ### preview_audience_dataset_segmentation تقبل طلبات المعاينة JSON بحد أقصى 256 KiB. جميع الاستجابات، بما فيها الرفض، خاصة وغير قابلة للتخزين المؤقت. يعيد JSON أو الحقول غير الصالحة `400`، وتجاوز حجم الطلب أو مجموعة البيانات `413`، ورفض أهلية Team أو الوصول إلى الملف `403`. يعيد فشل الاستعلام عن الاستحقاقات `503`؛ وتعطل التنزيل أو التصنيف أو التحليل غير المتوقع `500` عامًا. يؤدي حذف `segmentationColumns` إلى اختيار متغيرات السكان والتقسيم الافتراضية، وليس كل حقل غير معرّف. يتحقق MCP من الاستجابة التجميعية الكاملة ويطابق إجمالي الصفوف والمتغيرات المختارة وأعداد الاكتشافات المبلّغ عنها قبل وصف التحليل. تُحذف الحقول غير المعلنة. تُوصف أعداد العلاقات أو التبعيات الغائبة في الاستجابات القديمة بأنها غير مبلّغ عنها، لا صفرًا. هذه مراجعة لبيانات المصدر؛ ولا تنشئ مجموعة ممثلة أو تتحقق من توزيعها اللاحق. تُقرأ ملفات Minds المرفوعة والمصرح بها عبر فحوص الوصول إلى التخزين. يستخدم كل تنزيل بديل عبر الشبكة، بما في ذلك عنوان على مضيف Minds، حماية العناوين العامة ويتحقق من وجهات إعادة التوجيه؛ ولا تتجاوز العناوين ذات الأصل نفسه حماية الشبكات الخاصة. تظل التنزيلات خاضعة لحد تدفق قدره 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` و`manage_formation` مع `action: "list"` المعاملين الاختياريين `limit` و`offset`. يعيد كل استدعاء صفحة واحدة بحد افتراضي وأقصى 100. تابع عبر `pagination.nextOffset` ما دامت `hasMore` صحيحة. في `list_formations`، يمثل `totalCount` العدد المرئي الكامل لا عدد العناصر المعروضة. لا تعني الصفحة الفارغة بعد نهاية القائمة أن Audience بلا Formations. تؤدي بيانات الاستمرار غير الصالحة إلى خطأ أداة. يجمع التطبيق وعنصر Study كل صفحات الملخص قبل عرض قائمة كاملة؛ ولا يُعرض فشل طلب لاحق على أنه تقسيم مكتمل. يمكنك سرد Formations لأي Audience تستطيع عرضها، بما يشمل المشتركة والخاصة التي تخصك. يرفض MCP القوائم المشوّهة أو أعداد الأعضاء المفقودة بدلًا من الإبلاغ عن قائمة فارغة أو صفر أعضاء. تكون الأعداد نهائية فقط عند الحالة `ready`؛ أما `building` و`failed` فأعدادها مؤقتة. تعني الصفحة الأولى الفارغة مع `total: 0` عدم وجود Formations مرئية لك؛ ولا يؤدي فتحها إلى إنشاء التقسيمات الافتراضية إلا لمحرري 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_heatmap` لمادة مرتبطة بالفعل بسؤال Study. هذه الحالة لا تعني أن MCP عاجز عن تحليل المواد البصرية. ### list_study_drafts اعرض مسودات Study النشطة أو استرجع حالة التخطيط المحفوظة كاملة باستخدام `draftId`. يمكن استئناف `draft` من الخطوة والمراجعة المحفوظتين؛ وتشير `starting` إلى أن الإطلاق جارٍ بالفعل. قد يعيد البحث بالمعرّف سجل إغلاق `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`؛ ولا تُعرض بوصفها مسودة جديدة قابلة للتحرير. إذا كان الإقرار غير مكتمل، فتحقق من القوالب أو المسودات المحفوظة قبل إعادة المحاولة واحتفظ بمعرّف الطلب الأصلي. 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` وزد الإزاحة للمتابعة؛ يشير `data.total` إلى المجموعة كاملة. راجع [ترقيم صفحات المعرفة](/docs/api/ar/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 وحقول التفاصيل، ويحذف التشخيصات المحفوظة ويستخدم رسائل خطأ آمنة. تُرجع التفاصيل غير الصالحة أو غير المطابقة خطأ أداة. اقرأ `status` قبل استخدام تعيينات المجموعات؛ فقد تُبقي إعادة الحساب المجموعات السابقة المكتملة أثناء العمل. في `create`، راجع من 2 إلى 15 مجموعة بنصوص غير فارغة ومعرّفات وتسميات فريدة بعد إزالة المسافات الطرفية. لا تستخدم المعرّفات المحجوزة `unanswered` أو `__unanswered` أو `__other`. الحقل `name` اختياري. يجب ألا يتجاوز JSON المرسل 64 KiB. يفشل تقسيم المستخدم إذا احتوى على أقل من مجموعتين أساسيتين بهما أعضاء؛ تحقق من الحالة قبل استخدامه. راجع أخطاء الإنشاء في [واجهة Audience](/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 يتطلب UUID المسودة في `draftId`. يحذف `action: "delete"` المسودة ويتطلب استجابة API ناجحة بلا محتوى. يتطلب `action: "consume"` قيمة موجبة لـ `expectedRevision` ويقبل UUID اختياريًا لـ Study في `studyId`. يغلق حالة التخطيط ولا يبدأ البحث أو يتحقق منه. تُرفض المراجعة القديمة للمسودة النشطة؛ وتعيد محاولة استهلاك مسودة مستهلكة بالفعل سجل الإغلاق الموجود دون تغيير 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.