Minds: Synthetic Market Research Panels

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['question'], 'properties': {'name': {'type': 'string', 'description': 'Optional name for the Study created to ask this question. Defaults to the Audience name.'}, 'groupId': {'type': 'string', 'description': 'Legacy alias for audienceId. Accepted for compatibility.'}, 'question': {'type': 'string', 'minLength': 1, 'description': 'Exactly one respondent-visible standalone question for every Mind in the Audience. The system may classify or reformat it, but any text in this field can reach the Minds and influence their answers. Include only the concept, question, and instructions the Minds should receive. Never place planner-only or MCP-client orchestration instructions here.'}, 'groupName': {'type': 'string', 'description': 'Legacy alias for audienceName. Accepted for compatibility.'}, 'audienceId': {'type': 'string', 'description': 'Audience ID (UUID). Preferred when known.'}, 'attachments': {'type': 'array', 'items': {'type': 'object', 'properties': {'id': {'type': 'string', 'maxLength': 255, 'minLength': 1, 'description': 'Stable asset ID used by questionAttachments to assign this file to specific planned questions.'}, 'url': {'type': 'string', 'minLength': 1, 'description': 'Fetchable HTTP(S), signed, or Minds workspace upload URL. MCP cannot read or upload a local file:// path. Use a fetchable HTTP(S) URL, a signed URL supplied by the client for the attached file, or an existing Minds workspace upload URL/path. Study tools import external file URLs into durable Minds storage before saving or running. A workspace upload reused as a Study asset must sit under chat/<userId>/: request the signed upload with folder "chat" and pass that storage path or its /api/uploads/chat/ URL. A temp/, portfolio/, or context/ path — and any /api/uploads/file-access/ URL — is refused as not belonging to the workspace owner and is never re-fetched; pass a plain external URL instead. The Study refuses to start if Minds cannot read the asset.'}, 'name': {'type': 'string', 'minLength': 1, 'description': 'File name visible in the Study.'}, 'path': {'type': 'string', 'minLength': 1, 'description': 'Storage path of a file already uploaded to Minds. MCP cannot read or upload a local file:// path. Use a fetchable HTTP(S) URL, a signed URL supplied by the client for the attached file, or an existing Minds workspace upload URL/path. Study tools import external file URLs into durable Minds storage before saving or running. A workspace upload reused as a Study asset must sit under chat/<userId>/: request the signed upload with folder "chat" and pass that storage path or its /api/uploads/chat/ URL. A temp/, portfolio/, or context/ path — and any /api/uploads/file-access/ URL — is refused as not belonging to the workspace owner and is never re-fetched; pass a plain external URL instead. The Study refuses to start if Minds cannot read the asset.'}, 'type': {'type': 'string', 'minLength': 1, 'description': 'MIME type when known.'}}}, 'description': 'Files/images processed once and given to every Audience member as context. MCP cannot read or upload a local file:// path. Use a fetchable HTTP(S) URL, a signed URL supplied by the client for the attached file, or an existing Minds workspace upload URL/path. Study tools import external file URLs into durable Minds storage before saving or running. A workspace upload reused as a Study asset must sit under chat/<userId>/: request the signed upload with folder "chat" and pass that storage path or its /api/uploads/chat/ URL. A temp/, portfolio/, or context/ path — and any /api/uploads/file-access/ URL — is refused as not belonging to the workspace owner and is never re-fetched; pass a plain external URL instead. The Study refuses to start if Minds cannot read the asset.'}, 'audienceName': {'type': 'string', 'description': "Audience name to resolve via fuzzy match against the user's Audiences."}}}

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['question'], 'properties': {'links': {'type': 'array', 'items': {'type': 'object', 'required': ['label'], 'properties': {'id': {'type': 'string'}, 'url': {'type': 'string', 'description': 'URL to fetch as evidence for this question'}, 'label': {'type': 'string', 'description': 'Human-readable label for the link'}}}, 'description': 'Web pages given to every Mind as evidence for this question through v1 /studies/{studyId}/runs.'}, 'model': {'type': 'string', 'description': 'Optional per-request model override. Must be sent together with provider.'}, 'panelId': {'type': 'string', 'description': 'Study ID (UUID; legacy wire field name: panelId). Omit both panelId and panelName only when continuing the active Study from this MCP session.'}, 'studyId': {'type': 'string', 'description': 'Study ID (UUID). Omit with studyName to continue the active Study from this MCP session.'}, 'groupIds': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Legacy alias for audienceIds. Accepted for compatibility.'}, 'keywords': {'type': 'array', 'items': {'type': 'object', 'required': ['label'], 'properties': {'id': {'type': 'string'}, 'url': {'type': 'string'}, 'label': {'type': 'string', 'description': 'Search keyword or phrase'}}}, 'description': 'Search keywords used to gather evidence for this question through v1 /studies/{studyId}/runs.'}, 'provider': {'enum': ['anthropic', 'openai', 'google'], 'type': 'string', 'description': 'Provider for the model override. Must be sent together with model.'}, 'question': {'type': 'string', 'minLength': 1, 'description': 'Exactly ONE respondent-visible standalone question or result-dependent adaptive follow-up for every selected Mind. Never concatenate, enumerate, or otherwise place a questionnaire, survey, battery, section, cohesive question set, or two or more known questions in this field. The system may classify or reformat it, but any text here can reach the Minds and influence their answers. Include only the single question, its necessary stimulus, and respondent-facing instructions. Never place planner-only or MCP-client orchestration instructions here.'}, 'panelName': {'type': 'string', 'description': 'Study name (fuzzy matched; legacy wire field name: panelName). Omit both panelName and panelId only when continuing the active Study from this MCP session.'}, 'studyName': {'type': 'string', 'description': 'Study name (fuzzy matched). Omit with studyId to continue the active Study from this MCP session.'}, 'attachments': {'type': 'array', 'items': {'type': 'object', 'properties': {'id': {'type': 'string', 'maxLength': 255, 'minLength': 1, 'description': 'Stable asset ID used by questionAttachments to assign this file to specific planned questions.'}, 'url': {'type': 'string', 'minLength': 1, 'description': 'Fetchable HTTP(S), signed, or Minds workspace upload URL. MCP cannot read or upload a local file:// path. Use a fetchable HTTP(S) URL, a signed URL supplied by the client for the attached file, or an existing Minds workspace upload URL/path. Study tools import external file URLs into durable Minds storage before saving or running. A workspace upload reused as a Study asset must sit under chat/<userId>/: request the signed upload with folder "chat" and pass that storage path or its /api/uploads/chat/ URL. A temp/, portfolio/, or context/ path — and any /api/uploads/file-access/ URL — is refused as not belonging to the workspace owner and is never re-fetched; pass a plain external URL instead. The Study refuses to start if Minds cannot read the asset.'}, 'name': {'type': 'string', 'minLength': 1, 'description': 'File name visible in the Study.'}, 'path': {'type': 'string', 'minLength': 1, 'description': 'Storage path of a file already uploaded to Minds. MCP cannot read or upload a local file:// path. Use a fetchable HTTP(S) URL, a signed URL supplied by the client for the attached file, or an existing Minds workspace upload URL/path. Study tools import external file URLs into durable Minds storage before saving or running. A workspace upload reused as a Study asset must sit under chat/<userId>/: request the signed upload with folder "chat" and pass that storage path or its /api/uploads/chat/ URL. A temp/, portfolio/, or context/ path — and any /api/uploads/file-access/ URL — is refused as not belonging to the workspace owner and is never re-fetched; pass a plain external URL instead. The Study refuses to start if Minds cannot read the asset.'}, 'type': {'type': 'string', 'minLength': 1, 'description': 'MIME type when known.'}}}, 'description': 'Files/images processed once and given to every participating Mind. MCP cannot read or upload a local file:// path. Use a fetchable HTTP(S) URL, a signed URL supplied by the client for the attached file, or an existing Minds workspace upload URL/path. Study tools import external file URLs into durable Minds storage before saving or running. A workspace upload reused as a Study asset must sit under chat/<userId>/: request the signed upload with folder "chat" and pass that storage path or its /api/uploads/chat/ URL. A temp/, portfolio/, or context/ path — and any /api/uploads/file-access/ URL — is refused as not belonging to the workspace owner and is never re-fetched; pass a plain external URL instead. The Study refuses to start if Minds cannot read the asset.'}, 'audienceIds': {'type': 'array', 'items': {'type': 'string'}, 'description': "Optional subset of the Study's Audiences to ask; defaults to all Audiences."}, 'historyMode': {'enum': ['last5', 'followup_only', 'none'], 'type': 'string', 'description': 'Controls prior Study-history carryover for this one direct question. Defaults to none, so this measurement is independent of earlier Study questions. last5 is only for a conversational/adaptive question that requires respondent continuity; it costs roughly 2.4x wall-clock for about 0.6pp of accuracy. followup_only carries history only when the submitted question is classified as a conversational follow-up.'}, 'responseForm': {'enum': ['concise', 'standard', 'expanded'], 'type': 'string', 'description': 'How long and how shaped each qualitative answer should be: concise is one short message (5-20 words), standard is 1-3 sentences (25-90 words), expanded is 2-5 sentences (70-180 words). Omit to let the question itself decide. Set expanded when the researcher wants narrative depth (interviews, lived experience, reasoning) without editing the question wording, which a fixed instrument must keep exact. Ignored for scale, categorical and multiselect questions.'}, 'sourcePolicy': {'enum': ['auto', 'knowledge_only'], 'type': 'string', 'description': 'Use knowledge_only to forbid web/request sources and require every answer to be grounded in processed Mind knowledge.'}, 'modelConnection': {'type': 'object', 'required': ['id', 'revision'], 'properties': {'id': {'type': 'string', 'format': 'uuid', 'pattern': '^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$'}, 'revision': {'type': 'integer', 'maximum': 9007199254740991, 'exclusiveMinimum': 0}}, 'description': 'Verified team model connection ID and current revision. Mutually exclusive with model/provider. Applies to Mind answers and verbatim rendering; supporting analysis retains platform models.', 'additionalProperties': False}}}

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'properties': {'name': {'type': 'string', 'maxLength': 100, 'description': 'Optional Audience name override. When omitted, the server names the Audience from the brief or the LLM detection result.'}, 'text': {'type': 'string', 'maxLength': 200000, 'minLength': 1, 'description': 'Legacy alias for `brief`. Accepted for back-compat.'}, 'brief': {'type': 'string', 'maxLength': 200000, 'minLength': 1, 'description': 'Free-text brief describing the population the Audience should represent. E.g. "California high school students grades 9-12", "Berlin Späti customers", "Spanish lawyers", "management team of Coca Cola". The server runs deep web research on this brief to find demographic / psychographic distributions from authoritative sources, then generates personas that proportionally reflect those distributions.'}, 'files': {'type': 'array', 'items': {'type': 'object', 'required': ['name', 'url'], 'properties': {'url': {'type': 'string', 'minLength': 1, 'description': 'URL of an already-uploaded file. MCP cannot read or upload a local file:// path. Use a fetchable HTTP(S) URL, a signed URL supplied by the client for the attached file, or an existing Minds workspace upload URL/path. Study tools import external file URLs into durable Minds storage before saving or running. A workspace upload reused as a Study asset must sit under chat/<userId>/: request the signed upload with folder "chat" and pass that storage path or its /api/uploads/chat/ URL. A temp/, portfolio/, or context/ path — and any /api/uploads/file-access/ URL — is refused as not belonging to the workspace owner and is never re-fetched; pass a plain external URL instead. The Study refuses to start if Minds cannot read the asset.'}, 'name': {'type': 'string', 'description': 'File name'}}}, 'maxItems': 20, 'description': 'Optional already-uploaded research files. MCP cannot read or upload a local file:// path. Use a fetchable HTTP(S) URL, a signed URL supplied by the client for the attached file, or an existing Minds workspace upload URL/path. Study tools import external file URLs into durable Minds storage before saving or running. A workspace upload reused as a Study asset must sit under chat/<userId>/: request the signed upload with folder "chat" and pass that storage path or its /api/uploads/chat/ URL. A temp/, portfolio/, or context/ path — and any /api/uploads/file-access/ URL — is refused as not belonging to the workspace owner and is never re-fetched; pass a plain external URL instead. The Study refuses to start if Minds cannot read the asset. The server analyzes these through the same extended screener/questionnaire path as the in-app New Audience uploader, including study roles, screening and quota rules, review distributions, and grounding provenance.'}, 'links': {'type': 'array', 'items': {'type': 'string'}, 'maxItems': 10, 'description': 'Optional URLs scraped server-side for additional context (e.g. an article describing the population).'}, 'keywords': {'type': 'array', 'items': {'type': 'string'}, 'maxItems': 10, 'description': 'Optional Exa web-search seeds added alongside the brief.'}, 'memberCount': {'type': 'integer', 'maximum': 6000, 'description': 'Exact number of Minds to create. Pass this whenever the user states a size ("exactly 50 per region", "genau 50 Minds je Zelle") instead of relying on the server to parse the number out of the brief. When omitted, the size is inferred from the brief and, failing that, from the creation mode\'s evidence-based automatic sizing. Two separate refusals apply: 403 MODE_CAP above 20 in "balanced" mode (switch to segment_coverage or benchmark_depth), and 403 PLAN_LIMIT above your plan\'s per-Audience cap. The 6000 accepted here is the absolute system ceiling, not your allowance — call get_audience_limits for the real one. The Audience is never created at a partial size.', 'exclusiveMinimum': 0}, 'operationId': {'type': 'string', 'format': 'uuid', 'pattern': '^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$', 'description': 'Resume a queued preview or creation by its returned jobId. Reads its v1 operation status without creating or charging anything. Supply this alone; do not repeat the creation brief to check progress.'}, 'trainMembers': {'type': 'boolean', 'description': 'Opt-in per-Mind training for large reviewed-dataset cohorts (default false). By default a reviewed-dataset Audience of more than ~40 Minds is bulk-created immediately ready: exact demographics, but no per-Mind research training (empty system prompt, no knowledge items). Set true to create those Minds untrained instead and enqueue each one through the same per-member training pipeline the in-app draft flow uses, preserving its deterministic cohort profile and the request locale. The tool still returns as soon as the Audience exists — training continues in the background (structuredContent.audience.memberTraining reports what was queued); poll each member with GET /api/v1/minds/{id}/training. Has no effect on Audiences whose members are already trained individually.'}, 'cohortAllocation': {'type': 'object', 'properties': {'seed': {'type': 'string', 'maxLength': 200}, 'enabled': {'type': 'boolean'}, 'jointStrategy': {'enum': ['independent', 'aligned', 'observed'], 'type': 'string'}, 'minSegmentCount': {'type': 'integer', 'maximum': 20, 'minimum': 0}, 'targetOverrides': {'type': 'array', 'items': {'type': 'object', 'required': ['distribution', 'segments'], 'properties': {'segments': {'type': 'array', 'items': {'type': 'object', 'required': ['label', 'pct'], 'properties': {'pct': {'type': 'number', 'maximum': 100, 'minimum': 0}, 'label': {'type': 'string'}}}, 'maxItems': 200}, 'distribution': {'type': 'string'}}}, 'maxItems': 500}, 'maxDistributions': {'type': 'integer', 'maximum': 500, 'minimum': 1}, 'distributionNames': {'type': 'array', 'items': {'type': 'string'}, 'maxItems': 500}, 'includeProfilesInResponse': {'type': 'boolean'}}, 'description': 'Deterministic allocation controls. Reviewed respondent datasets default to observed, which preserves the strongest privacy-safe structural relationships while keeping exact marginals; other sources default to independence. Use distributionNames/maxDistributions to choose axes, minSegmentCount for a feasible floor, and seed for reproducible external runs.'}, 'groundingPreview': {'type': 'boolean', 'description': 'Review the quota axes BEFORE any Mind exists. When true, the server runs research grounding and deterministic cohort allocation without creating an Audience or Minds or consuming a generation allowance. To revise a saved preview without repeating research, pass its unchanged reviewedGroundingJson/SHA pair together with groundingPreview and the revised exclusion/allocation options. Fresh research uses the same durable operation as the public REST API; this tool polls it to completion. The response includes effective target percentages and integer counts; explicit allocation targets that do not match grounded axes fail closed. Present the plan to the user, then call again without groundingPreview and pass reviewedGroundingJson plus reviewedGroundingSha256 unchanged with the same allocation options.'}, 'includeWebSearch': {'type': 'boolean', 'default': True, 'description': 'Set false to skip Exa web search and extraction completely. The Audience is then grounded only on the brief and supplied files, links, keywords, and structurally parsed respondent data.'}, 'groupCreationMode': {'enum': ['balanced', 'segment_coverage', 'benchmark_depth'], 'type': 'string', 'description': 'Legacy alias for audienceCreationMode — same values, same behaviour. How the Audience is sized. "balanced" (default): compact and representative for everyday research. It is the only mode with a hard wall on a size you state — a memberCount above 20 is refused with 403 MODE_CAP. "segment_coverage": two representatives per limiting grounded cell, from a 10-Mind floor; automatic sizing stops at 50, but a memberCount you state is bounded only by your plan. "benchmark_depth": repeated representation of limiting grounded cells for validation-ready segmentation; bounded by your plan allowance. The deeper two require a Team (enterprise) plan — on other plans the server SILENTLY downgrades to "balanced" and echoes the effective mode in structuredContent.audience.audienceCreationMode. Call get_audience_limits to see the ceilings that apply to your account.'}, 'datasetSegmentation': {'type': 'object', 'required': ['fileName', 'segmentationColumns', 'combinations'], 'properties': {'columns': {'type': 'array', 'items': {'type': 'object', 'required': ['key', 'label', 'distribution'], 'properties': {'key': {'type': 'string'}, 'label': {'type': 'string'}, 'distribution': {'type': 'array', 'items': {'type': 'object', 'required': ['value', 'respondentCount', 'sharePct'], 'properties': {'value': {'type': 'string', 'default': ''}, 'sharePct': {'type': 'number', 'minimum': 0}, 'respondentCount': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': 0}}}, 'maxItems': 30}, 'otherRespondentCount': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': 0}, 'validRespondentCount': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': 0}}}, 'maxItems': 200, 'description': 'Column-level distributions from the preview. Used when `variables` is absent.'}, 'fileName': {'type': 'string'}, 'sheetName': {'type': 'string'}, 'variables': {'type': 'array', 'items': {'type': 'object', 'required': ['key', 'label', 'distribution'], 'properties': {'key': {'type': 'string'}, 'label': {'type': 'string'}, 'distribution': {'type': 'array', 'items': {'type': 'object', 'required': ['value', 'respondentCount', 'sharePct'], 'properties': {'value': {'type': 'string', 'default': ''}, 'sharePct': {'type': 'number', 'minimum': 0}, 'respondentCount': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': 0}}}, 'maxItems': 30}, 'otherRespondentCount': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': 0}, 'validRespondentCount': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': 0}}}, 'maxItems': 200, 'description': 'Variable-level distributions from the preview (preferred over `columns` when present).'}, 'combinations': {'type': 'array', 'items': {'type': 'object', 'required': ['id', 'respondentCount', 'sharePct'], 'properties': {'id': {'type': 'string'}, 'sharePct': {'type': 'number', 'minimum': 0}, 'respondentCount': {'type': 'integer', 'maximum': 9007199254740991, 'exclusiveMinimum': 0}}}, 'maxItems': 5000, 'description': 'Observed joint profiles as audit counts. Copy the ids and counts from the preview; per-cell values are not needed.'}, 'respondentCount': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': 0, 'description': 'Total respondent rows in the reviewed sheet, copied from the preview.'}, 'segmentationColumns': {'type': 'array', 'items': {'type': 'string'}, 'maxItems': 200, 'minItems': 1, 'description': 'Keys of the variables the user kept after review. These are the only ones that shape the cohort.'}, 'recommendedMindCount': {'type': 'integer', 'maximum': 9007199254740991, 'description': 'Preview-recommended cohort size. Caps how many Minds the benchmark run creates.', 'exclusiveMinimum': 0}, 'retainedCombinationIds': {'type': 'array', 'items': {'type': 'string'}, 'maxItems': 5000}}, 'description': 'Reviewed variable roles, distributions, and privacy-safe pairwise relationships returned by preview_audience_dataset_segmentation. Requires audienceCreationMode="benchmark_depth". Structural variables shape one generalizable representative cohort; outcomes remain held out and joint combinations remain audit evidence only. Copy `respondentCount` and `recommendedMindCount` through from the preview — they cap the cohort size.'}, 'audienceCreationMode': {'enum': ['balanced', 'segment_coverage', 'benchmark_depth'], 'type': 'string', 'description': 'How the Audience is sized. "balanced" (default): compact and representative for everyday research. It is the only mode with a hard wall on a size you state — a memberCount above 20 is refused with 403 MODE_CAP. "segment_coverage": two representatives per limiting grounded cell, from a 10-Mind floor; automatic sizing stops at 50, but a memberCount you state is bounded only by your plan. "benchmark_depth": repeated representation of limiting grounded cells for validation-ready segmentation; bounded by your plan allowance. The deeper two require a Team (enterprise) plan — on other plans the server SILENTLY downgrades to "balanced" and echoes the effective mode in structuredContent.audience.audienceCreationMode. Call get_audience_limits to see the ceilings that apply to your account.'}, 'excludeDistributions': {'type': 'array', 'items': {'type': 'string', 'maxLength': 200, 'minLength': 1}, 'maxItems': 200, 'description': 'Exact axis names whose composition quotas should be removed. Age remains as one eligibility range without within-range shares; explicit gender membership remains enforced. Include required eligibility axes in cohortAllocation.distributionNames. Original evidence stays in reviewDistributions.'}, 'isLinkSharingEnabled': {'type': 'boolean', 'default': False, 'description': 'Set true ONLY when the user explicitly asked for a public/shareable link. Defaults to false: the Audience is private to its owner and no share URL is generated. Enabling this publishes the Audience — including its grounding, sources and personas — at a world-readable URL that needs no login. Do not enable it to "be helpful".'}, 'reviewedGroundingJson': {'type': 'string', 'maxLength': 2000000, 'minLength': 1, 'description': 'Exact reviewedGroundingJson returned by groundingPreview or import_audience_sources. Pass it unchanged together with reviewedGroundingSha256 on a re-preview or creation call; the server reuses this reviewed snapshot instead of rerunning grounding research.'}, 'reviewedGroundingSha256': {'type': 'string', 'pattern': '^[0-9a-f]{64}$', 'description': 'SHA-256 returned by the same groundingPreview. Required together with reviewedGroundingJson; any mismatch is rejected before Audience or Mind materialisation.'}}}

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['name'], 'properties': {'name': {'type': 'string', 'minLength': 1, 'description': 'Name for the Study workspace (e.g., "Brand Perception Study", "Q4 Market Research")'}, 'groupIds': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Legacy alias for audienceIds.'}, 'audienceIds': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Preferred field for existing Audience IDs to attach — use list_audiences to find IDs.'}, 'groupConfigs': {'type': 'array', 'items': {'type': 'object', 'properties': {'name': {'type': 'string'}, 'mindIds': {'type': 'array', 'items': {'type': 'string'}}}}, 'description': 'Legacy alias for audienceConfigs.'}, 'audienceConfigs': {'type': 'array', 'items': {'type': 'object', 'properties': {'name': {'type': 'string', 'description': 'Audience name (optional — defaults to "Audience N").'}, 'mindIds': {'type': 'array', 'items': {'type': 'string'}, 'description': 'IDs of existing Minds to add to this Audience.'}}}, 'description': 'Preferred field for new Audiences to create and attach atomically.'}, 'isLinkSharingEnabled': {'type': 'boolean', 'default': False, 'description': 'Set true ONLY when the user explicitly asked for a public/shareable Study link. Defaults to false: the Study is private to its owner and no share URL is generated. Enabling this ALSO publishes every attached Audience and every Mind inside them at world-readable URLs — including pre-existing Audiences passed via audienceIds. Do not enable it to "be helpful".'}}}

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'properties': {'force': {'type': 'boolean', 'description': 'Regenerate instead of returning a cached artifact.'}, 'format': {'enum': ['md', 'markdown', 'pdf', 'docx', 'pptx'], 'type': 'string', 'description': 'Export format: "md" (default), "pdf", "docx", or "pptx"'}, 'groupId': {'type': 'string', 'description': 'Legacy alias for audienceId. Accepted for compatibility.'}, 'groupName': {'type': 'string', 'description': 'Legacy alias for audienceName. Accepted for compatibility.'}, 'audienceId': {'type': 'string', 'description': 'Audience ID (UUID).'}, 'audienceName': {'type': 'string', 'description': 'Audience name (fuzzy matched).'}}}

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['messageId'], 'properties': {'force': {'type': 'boolean', 'description': 'Regenerate the ZIP archive instead of returning the cached artifact.'}, 'panelId': {'type': 'string', 'description': 'Study ID (UUID; legacy wire field name: panelId)'}, 'studyId': {'type': 'string', 'description': 'Study ID (UUID).'}, 'messageId': {'type': 'string', 'minLength': 1, 'description': 'ID of the completed Study result containing the website heatmap. Completed Study results report this identifier when the answer carries a heatmap.'}, 'panelName': {'type': 'string', 'description': 'Study name (fuzzy matched; legacy wire field name: panelName)'}, 'studyName': {'type': 'string', 'description': 'Study name (fuzzy matched).'}}}

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'properties': {'force': {'type': 'boolean', 'description': 'Regenerate instead of returning a cached artifact.'}, 'format': {'enum': ['md', 'markdown', 'pdf', 'docx', 'pptx'], 'type': 'string', 'description': 'Export format: "md" (default) markdown persona profile (returned inline), "pdf" portrait branded profile, "docx" Word document, "pptx" editable branded deck'}, 'mindId': {'type': 'string', 'description': 'Mind ID (UUID)'}, 'mindName': {'type': 'string', 'description': 'Mind name (fuzzy matched)'}}}

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'properties': {'kind': {'enum': ['executive_brief', 'full_report', 'raw_data'], 'type': 'string', 'description': 'Report kind. Defaults to full_report, except CSV/XLS/SAV which default to raw_data.'}, 'force': {'type': 'boolean', 'description': 'Regenerate instead of returning a cached artifact.'}, 'format': {'enum': ['pdf', 'docx', 'pptx', 'csv', 'xls', 'sav', 'md', 'markdown'], 'type': 'string', 'description': 'Export format: "pdf" (default), "docx", "pptx", "csv", "xls", "sav", or "md" (also accepts "markdown"). Executive-summary and full-report PPTX exports use a slide-native 16:9 layout.'}, 'length': {'enum': ['brief', 'standard', 'detailed'], 'type': 'string', 'description': 'Requested report detail for executive_brief and full_report exports.'}, 'panelId': {'type': 'string', 'description': 'Study ID (UUID; legacy wire field name: panelId). Omit both panelId and panelName only when exporting the active Study from this MCP session.'}, 'studyId': {'type': 'string', 'description': 'Study ID (UUID). Omit with studyName to export the active Study.'}, 'panelName': {'type': 'string', 'description': 'Study name (fuzzy matched; legacy wire field name: panelName). Omit both panelName and panelId only when exporting the active Study from this MCP session.'}, 'studyName': {'type': 'string', 'description': 'Study name (fuzzy matched). Omit with studyId to export the active Study.'}, 'scheduledRunId': {'type': 'string', 'description': 'Export only the messages produced by one scheduled run of this Study, instead of the whole timeline. Use the run ID from the Study schedule history.'}}}

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'properties': {'mode': {'enum': ['balanced', 'segment_coverage', 'benchmark_depth'], 'type': 'string', 'description': 'Report only this creation mode. Omit to see every mode.'}}}

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'properties': {'runId': {'type': 'string', 'format': 'uuid', 'pattern': '^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$', 'description': 'Multi-question run ID returned by run_study_questions. Preferred.'}, 'panelId': {'type': 'string', 'format': 'uuid', 'pattern': '^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$', 'description': 'Legacy alias for the Study workspace ID. Accepted for compatibility.'}, 'studyId': {'type': 'string', 'format': 'uuid', 'pattern': '^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$', 'description': 'Study workspace ID (UUID). When panelId is supplied for compatibility, studyId may carry the legacy run identifier.'}, 'panelName': {'type': 'string', 'description': 'Legacy alias for studyName. Accepted for compatibility.'}, 'studyName': {'type': 'string', 'description': 'Study workspace name for fuzzy matching.'}}}

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'properties': {'panelId': {'type': 'string', 'format': 'uuid', 'pattern': '^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$', 'description': 'Study ID (UUID; legacy wire field name: panelId). Omit both panelId and panelName only for the active Study from this MCP session.'}, 'studyId': {'type': 'string', 'format': 'uuid', 'pattern': '^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$', 'description': 'Study ID (UUID). Omit with studyName to use the active Study.'}, 'panelName': {'type': 'string', 'description': 'Study name (fuzzy matched; legacy wire field name: panelName). Omit both panelName and panelId only for the active Study from this MCP session.'}, 'studyName': {'type': 'string', 'description': 'Study name (fuzzy matched). Omit with studyId to use the active Study.'}, 'exportKind': {'enum': ['executive_brief', 'full_report', 'raw_data'], 'type': 'string', 'description': 'Asynchronous export kind whose status should be returned (defaults to full_report).'}, 'exportJobId': {'type': 'string', 'minLength': 1, 'description': 'Export job ID returned by export_study. Pass it with exportKind and exportFormat to poll that exact artifact.'}, 'exportFormat': {'enum': ['pdf', 'html', 'png', 'docx', 'pptx', 'csv', 'xls', 'sav', 'md'], 'type': 'string', 'description': 'Asynchronous export format whose status should be returned (defaults to pdf). HTML and PNG are accepted here only to finish polling previously created executive-summary jobs.'}}}

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'properties': {'force': {'type': 'boolean', 'default': False, 'description': 'Regenerate even when the covered message range is unchanged.'}, 'length': {'enum': ['short', 'standard', 'detailed'], 'type': 'string', 'default': 'standard'}, 'panelId': {'type': 'string', 'format': 'uuid', 'pattern': '^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$', 'description': 'Study ID (UUID; legacy wire field name: panelId). Omit both panelId and panelName only for the active Study from this MCP session.'}, 'refresh': {'type': 'boolean', 'default': False, 'description': 'Generate or refresh the summary instead of only reading the persisted summary.'}, 'studyId': {'type': 'string', 'format': 'uuid', 'pattern': '^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$', 'description': 'Study ID (UUID). Omit with studyName to use the active Study.'}, 'panelName': {'type': 'string', 'description': 'Study name for fuzzy matching (legacy wire field name: panelName). Omit both panelName and panelId only for the active Study from this MCP session.'}, 'studyName': {'type': 'string', 'description': 'Study name for fuzzy matching. Omit with studyId to use the active Study.'}}}

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'properties': {'files': {'type': 'array', 'items': {'type': 'object', 'required': ['name', 'content'], 'properties': {'name': {'type': 'string', 'pattern': '\\.(txt|md|csv|json)$', 'maxLength': 200, 'minLength': 1}, 'content': {'type': 'string', 'maxLength': 5242880, 'minLength': 1}}, 'additionalProperties': False}, 'default': [], 'maxItems': 20}, 'existingFiles': {'type': 'array', 'items': {'type': 'object', 'required': ['name', 'url'], 'properties': {'url': {'type': 'string', 'maxLength': 2000, 'minLength': 1}, 'name': {'type': 'string', 'maxLength': 200, 'minLength': 1}}, 'additionalProperties': False}, 'default': [], 'maxItems': 20}, 'groundingJson': {'type': 'string', 'maxLength': 2000000, 'minLength': 1, 'description': 'Optional explicitly supplied distribution JSON (the grounding object, not respondent rows). Sources are bound to the files in request order: existingFiles followed by files. Import does not assert independent verification of the supplied percentages.'}}, 'additionalProperties': False}

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'properties': {'searchQuery': {'type': 'string', 'description': 'Search for an Audience by name (fuzzy matching supported)'}}}

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'properties': {'cursor': {'type': 'string', 'format': 'uuid', 'pattern': '^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$', 'description': 'Next-page cursor from a prior result.'}}}

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'properties': {'includePlanned': {'type': 'boolean', 'default': True, 'description': 'Include methods that are currently planned/non-executable so the model can explain framework compatibility. Availability is dynamic; only entries with executable:true can run.'}}}

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'properties': {'searchQuery': {'type': 'string', 'description': 'Search for a Study by name (fuzzy matching supported)'}}}

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'properties': {'draftId': {'type': 'string', 'format': 'uuid', 'pattern': '^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$', 'description': 'Exact study draft ID to retrieve. Omit to list all resumable study drafts owned by the authenticated user.'}}}

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'properties': {'templateId': {'type': 'string', 'format': 'uuid', 'pattern': '^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$', 'description': 'Omit to list your own and team-shared Study templates.'}}}

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['action'], 'properties': {'use': {'type': 'object', 'required': ['expectedRevision', 'requestId'], 'properties': {'requestId': {'type': 'string', 'format': 'uuid', 'pattern': '^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$'}, 'expectedRevision': {'type': 'integer', 'maximum': 9007199254740991, 'exclusiveMinimum': 0}}, 'additionalProperties': False}, 'save': {'type': 'object', 'required': ['name', 'configuration'], 'properties': {'name': {'type': 'string', 'maxLength': 200, 'minLength': 1}, 'requestId': {'type': 'string', 'format': 'uuid', 'pattern': '^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$'}, 'configuration': {'type': 'object', 'required': ['version', 'goal', 'studyLocale', 'questions', 'methodId'], 'properties': {'goal': {'enum': ['concept', 'comparison', 'website', 'pricing', 'market', 'explore'], 'type': 'string'}, 'version': {'type': 'number', 'const': 1}, 'methodId': {'type': 'string', 'const': 'guided-research'}, 'questions': {'type': 'array', 'items': {'type': 'object', 'required': ['text', 'response'], 'properties': {'text': {'type': 'string', 'maxLength': 20000, 'minLength': 1}, 'response': {'type': 'object', 'required': ['type'], 'properties': {'type': {'enum': ['qualitative', 'categorical', 'multiselect', 'scale'], 'type': 'string'}, 'scaleRange': {'type': 'array', 'items': {'type': 'number'}, 'maxItems': 2, 'minItems': 2}, 'maxSelections': {'type': 'integer', 'maximum': 9007199254740991, 'exclusiveMinimum': 0}, 'categoricalOptions': {'type': 'array', 'items': {'type': 'string', 'maxLength': 2000, 'minLength': 1}, 'maxItems': 100}}, 'additionalProperties': False}, 'attachments': {'type': 'array', 'items': {'type': 'object', 'required': ['id', 'name', 'url'], 'properties': {'id': {'type': 'string', 'maxLength': 200, 'minLength': 1}, 'url': {'type': 'string', 'maxLength': 4000, 'minLength': 1}, 'kind': {'type': 'string', 'const': 'link'}, 'name': {'type': 'string', 'maxLength': 500, 'minLength': 1}, 'path': {'type': 'string', 'maxLength': 2000}, 'mimeType': {'type': 'string', 'maxLength': 200}, 'mediaType': {'type': 'string', 'const': 'video'}, 'sizeBytes': {'type': 'number', 'minimum': 0}}, 'additionalProperties': False}, 'default': [], 'maxItems': 30}}, 'additionalProperties': False}, 'maxItems': 200, 'minItems': 1}, 'studyLocale': {'enum': ['ar', 'de', 'en', 'es', 'fr', 'ja', 'ko', 'tr', 'zh'], 'type': 'string'}}, 'additionalProperties': False}}, 'additionalProperties': False}, 'action': {'enum': ['save', 'update', 'use', 'delete'], 'type': 'string'}, 'update': {'type': 'object', 'required': ['expectedRevision'], 'properties': {'name': {'type': 'string', 'maxLength': 200, 'minLength': 1}, 'configuration': {'type': 'object', 'required': ['version', 'goal', 'studyLocale', 'questions', 'methodId'], 'properties': {'goal': {'enum': ['concept', 'comparison', 'website', 'pricing', 'market', 'explore'], 'type': 'string'}, 'version': {'type': 'number', 'const': 1}, 'methodId': {'type': 'string', 'const': 'guided-research'}, 'questions': {'type': 'array', 'items': {'type': 'object', 'required': ['text', 'response'], 'properties': {'text': {'type': 'string', 'maxLength': 20000, 'minLength': 1}, 'response': {'type': 'object', 'required': ['type'], 'properties': {'type': {'enum': ['qualitative', 'categorical', 'multiselect', 'scale'], 'type': 'string'}, 'scaleRange': {'type': 'array', 'items': {'type': 'number'}, 'maxItems': 2, 'minItems': 2}, 'maxSelections': {'type': 'integer', 'maximum': 9007199254740991, 'exclusiveMinimum': 0}, 'categoricalOptions': {'type': 'array', 'items': {'type': 'string', 'maxLength': 2000, 'minLength': 1}, 'maxItems': 100}}, 'additionalProperties': False}, 'attachments': {'type': 'array', 'items': {'type': 'object', 'required': ['id', 'name', 'url'], 'properties': {'id': {'type': 'string', 'maxLength': 200, 'minLength': 1}, 'url': {'type': 'string', 'maxLength': 4000, 'minLength': 1}, 'kind': {'type': 'string', 'const': 'link'}, 'name': {'type': 'string', 'maxLength': 500, 'minLength': 1}, 'path': {'type': 'string', 'maxLength': 2000}, 'mimeType': {'type': 'string', 'maxLength': 200}, 'mediaType': {'type': 'string', 'const': 'video'}, 'sizeBytes': {'type': 'number', 'minimum': 0}}, 'additionalProperties': False}, 'default': [], 'maxItems': 30}}, 'additionalProperties': False}, 'maxItems': 200, 'minItems': 1}, 'studyLocale': {'enum': ['ar', 'de', 'en', 'es', 'fr', 'ja', 'ko', 'tr', 'zh'], 'type': 'string'}}, 'additionalProperties': False}, 'expectedRevision': {'type': 'integer', 'maximum': 9007199254740991, 'exclusiveMinimum': 0}, 'isSharedWithTeam': {'type': 'boolean'}}, 'additionalProperties': False}, 'templateId': {'type': 'string', 'format': 'uuid', 'pattern': '^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$'}}}

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'properties': {'edits': {'type': 'object', 'properties': {'objective': {'type': 'string', 'maxLength': 2000, 'minLength': 1}, 'questions': {'type': 'array', 'items': {'type': 'object', 'required': ['id', 'moduleId', 'text', 'response'], 'properties': {'id': {'type': 'string', 'pattern': '^[a-z0-9_-]+$', 'maxLength': 80, 'minLength': 1}, 'text': {'type': 'string', 'maxLength': 2000, 'minLength': 1}, 'moduleId': {'type': 'string', 'maxLength': 120, 'minLength': 1}, 'response': {'type': 'object', 'required': ['type'], 'properties': {'type': {'enum': ['qualitative', 'categorical', 'multiselect', 'scale'], 'type': 'string'}, 'scaleRange': {'type': 'array', 'items': {'type': 'integer', 'maximum': 100, 'minimum': -100}, 'maxItems': 2, 'minItems': 2}, 'maxSelections': {'type': 'integer', 'maximum': 100, 'minimum': 1}, 'categoricalOptions': {'type': 'array', 'items': {'type': 'string', 'minLength': 1}, 'maxItems': 100, 'minItems': 2}}, 'additionalProperties': False}, 'attachmentIds': {'type': 'array', 'items': {'type': 'string', 'maxLength': 255, 'minLength': 1}, 'maxItems': 50}}, 'additionalProperties': False}, 'maxItems': 200, 'minItems': 1}, 'promptContent': {'type': 'string', 'maxLength': 20000}}, 'description': 'Save exact edits to draftPlanId and revision without a model call. Preserves method configuration, source policy, item IDs and exact wording. Questions are the complete selected instrument in module order; method-specific batteries are read-only. Cannot combine with planner inputs.', 'additionalProperties': False}, 'source': {'type': 'object', 'required': ['kind', 'label'], 'properties': {'url': {'type': 'string', 'minLength': 1, 'description': 'Fetchable source URL. MCP cannot read or upload a local file:// path. Use a fetchable HTTP(S) URL, a signed URL supplied by the client for the attached file, or an existing Minds workspace upload URL/path. Study tools import external file URLs into durable Minds storage before saving or running. A workspace upload reused as a Study asset must sit under chat/<userId>/: request the signed upload with folder "chat" and pass that storage path or its /api/uploads/chat/ URL. A temp/, portfolio/, or context/ path — and any /api/uploads/file-access/ URL — is refused as not belonging to the workspace owner and is never re-fetched; pass a plain external URL instead. The Study refuses to start if Minds cannot read the asset.'}, 'kind': {'enum': ['prompt', 'website', 'image', 'video', 'document', 'questionnaire', 'other'], 'type': 'string'}, 'label': {'type': 'string', 'minLength': 1}, 'content': {'type': 'string', 'maxLength': 20000, 'minLength': 1, 'description': 'Exact respondent-visible pasted text. Use only with kind prompt when Minds must evaluate a concept, message, description, or other text. Do not include planner-only instructions.'}, 'mimeType': {'type': 'string'}}, 'description': 'The one main source this study is about. When Minds must evaluate pasted text, use kind prompt and put the exact respondent-visible material in content. Keep research objectives, requested questions, and planner-only instructions in request. MCP cannot read or upload a local file:// path. Use a fetchable HTTP(S) URL, a signed URL supplied by the client for the attached file, or an existing Minds workspace upload URL/path. Study tools import external file URLs into durable Minds storage before saving or running. A workspace upload reused as a Study asset must sit under chat/<userId>/: request the signed upload with folder "chat" and pass that storage path or its /api/uploads/chat/ URL. A temp/, portfolio/, or context/ path — and any /api/uploads/file-access/ URL — is refused as not belonging to the workspace owner and is never re-fetched; pass a plain external URL instead. The Study refuses to start if Minds cannot read the asset.'}, 'answers': {'type': 'array', 'items': {'type': 'object', 'required': ['questionId', 'answer'], 'properties': {'answer': {'type': 'string', 'description': "The user's answer to that confirmation question."}, 'questionId': {'type': 'string', 'minLength': 1, 'description': 'Confirmation question ID from the latest draft.'}}, 'additionalProperties': False}, 'description': 'Answers to the draft confirmation questions.'}, 'panelId': {'type': 'string', 'format': 'uuid', 'pattern': '^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$', 'description': 'Study ID (UUID; legacy wire field name: panelId). Omit both panelId and panelName only to continue the active Study from this MCP session.'}, 'request': {'type': 'string', 'minLength': 1, 'description': 'Planner input containing the research objective, questionnaire, survey, battery, section, cohesive question set, audit request, or analysis request. Required for a new draft. Include EVERY question already known in this one request so the planner can group the complete set into cohesive named modules for one confirmed multi-question run inside the Study; never create one planning request per known question. This request is not sent verbatim to Minds; the exact proposed respondent-visible questions are returned in the draft for review.'}, 'studyId': {'type': 'string', 'format': 'uuid', 'pattern': '^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$', 'description': 'Study ID (UUID). Omit with studyName to continue the active Study.'}, 'revision': {'type': 'integer', 'maximum': 9007199254740991, 'description': 'Current draft revision; required with draftPlanId.', 'exclusiveMinimum': 0}, 'panelName': {'type': 'string', 'description': 'Study name for fuzzy matching (legacy wire field name: panelName). Omit both panelName and panelId only to continue the active Study from this MCP session.'}, 'questions': {'type': 'array', 'items': {'type': 'object', 'required': ['text', 'response'], 'properties': {'id': {'type': 'string', 'maxLength': 80, 'minLength': 1, 'description': 'Stable item id (lower-cased to a slug). Defaults to q<position>.'}, 'text': {'type': 'string', 'maxLength': 2000, 'minLength': 1, 'description': 'Exact respondent-visible question text, including any anchors or labels. Stored as given.'}, 'module': {'type': 'string', 'maxLength': 200, 'minLength': 1, 'description': 'Optional module (battery) label. Consecutive questions with the same label form one module.'}, 'response': {'type': 'object', 'required': ['type'], 'properties': {'type': {'enum': ['qualitative', 'categorical', 'multiselect', 'scale'], 'type': 'string'}, 'scaleRange': {'type': 'array', 'items': {'type': 'integer', 'maximum': 100, 'minimum': -100}, 'maxItems': 2, 'minItems': 2, 'description': 'Inclusive integer response range as [minimum, maximum]; required for scale responses.'}, 'maxSelections': {'type': 'integer', 'maximum': 100, 'minimum': 1, 'description': 'Maximum choices a respondent may select; only valid for multiselect responses.'}, 'categoricalOptions': {'type': 'array', 'items': {'type': 'string', 'minLength': 1}, 'maxItems': 100, 'minItems': 2, 'description': 'Predefined answer choices; only valid for categorical or multiselect responses.'}}, 'description': 'Exact execution contract for this item: type qualitative, categorical (with categoricalOptions), multiselect, or scale (with inclusive integer scaleRange). Supplied categoricalOptions keep their exact labels and order even with attachments; files are evidence and do not generate replacement A/B options.', 'additionalProperties': False}}, 'additionalProperties': False}, 'maxItems': 200, 'minItems': 1, 'description': 'Fixed instrument: use INSTEAD of request when the user supplies a pre-registered or fixed questionnaire whose wording, order, and response formats must not change. The planner is bypassed; every question is stored verbatim, in this order, with exactly this response contract. Cannot be combined with refinement, answers, questionResponses, or suggestQuestionStimuli. Repeated question texts or colliding ids are rejected.'}, 'studyName': {'type': 'string', 'description': 'Study name for fuzzy matching. Omit with studyId to continue the active Study.'}, 'loadLatest': {'type': 'boolean', 'description': 'Read the latest saved revision of draftPlanId, without generating, saving or executing. Do not combine with edits or planner inputs.'}, 'refinement': {'type': 'string', 'description': 'How the user wants the existing draft changed.'}, 'attachments': {'type': 'array', 'items': {'type': 'object', 'properties': {'id': {'type': 'string', 'maxLength': 255, 'minLength': 1, 'description': 'Stable asset ID used by questionAttachments to assign this file to specific planned questions.'}, 'url': {'type': 'string', 'minLength': 1, 'description': 'Fetchable HTTP(S), signed, or Minds workspace upload URL. MCP cannot read or upload a local file:// path. Use a fetchable HTTP(S) URL, a signed URL supplied by the client for the attached file, or an existing Minds workspace upload URL/path. Study tools import external file URLs into durable Minds storage before saving or running. A workspace upload reused as a Study asset must sit under chat/<userId>/: request the signed upload with folder "chat" and pass that storage path or its /api/uploads/chat/ URL. A temp/, portfolio/, or context/ path — and any /api/uploads/file-access/ URL — is refused as not belonging to the workspace owner and is never re-fetched; pass a plain external URL instead. The Study refuses to start if Minds cannot read the asset.'}, 'kind': {'type': 'string', 'const': 'website', 'description': 'Use website for a page to read as a website rather than download as a file.'}, 'name': {'type': 'string', 'minLength': 1, 'description': 'File name visible in the Study.'}, 'path': {'type': 'string', 'minLength': 1, 'description': 'Storage path of a file already uploaded to Minds. MCP cannot read or upload a local file:// path. Use a fetchable HTTP(S) URL, a signed URL supplied by the client for the attached file, or an existing Minds workspace upload URL/path. Study tools import external file URLs into durable Minds storage before saving or running. A workspace upload reused as a Study asset must sit under chat/<userId>/: request the signed upload with folder "chat" and pass that storage path or its /api/uploads/chat/ URL. A temp/, portfolio/, or context/ path — and any /api/uploads/file-access/ URL — is refused as not belonging to the workspace owner and is never re-fetched; pass a plain external URL instead. The Study refuses to start if Minds cannot read the asset.'}, 'type': {'type': 'string', 'minLength': 1, 'description': 'MIME type when known.'}, 'mimeType': {'type': 'string', 'maxLength': 255}}}, 'maxItems': 100, 'description': 'Files and websites available to the planned Study (one question block, at most 100). With multiple assets, every question needs an explicit assignment and every asset must be used by at least one question. Use [] for no assets. Give each scoped file a stable id. Remote URLs are copied into durable Minds storage before the draft is saved. MCP cannot read or upload a local file:// path. Use a fetchable HTTP(S) URL, a signed URL supplied by the client for the attached file, or an existing Minds workspace upload URL/path. Study tools import external file URLs into durable Minds storage before saving or running. A workspace upload reused as a Study asset must sit under chat/<userId>/: request the signed upload with folder "chat" and pass that storage path or its /api/uploads/chat/ URL. A temp/, portfolio/, or context/ path — and any /api/uploads/file-access/ URL — is refused as not belonging to the workspace owner and is never re-fetched; pass a plain external URL instead. The Study refuses to start if Minds cannot read the asset.'}, 'draftPlanId': {'type': 'string', 'format': 'uuid', 'pattern': '^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$', 'description': 'Existing draft ID to revise after the user answers a confirmation question.'}, 'studyLocale': {'enum': ['en', 'es', 'fr', 'de', 'zh', 'tr', 'ar', 'ja', 'ko'], 'type': 'string', 'description': 'Language for the plan, questions, responses, labels, and summary. Set this explicitly when the user requests a language.'}, 'sourcePolicy': {'enum': ['request_only', 'auto'], 'type': 'string', 'description': 'Evidence policy stored in the draft and reviewed before execution. Defaults to request_only for a controlled Study. Use auto only for an explicitly designed experiment that should allow relevant Mind-knowledge retrieval; response-mode rules still control live web search.'}, 'idempotencyKey': {'type': 'string', 'maxLength': 200, 'minLength': 1, 'description': 'Optional stable retry key. When omitted the tool derives one from its own arguments, so a repeated identical call (including a host retry after a timeout) returns the draft revision that was already saved instead of planning again. Pass a fresh key to force a new plan for identical input.'}, 'questionResponses': {'type': 'array', 'items': {'type': 'object', 'required': ['questionId', 'type'], 'properties': {'type': {'enum': ['qualitative', 'categorical', 'multiselect', 'scale'], 'type': 'string'}, 'questionId': {'type': 'string', 'maxLength': 80, 'minLength': 1, 'description': 'Question ID from the latest draft plan.'}, 'scaleRange': {'type': 'array', 'items': {'type': 'integer', 'maximum': 100, 'minimum': -100}, 'maxItems': 2, 'minItems': 2, 'description': 'Inclusive integer response range as [minimum, maximum]; required for scale responses.'}, 'maxSelections': {'type': 'integer', 'maximum': 100, 'minimum': 1, 'description': 'Maximum choices a respondent may select; only valid for multiselect responses.'}, 'categoricalOptions': {'type': 'array', 'items': {'type': 'string', 'minLength': 1}, 'maxItems': 100, 'minItems': 2, 'description': 'Predefined answer choices; only valid for categorical or multiselect responses.'}}, 'additionalProperties': False}, 'description': 'Explicit response-format edits, one entry per question. Each entry needs questionId (from the latest draft) plus type qualitative, categorical, multiselect, or scale with an inclusive integer scaleRange.'}, 'questionAttachments': {'type': 'array', 'items': {'type': 'object', 'required': ['questionNumber', 'attachmentIds'], 'properties': {'attachmentIds': {'type': 'array', 'items': {'type': 'string', 'maxLength': 255, 'minLength': 1}, 'maxItems': 20, 'description': 'Stable ids from attachments that this question alone receives (at most 20).'}, 'questionNumber': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': 1, 'description': 'One-based question position in the returned plan, across modules in order.'}}, 'additionalProperties': False}, 'minItems': 1, 'description': 'Question-to-file mapping. Multi-asset blocks require every question to be mapped, using [] for no assets; every asset must appear on at least one question. Each question at most once; every referenced attachment id must resolve.'}, 'suggestQuestionStimuli': {'type': 'boolean', 'description': 'Default true. Lets the planner assign each attached file or website to one or more questions (attachmentIds on those questions). Pass false to leave questions unassigned unless questionAttachments names them.'}, 'mindSourcePolicyOverrides': {'type': 'array', 'items': {'type': 'object', 'required': ['mindId', 'sourcePolicy'], 'properties': {'mindId': {'type': 'string', 'format': 'uuid', 'pattern': '^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$', 'description': 'Exact Mind UUID in the Study cohort.'}, 'sourcePolicy': {'enum': ['request_only', 'auto'], 'type': 'string', 'description': 'Request-scoped evidence treatment for this Mind.'}}, 'additionalProperties': False}, 'maxItems': 2000, 'description': 'Experimental per-Mind treatment assignments stored in the exact draft revision. Each Mind may appear once; unlisted Minds use sourcePolicy. Use only for a preregistered source-policy experiment.'}}}

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['draftPlanId', 'revision', 'confirmed'], 'properties': {'panelId': {'type': 'string', 'format': 'uuid', 'pattern': '^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$', 'description': 'Study ID (UUID; legacy wire field name: panelId). Omit both panelId and panelName only to run the confirmed draft in the active Study from this MCP session.'}, 'studyId': {'type': 'string', 'format': 'uuid', 'pattern': '^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$', 'description': 'Study ID (UUID). Omit with studyName to run in the active Study.'}, 'groupIds': {'type': 'array', 'items': {'type': 'string', 'format': 'uuid', 'pattern': '^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$'}, 'description': 'Legacy alias for audienceIds. Accepted for compatibility.'}, 'revision': {'type': 'integer', 'maximum': 9007199254740991, 'description': 'Exact draft revision the user reviewed.', 'exclusiveMinimum': 0}, 'confirmed': {'type': 'boolean', 'const': True, 'description': 'Must be true only after the user explicitly confirms this exact draft revision.'}, 'panelName': {'type': 'string', 'description': 'Study name for fuzzy matching (legacy wire field name: panelName). Omit both panelName and panelId only to run the confirmed draft in the active Study from this MCP session.'}, 'studyName': {'type': 'string', 'description': 'Study name for fuzzy matching. Omit with studyId to run in the active Study.'}, 'audienceIds': {'type': 'array', 'items': {'type': 'string', 'format': 'uuid', 'pattern': '^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$'}, 'description': "Optional subset of the Study's Audiences to include."}, 'draftPlanId': {'type': 'string', 'format': 'uuid', 'pattern': '^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$', 'description': 'Exact draft plan ID returned by plan_study_questions.'}, 'idempotencyKey': {'type': 'string', 'format': 'uuid', 'pattern': '^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$', 'description': 'Stable UUID for safe retries.'}, 'modelConnection': {'type': 'object', 'required': ['id', 'revision'], 'properties': {'id': {'type': 'string', 'format': 'uuid', 'pattern': '^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$'}, 'revision': {'type': 'integer', 'maximum': 9007199254740991, 'exclusiveMinimum': 0}}, 'description': 'Verified caller-team connection for Mind answers and verbatim rendering. Select only when the user requests it; confirmation pins this connection revision, and retries must keep it. Supporting analysis retains platform models.', 'additionalProperties': False}, 'advancedMethodOptIn': {'type': 'boolean', 'description': 'Explicit opt-in for an advanced method. Omit or false to keep simple methods.'}}}

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'properties': {'mode': {'enum': ['quick', 'custom'], 'type': 'string', 'default': 'custom', 'description': 'Planning mode to restore. Defaults to custom for agent-authored planning state.'}, 'name': {'type': 'string', 'maxLength': 200, 'minLength': 1, 'description': 'Sidebar name for the Study draft.'}, 'notes': {'type': 'string', 'description': 'Additional research context or constraints.'}, 'draftId': {'type': 'string', 'format': 'uuid', 'pattern': '^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$', 'description': 'Existing Study draft ID to revise. Omit to create a new durable draft.'}, 'website': {'type': 'string', 'format': 'uri', 'description': 'Primary website associated with the research context.'}, 'groupIds': {'type': 'array', 'items': {'type': 'string', 'format': 'uuid', 'pattern': '^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$'}, 'description': 'Legacy alias for audienceIds. Accepted for compatibility.'}, 'methodId': {'enum': ['guided-research', 'single-question', 'questionnaire', 'guided-qualitative-exploration', 'ranked-preferences', 'segment-comparison', 'visual-asset-analysis', 'recommendation-synthesis', 'maxdiff', 'conjoint', 'nps', 'top-box', 'key-drivers', 'turf', 'gabor-granger', 'van-westendorp', 'kano'], 'type': 'string', 'default': 'guided-research', 'description': 'Research method selected for the draft. Use list_research_methods as the availability authority.'}, 'objective': {'type': 'string', 'description': 'Research objective or intent captured so far.'}, 'questions': {'type': 'array', 'items': {'type': 'string', 'minLength': 1}, 'default': [], 'description': 'Manual research questions in their intended order.'}, 'sourceUrls': {'type': 'array', 'items': {'type': 'string', 'format': 'uri'}, 'default': [], 'description': 'Ordered source URLs supplied as Study context.'}, 'audienceIds': {'type': 'array', 'items': {'type': 'string', 'format': 'uuid', 'pattern': '^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$'}, 'description': 'Existing Audience IDs selected for the Study. Preferred.'}, 'currentStep': {'type': 'string', 'default': 'context', 'maxLength': 100, 'minLength': 1, 'description': 'Exact planner step to reopen, such as context, audiences, method, questions, or confirm. The legacy value groups remains accepted when reopening an older draft.'}, 'expectedRevision': {'type': 'integer', 'maximum': 9007199254740991, 'description': 'Exact current revision. Required with draftId so stale updates cannot overwrite newer planning state.', 'exclusiveMinimum': 0}}}

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['messageId'], 'properties': {'action': {'enum': ['get', 'start'], 'type': 'string', 'default': 'get'}, 'studyId': {'type': 'string'}, 'assetKey': {'type': 'string', 'minLength': 1}, 'messageId': {'type': 'string', 'minLength': 1}, 'studyName': {'type': 'string'}}}