Minds: Synthetic Market Research

Ask One Standalone Audience Question

ask_audience

Asks exactly one standalone question of one existing Audience. It creates a private Study for that Audience, starts asynchronous answers from its Minds, and returns the Study identifier and its links.

The server may reword a context-dependent question. The accepted task and its answer contract are returned with the original request. Ambiguous requests or generated questions return planning_required before execution.

Out of scope: a questionnaire, battery, section or any request with two or more known questions. That complete set runs as one planned multi-question block inside a Study.

Attachments can be URLs, Minds uploads or files shared in the conversation (uploaded or generated images, PDFs).

Input Schema

TableJSON Schema

Name	Required	Description
`name`	No	Optional name for the Study created to ask this question. Defaults to the Audience name.
`audience`	No	Which Audience to ask. Give the id when known, otherwise the name.
`question`	Yes	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 question and the instructions the Minds should receive. Material the question is about (a pasted newsletter, email, ad copy or concept text) goes in textAttachments, verbatim, not here. Never place planner-only or MCP-client orchestration instructions here. If the question offers a fixed set of answer options, say so in the text as the respondent would read it. The research reader identifies the question and its answer contract together. Include the complete authored labels, ordering and selection instructions. Numbered answer options do not by themselves make a request a multi-question battery. An invalid or ambiguous reading stops for retry or planning before execution.
`attachments`	No	Files/images processed once and given to every Audience member as context. Accepts a public HTTP(S) URL or a file already in the user's Minds uploads under chat/<userId>/ (its storage path or its /api/uploads/chat/ URL). MCP cannot read a local path. Files shared in the conversation (uploaded or generated images, PDFs, documents) go in the tool's top-level conversationFiles field where the tool has one; elsewhere a PDF or image without a public URL has no MCP route and is uploaded in the Minds app first. Plain text contents (UTF-8 text, Markdown, CSV, JSON) can go to import_audience_sources. External URLs are copied into Minds storage before a Study is saved or run. temp/, portfolio/ and context/ paths and /api/uploads/file-access/ URLs belong to other owners and are not accepted. A Study does not start until Minds can read every file.
`textAttachments`	No	Pasted material the question is about: a newsletter, an email, ad copy, a concept or any other text the user shared and wants the Minds to react to. Put it here verbatim, one entry per piece, instead of inside the question. Each entry is stored as a Markdown file and given to the Minds like an uploaded attachment; a brief or background note sent here is read as such and not shown to them.
`conversationFiles`	No	Stimulus files given to every Audience member, alongside any attachments. Files shared in this conversation: uploaded or generated images, PDFs, documents. Each is copied into Minds storage on receipt; its file_id is its attachment id.

Output Schema

TableJSON Schema

Name	Required	Description
`runId`	No	Durable run identifier.
`locale`	No	Study display locale.
`status`	No	queued once submitted, or planning_required when the request needs a reviewed multi-question plan (nothing was submitted).
`apiBase`	No	Minds base URL.
`studyId`	No	Study the question was asked in.
`question`	No	The submitted question.
`planLimit`	No	Present when a plan limit refused, truncated or stopped Study work.
`questionId`	No	Identifier of this question; pass it to get_study_status to follow only this question.
`waitingFor`	No	Present when the question is queued behind Minds still training: how many it waits for. It starts once they are ready; nothing has been answered yet.
`workspaceUrl`	No	Authenticated Minds workspace link for the Study.
`sharedStudyUrl`	No	Public share link, or null when link sharing is off.
`executionStarted`	No	False when nothing was submitted.
`proposedQuestions`	No	For planning_required: the respondent questions detected or proposed.

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedOct 13, 2026

changedInput schema / properties / question / description

Previous value: -"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. If the question offers a fixed set of answer options, say so in the text as the respondent would read it. The research reader identifies the question and its answer contract together. Include the complete authored labels, ordering and selection instructions. Numbered answer options do not by themselves make a request a multi-question battery. An invalid or ambiguous reading stops for retry or planning before execution."New value: +"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 question and the instructions the Minds should receive. Material the question is about (a pasted newsletter, email, ad copy or concept text) goes in textAttachments, verbatim, not here. Never place planner-only or MCP-client orchestration instructions here. If the question offers a fixed set of answer options, say so in the text as the respondent would read it. The research reader identifies the question and its answer contract together. Include the complete authored labels, ordering and selection instructions. Numbered answer options do not by themselves make a request a multi-question battery. An invalid or ambiguous reading stops for retry or planning before execution."

addedInput schema / properties / textAttachments

Added value: +{
+  "description": "Pasted material the question is about: a newsletter, an email, ad copy, a concept or any other text the user shared and wants the Minds to react to. Put it here verbatim, one entry per piece, instead of inside the question. Each entry is stored as a Markdown file and given to the Minds like an uploaded attachment; a brief or background note sent here is read as such and not shown to them.",
+  "items": {
+    "properties": {
+      "name": {
+        "description": "Short file name for the material, for example \"newsletter-october\". Optional.",
+        "maxLength": 200,
+        "type": "string"
+      },
+      "text": {
+        "description": "The material, exactly as the user shared it.",
+        "minLength": 1,
+        "type": "string"
+      }
+    },
+    "required": [
+      "text"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}

Changed1 schema field changedOct 11, 2026

addedOutput schema / properties / waitingFor

Added value: +{
+  "description": "Present when the question is queued behind Minds still training: how many it waits for. It starts once they are ready; nothing has been answered yet.",
+  "type": [
+    "number",
+    "null"
+  ]
+}

Changed1 schema field changedOct 10, 2026

changedOutput schema / properties / planLimit / anyOf

Previous value: -[
-  {
-    "additionalProperties": {},
-    "properties": {
-      "executionStarted": {
-        "description": "Whether any question of this request ran.",
-        "type": [
-          "boolean",
-          "null"
-        ]
-      },
-      "kind": {
-        "description": "study_answers (Free plan monthly Study answers) or response_credits (synthetic-response allowance).",
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "limit": {
-        "description": "Allowance of the current period, when known.",
-        "type": [
-          "number",
-          "null"
-        ]
-      },
-      "message": {
-        "description": "One user-facing sentence with the link(s).",
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "outcome": {
-        "description": "refused (nothing started or charged), partial (only the first questions run), stopped (a run stopped at the limit), or resume_refused.",
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "periodEnd": {
-        "description": "When the allowance renews (ISO 8601), when known.",
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "remaining": {
-        "description": "Allowance left, when known.",
-        "type": [
-          "number",
-          "null"
-        ]
-      },
-      "requested": {
-        "description": "Responses or answers the refused work needed, when known.",
-        "type": [
-          "number",
-          "null"
-        ]
-      },
-      "responseCreditsUrl": {
-        "description": "Absolute link to buy response credits; only for response_credits.",
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "resumable": {
-        "description": "True when the run can be continued in place with resume_study_run runId once the plan allows it.",
-        "type": [
-          "boolean",
-          "null"
-        ]
-      },
-      "runId": {
-        "description": "The run concerned, when one exists.",
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "skippedQuestionCount": {
-        "description": "Questions the limit kept from running.",
-        "type": [
-          "number",
-          "null"
-        ]
-      },
-      "skippedQuestions": {
-        "anyOf": [
-          {
-            "items": {},
-            "type": "array"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "description": "Questions not asked: { index (zero-based), text }."
-      },
-      "totalQuestionCount": {
-        "description": "Questions in the request or run, when known.",
-        "type": [
-          "number",
-          "null"
-        ]
-      },
-      "upgradeUrl": {
-        "description": "Absolute link to the Minds plans page.",
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "used": {
-        "description": "Allowance used in the current period, when known.",
-        "type": [
-          "number",
-          "null"
-        ]
-      }
-    },
-    "type": "object"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "additionalProperties": {},
+    "properties": {
+      "billingMode": {
+        "description": "prepaid (purchased response balance) or subscription (recurring allowance), when known.",
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "context": {
+        "description": "sharedStudyUsage or sharedMindUsage when the owner pays for the refused work.",
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "executionStarted": {
+        "description": "Whether any question of this request ran.",
+        "type": [
+          "boolean",
+          "null"
+        ]
+      },
+      "kind": {
+        "description": "study_answers (Free plan monthly Study answers) or response_credits (synthetic-response allowance).",
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "limit": {
+        "description": "Allowance of the current period, when known.",
+        "type": [
+          "number",
+          "null"
+        ]
+      },
+      "message": {
+        "description": "One user-facing sentence with the link(s).",
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "outcome": {
+        "description": "refused (nothing started or charged), partial (only the first questions run), stopped (a run stopped at the limit), or resume_refused.",
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "periodEnd": {
+        "description": "When the allowance renews (ISO 8601), when known.",
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "remaining": {
+        "description": "Allowance left, when known.",
+        "type": [
+          "number",
+          "null"
+        ]
+      },
+      "requested": {
+        "description": "Responses or answers the refused work needed, when known.",
+        "type": [
+          "number",
+          "null"
+        ]
+      },
+      "responseCreditsUrl": {
+        "description": "Absolute link to buy response credits; only for response_credits and absent when the shared owner must act.",
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "resumable": {
+        "description": "True when the run can be continued in place with resume_study_run runId once the plan allows it.",
+        "type": [
+          "boolean",
+          "null"
+        ]
+      },
+      "runId": {
+        "description": "The run concerned, when one exists.",
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "skippedQuestionCount": {
+        "description": "Questions the limit kept from running.",
+        "type": [
+          "number",
+          "null"
+        ]
+      },
+      "skippedQuestions": {
+        "anyOf": [
+          {
+            "items": {},
+            "type": "array"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "Questions not asked: { index (zero-based), text }."
+      },
+      "totalQuestionCount": {
+        "description": "Questions in the request or run, when known.",
+        "type": [
+          "number",
+          "null"
+        ]
+      },
+      "upgradeUrl": {
+        "description": "Absolute link to the Minds plans page; absent when the shared owner must act.",
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "used": {
+        "description": "Allowance used in the current period, when known.",
+        "type": [
+          "number",
+          "null"
+        ]
+      }
+    },
+    "type": "object"
+  },
+  {
+    "type": "null"
+  }
+]

Changed1 schema field changedOct 8, 2026

changedOutput schema / properties / planLimit / anyOf

Previous value: -[
-  {
-    "additionalProperties": {},
-    "properties": {
-      "executionStarted": {
-        "description": "Whether any question of this request ran.",
-        "type": [
-          "boolean",
-          "null"
-        ]
-      },
-      "kind": {
-        "description": "study_answers (Free plan monthly Study answers) or response_credits (synthetic-response allowance).",
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "limit": {
-        "description": "Allowance of the current period, when known.",
-        "type": [
-          "number",
-          "null"
-        ]
-      },
-      "message": {
-        "description": "One user-facing sentence with the link(s).",
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "outcome": {
-        "description": "refused (nothing started or charged), partial (only the first questions run), stopped (a run stopped at the limit), or resume_refused.",
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "periodEnd": {
-        "description": "When the allowance renews (ISO 8601), when known.",
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "remaining": {
-        "description": "Allowance left, when known.",
-        "type": [
-          "number",
-          "null"
-        ]
-      },
-      "requested": {
-        "description": "Responses or answers the refused work needed, when known.",
-        "type": [
-          "number",
-          "null"
-        ]
-      },
-      "responseCreditsUrl": {
-        "description": "Absolute link to buy response credits; only for response_credits.",
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "resumable": {
-        "description": "True when the run can be continued in place with run_study_questions resume.runId once the plan allows it.",
-        "type": [
-          "boolean",
-          "null"
-        ]
-      },
-      "runId": {
-        "description": "The run concerned, when one exists.",
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "skippedQuestionCount": {
-        "description": "Questions the limit kept from running.",
-        "type": [
-          "number",
-          "null"
-        ]
-      },
-      "skippedQuestions": {
-        "anyOf": [
-          {
-            "items": {},
-            "type": "array"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "description": "Questions not asked: { index (zero-based), text }."
-      },
-      "totalQuestionCount": {
-        "description": "Questions in the request or run, when known.",
-        "type": [
-          "number",
-          "null"
-        ]
-      },
-      "upgradeUrl": {
-        "description": "Absolute link to the Minds plans page.",
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "used": {
-        "description": "Allowance used in the current period, when known.",
-        "type": [
-          "number",
-          "null"
-        ]
-      }
-    },
-    "type": "object"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "additionalProperties": {},
+    "properties": {
+      "executionStarted": {
+        "description": "Whether any question of this request ran.",
+        "type": [
+          "boolean",
+          "null"
+        ]
+      },
+      "kind": {
+        "description": "study_answers (Free plan monthly Study answers) or response_credits (synthetic-response allowance).",
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "limit": {
+        "description": "Allowance of the current period, when known.",
+        "type": [
+          "number",
+          "null"
+        ]
+      },
+      "message": {
+        "description": "One user-facing sentence with the link(s).",
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "outcome": {
+        "description": "refused (nothing started or charged), partial (only the first questions run), stopped (a run stopped at the limit), or resume_refused.",
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "periodEnd": {
+        "description": "When the allowance renews (ISO 8601), when known.",
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "remaining": {
+        "description": "Allowance left, when known.",
+        "type": [
+          "number",
+          "null"
+        ]
+      },
+      "requested": {
+        "description": "Responses or answers the refused work needed, when known.",
+        "type": [
+          "number",
+          "null"
+        ]
+      },
+      "responseCreditsUrl": {
+        "description": "Absolute link to buy response credits; only for response_credits.",
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "resumable": {
+        "description": "True when the run can be continued in place with resume_study_run runId once the plan allows it.",
+        "type": [
+          "boolean",
+          "null"
+        ]
+      },
+      "runId": {
+        "description": "The run concerned, when one exists.",
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "skippedQuestionCount": {
+        "description": "Questions the limit kept from running.",
+        "type": [
+          "number",
+          "null"
+        ]
+      },
+      "skippedQuestions": {
+        "anyOf": [
+          {
+            "items": {},
+            "type": "array"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "Questions not asked: { index (zero-based), text }."
+      },
+      "totalQuestionCount": {
+        "description": "Questions in the request or run, when known.",
+        "type": [
+          "number",
+          "null"
+        ]
+      },
+      "upgradeUrl": {
+        "description": "Absolute link to the Minds plans page.",
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "used": {
+        "description": "Allowance used in the current period, when known.",
+        "type": [
+          "number",
+          "null"
+        ]
+      }
+    },
+    "type": "object"
+  },
+  {
+    "type": "null"
+  }
+]

Changed1 schema field changedOct 7, 2026

changedInput schema / properties / audience / properties / name / description

Previous value: -"Audience name to fuzzy-match among the newest 1,000 visible Audiences. Use an exact audienceId for older records."New value: +"Audience name: exact or partial (case-insensitive), with a fuzzy fallback for typos."

Changed1 schema field changedOct 4, 2026

changedOutput schema / properties / planLimit / anyOf

Previous value: -[
-  {
-    "additionalProperties": {},
-    "properties": {
-      "executionStarted": {
-        "description": "Whether any question of this request ran.",
-        "type": [
-          "boolean",
-          "null"
-        ]
-      },
-      "kind": {
-        "description": "study_answers (Free plan monthly Study answers) or response_credits (synthetic-response allowance).",
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "limit": {
-        "description": "Allowance of the current period, when known.",
-        "type": [
-          "number",
-          "null"
-        ]
-      },
-      "message": {
-        "description": "One user-facing sentence with the link(s).",
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "outcome": {
-        "description": "refused (nothing started or charged), partial (only the first questions run), stopped (a run stopped at the limit), or resume_refused.",
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "periodEnd": {
-        "description": "When the allowance renews (ISO 8601), when known.",
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "remaining": {
-        "description": "Allowance left, when known.",
-        "type": [
-          "number",
-          "null"
-        ]
-      },
-      "responseCreditsUrl": {
-        "description": "Absolute link to buy response credits; only for response_credits.",
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "resumable": {
-        "description": "True when the run can be continued in place with run_study_questions resume.runId once the plan allows it.",
-        "type": [
-          "boolean",
-          "null"
-        ]
-      },
-      "runId": {
-        "description": "The run concerned, when one exists.",
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "skippedQuestionCount": {
-        "description": "Questions the limit kept from running.",
-        "type": [
-          "number",
-          "null"
-        ]
-      },
-      "skippedQuestions": {
-        "anyOf": [
-          {
-            "items": {},
-            "type": "array"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "description": "Questions not asked: { index (zero-based), text }."
-      },
-      "totalQuestionCount": {
-        "description": "Questions in the request or run, when known.",
-        "type": [
-          "number",
-          "null"
-        ]
-      },
-      "upgradeUrl": {
-        "description": "Absolute link to the Minds plans page.",
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "used": {
-        "description": "Allowance used in the current period, when known.",
-        "type": [
-          "number",
-          "null"
-        ]
-      }
-    },
-    "type": "object"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "additionalProperties": {},
+    "properties": {
+      "executionStarted": {
+        "description": "Whether any question of this request ran.",
+        "type": [
+          "boolean",
+          "null"
+        ]
+      },
+      "kind": {
+        "description": "study_answers (Free plan monthly Study answers) or response_credits (synthetic-response allowance).",
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "limit": {
+        "description": "Allowance of the current period, when known.",
+        "type": [
+          "number",
+          "null"
+        ]
+      },
+      "message": {
+        "description": "One user-facing sentence with the link(s).",
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "outcome": {
+        "description": "refused (nothing started or charged), partial (only the first questions run), stopped (a run stopped at the limit), or resume_refused.",
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "periodEnd": {
+        "description": "When the allowance renews (ISO 8601), when known.",
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "remaining": {
+        "description": "Allowance left, when known.",
+        "type": [
+          "number",
+          "null"
+        ]
+      },
+      "requested": {
+        "description": "Responses or answers the refused work needed, when known.",
+        "type": [
+          "number",
+          "null"
+        ]
+      },
+      "responseCreditsUrl": {
+        "description": "Absolute link to buy response credits; only for response_credits.",
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "resumable": {
+        "description": "True when the run can be continued in place with run_study_questions resume.runId once the plan allows it.",
+        "type": [
+          "boolean",
+          "null"
+        ]
+      },
+      "runId": {
+        "description": "The run concerned, when one exists.",
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "skippedQuestionCount": {
+        "description": "Questions the limit kept from running.",
+        "type": [
+          "number",
+          "null"
+        ]
+      },
+      "skippedQuestions": {
+        "anyOf": [
+          {
+            "items": {},
+            "type": "array"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "Questions not asked: { index (zero-based), text }."
+      },
+      "totalQuestionCount": {
+        "description": "Questions in the request or run, when known.",
+        "type": [
+          "number",
+          "null"
+        ]
+      },
+      "upgradeUrl": {
+        "description": "Absolute link to the Minds plans page.",
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "used": {
+        "description": "Allowance used in the current period, when known.",
+        "type": [
+          "number",
+          "null"
+        ]
+      }
+    },
+    "type": "object"
+  },
+  {
+    "type": "null"
+  }
+]

Changed21 schema fields changedOct 2, 2026

removedOutput schema / properties / apiBase / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

addedOutput schema / properties / apiBase / type
```
Added value: +[
+  "string",
+  "null"
+]
```

removedOutput schema / properties / executionStarted / anyOf

Removed value: -[
-  {
-    "type": "boolean"
-  },
-  {
-    "type": "null"
-  }
-]

addedOutput schema / properties / executionStarted / type
```
Added value: +[
+  "boolean",
+  "null"
+]
```

removedOutput schema / properties / locale / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

addedOutput schema / properties / locale / type
```
Added value: +[
+  "string",
+  "null"
+]
```

changedOutput schema / properties / planLimit / anyOf

Previous value: -[
-  {
-    "additionalProperties": {},
-    "properties": {
-      "executionStarted": {
-        "anyOf": [
-          {
-            "type": "boolean"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "description": "Whether any question of this request ran."
-      },
-      "kind": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "description": "study_answers (Free plan monthly Study answers) or response_credits (synthetic-response allowance)."
-      },
-      "limit": {
-        "anyOf": [
-          {
-            "type": "number"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "description": "Allowance of the current period, when known."
-      },
-      "message": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "description": "One user-facing sentence with the link(s)."
-      },
-      "outcome": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "description": "refused (nothing started or charged), partial (only the first questions run), stopped (a run stopped at the limit), or resume_refused."
-      },
-      "periodEnd": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "description": "When the allowance renews (ISO 8601), when known."
-      },
-      "remaining": {
-        "anyOf": [
-          {
-            "type": "number"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "description": "Allowance left, when known."
-      },
-      "responseCreditsUrl": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "description": "Absolute link to buy response credits; only for response_credits."
-      },
-      "resumable": {
-        "anyOf": [
-          {
-            "type": "boolean"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "description": "True when the run can be continued in place with run_study_questions resume.runId once the plan allows it."
-      },
-      "runId": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "description": "The run concerned, when one exists."
-      },
-      "skippedQuestionCount": {
-        "anyOf": [
-          {
-            "type": "number"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "description": "Questions the limit kept from running."
-      },
-      "skippedQuestions": {
-        "anyOf": [
-          {
-            "items": {},
-            "type": "array"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "description": "Questions not asked: { index (zero-based), text }."
-      },
-      "totalQuestionCount": {
-        "anyOf": [
-          {
-            "type": "number"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "description": "Questions in the request or run, when known."
-      },
-      "upgradeUrl": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "description": "Absolute link to the Minds plans page."
-      },
-      "used": {
-        "anyOf": [
-          {
-            "type": "number"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "description": "Allowance used in the current period, when known."
-      }
-    },
-    "type": "object"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "additionalProperties": {},
+    "properties": {
+      "executionStarted": {
+        "description": "Whether any question of this request ran.",
+        "type": [
+          "boolean",
+          "null"
+        ]
+      },
+      "kind": {
+        "description": "study_answers (Free plan monthly Study answers) or response_credits (synthetic-response allowance).",
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "limit": {
+        "description": "Allowance of the current period, when known.",
+        "type": [
+          "number",
+          "null"
+        ]
+      },
+      "message": {
+        "description": "One user-facing sentence with the link(s).",
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "outcome": {
+        "description": "refused (nothing started or charged), partial (only the first questions run), stopped (a run stopped at the limit), or resume_refused.",
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "periodEnd": {
+        "description": "When the allowance renews (ISO 8601), when known.",
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "remaining": {
+        "description": "Allowance left, when known.",
+        "type": [
+          "number",
+          "null"
+        ]
+      },
+      "responseCreditsUrl": {
+        "description": "Absolute link to buy response credits; only for response_credits.",
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "resumable": {
+        "description": "True when the run can be continued in place with run_study_questions resume.runId once the plan allows it.",
+        "type": [
+          "boolean",
+          "null"
+        ]
+      },
+      "runId": {
+        "description": "The run concerned, when one exists.",
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "skippedQuestionCount": {
+        "description": "Questions the limit kept from running.",
+        "type": [
+          "number",
+          "null"
+        ]
+      },
+      "skippedQuestions": {
+        "anyOf": [
+          {
+            "items": {},
+            "type": "array"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "Questions not asked: { index (zero-based), text }."
+      },
+      "totalQuestionCount": {
+        "description": "Questions in the request or run, when known.",
+        "type": [
+          "number",
+          "null"
+        ]
+      },
+      "upgradeUrl": {
+        "description": "Absolute link to the Minds plans page.",
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "used": {
+        "description": "Allowance used in the current period, when known.",
+        "type": [
+          "number",
+          "null"
+        ]
+      }
+    },
+    "type": "object"
+  },
+  {
+    "type": "null"
+  }
+]

removedOutput schema / properties / question / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

addedOutput schema / properties / question / type
```
Added value: +[
+  "string",
+  "null"
+]
```

removedOutput schema / properties / questionId / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

addedOutput schema / properties / questionId / type
```
Added value: +[
+  "string",
+  "null"
+]
```

removedOutput schema / properties / runId / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

addedOutput schema / properties / runId / type
```
Added value: +[
+  "string",
+  "null"
+]
```

removedOutput schema / properties / sharedStudyUrl / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

addedOutput schema / properties / sharedStudyUrl / type
```
Added value: +[
+  "string",
+  "null"
+]
```

removedOutput schema / properties / status / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

addedOutput schema / properties / status / type
```
Added value: +[
+  "string",
+  "null"
+]
```

removedOutput schema / properties / studyId / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

addedOutput schema / properties / studyId / type
```
Added value: +[
+  "string",
+  "null"
+]
```

removedOutput schema / properties / workspaceUrl / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

addedOutput schema / properties / workspaceUrl / type
```
Added value: +[
+  "string",
+  "null"
+]
```

Changed3 schema fields changedOct 1, 2026

changedInput schema / properties / attachments / description

Previous value: -"Files/images processed once and given to every Audience member as context. Pass a fetchable HTTP(S) URL, or an existing Minds workspace upload under chat/<userId>/ (that storage path or its /api/uploads/chat/ URL; request the signed upload with folder \"chat\"). MCP cannot read a local path. A file shared in the conversation (uploaded or generated image, PDF, document) is read through the tool's top-level files field where the tool has one; elsewhere a PDF or image with no public URL has no MCP route and is uploaded in the Minds app first. Text contents (UTF-8 text, Markdown, CSV, JSON) can be sent to import_audience_sources. Study tools import external file URLs into durable Minds storage before saving or running. A temp/, portfolio/, or context/ path, and any /api/uploads/file-access/ URL, is refused as not belonging to the workspace owner; pass a plain external URL instead. The Study refuses to start if Minds cannot read the asset."New value: +"Files/images processed once and given to every Audience member as context. Accepts a public HTTP(S) URL or a file already in the user's Minds uploads under chat/<userId>/ (its storage path or its /api/uploads/chat/ URL). MCP cannot read a local path. Files shared in the conversation (uploaded or generated images, PDFs, documents) go in the tool's top-level conversationFiles field where the tool has one; elsewhere a PDF or image without a public URL has no MCP route and is uploaded in the Minds app first. Plain text contents (UTF-8 text, Markdown, CSV, JSON) can go to import_audience_sources. External URLs are copied into Minds storage before a Study is saved or run. temp/, portfolio/ and context/ paths and /api/uploads/file-access/ URLs belong to other owners and are not accepted. A Study does not start until Minds can read every file."

addedInput schema / properties / conversationFiles

Added value: +{
+  "description": "Stimulus files given to every Audience member, alongside any attachments. Files shared in this conversation: uploaded or generated images, PDFs, documents. Each is copied into Minds storage on receipt; its file_id is its attachment id.",
+  "items": {
+    "properties": {
+      "download_url": {
+        "description": "Download URL the chat host supplies for this file.",
+        "minLength": 1,
+        "type": "string"
+      },
+      "file_id": {
+        "description": "The chat host's ID for this file.",
+        "minLength": 1,
+        "type": "string"
+      },
+      "file_name": {
+        "description": "File name when the host supplies it.",
+        "minLength": 1,
+        "type": "string"
+      },
+      "mime_type": {
+        "description": "MIME type when the host supplies it.",
+        "minLength": 1,
+        "type": "string"
+      }
+    },
+    "required": [
+      "download_url",
+      "file_id"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}

removedInput schema / properties / files

Removed value: -{
-  "description": "Stimulus files given to every Audience member, alongside any attachments. Files shared in this conversation: uploaded or generated images, PDFs, documents. Each is copied into Minds storage on receipt; its file_id is its attachment id.",
-  "items": {
-    "properties": {
-      "download_url": {
-        "description": "Download URL the chat host supplies for this file.",
-        "minLength": 1,
-        "type": "string"
-      },
-      "file_id": {
-        "description": "The chat host's ID for this file.",
-        "minLength": 1,
-        "type": "string"
-      },
-      "file_name": {
-        "description": "File name when the host supplies it.",
-        "minLength": 1,
-        "type": "string"
-      },
-      "mime_type": {
-        "description": "MIME type when the host supplies it.",
-        "minLength": 1,
-        "type": "string"
-      }
-    },
-    "required": [
-      "download_url",
-      "file_id"
-    ],
-    "type": "object"
-  },
-  "type": "array"
-}

Changed5 schema fields changedOct 1, 2026

changedInput schema / properties / attachments / description

Previous value: -"Files/images processed once and given to every Audience member as context. Pass a fetchable HTTP(S) URL, or an existing Minds workspace upload under chat/<userId>/ (that storage path or its /api/uploads/chat/ URL; request the signed upload with folder \"chat\"). MCP cannot read a local path, and a file the user attached in the chat client is NOT reachable either unless that client also exposes a public URL for it — most do not. When it is not: send the file CONTENTS to import_audience_sources (UTF-8 text, Markdown, CSV, JSON), which takes contents rather than paths. A PDF or image with no public URL has no MCP route at all — it must be uploaded in the Minds app first; say so instead of retrying. Study tools import external file URLs into durable Minds storage before saving or running. 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."New value: +"Files/images processed once and given to every Audience member as context. Pass a fetchable HTTP(S) URL, or an existing Minds workspace upload under chat/<userId>/ (that storage path or its /api/uploads/chat/ URL; request the signed upload with folder \"chat\"). MCP cannot read a local path. A file shared in the conversation (uploaded or generated image, PDF, document) is read through the tool's top-level files field where the tool has one; elsewhere a PDF or image with no public URL has no MCP route and is uploaded in the Minds app first. Text contents (UTF-8 text, Markdown, CSV, JSON) can be sent to import_audience_sources. Study tools import external file URLs into durable Minds storage before saving or running. A temp/, portfolio/, or context/ path, and any /api/uploads/file-access/ URL, is refused as not belonging to the workspace owner; pass a plain external URL instead. The Study refuses to start if Minds cannot read the asset."

changedInput schema / properties / attachments / items / properties / path / description

Previous value: -"Storage path of a file already uploaded to Minds. Pass a fetchable HTTP(S) URL, or an existing Minds workspace upload under chat/<userId>/ (that storage path or its /api/uploads/chat/ URL; request the signed upload with folder \"chat\"). MCP cannot read a local path, and a file the user attached in the chat client is NOT reachable either unless that client also exposes a public URL for it — most do not. When it is not: send the file CONTENTS to import_audience_sources (UTF-8 text, Markdown, CSV, JSON), which takes contents rather than paths. A PDF or image with no public URL has no MCP route at all — it must be uploaded in the Minds app first; say so instead of retrying. Study tools import external file URLs into durable Minds storage before saving or running. 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."New value: +"Storage path of a file already uploaded to Minds (chat/<userId>/...)."

changedInput schema / properties / attachments / items / properties / url / description

Previous value: -"Fetchable HTTP(S), signed, or Minds workspace upload URL. Pass a fetchable HTTP(S) URL, or an existing Minds workspace upload under chat/<userId>/ (that storage path or its /api/uploads/chat/ URL; request the signed upload with folder \"chat\"). MCP cannot read a local path, and a file the user attached in the chat client is NOT reachable either unless that client also exposes a public URL for it — most do not. When it is not: send the file CONTENTS to import_audience_sources (UTF-8 text, Markdown, CSV, JSON), which takes contents rather than paths. A PDF or image with no public URL has no MCP route at all — it must be uploaded in the Minds app first; say so instead of retrying. Study tools import external file URLs into durable Minds storage before saving or running. 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."New value: +"Fetchable HTTP(S), signed, or Minds workspace upload URL."

addedInput schema / properties / files

Added value: +{
+  "description": "Stimulus files given to every Audience member, alongside any attachments. Files shared in this conversation: uploaded or generated images, PDFs, documents. Each is copied into Minds storage on receipt; its file_id is its attachment id.",
+  "items": {
+    "properties": {
+      "download_url": {
+        "description": "Download URL the chat host supplies for this file.",
+        "minLength": 1,
+        "type": "string"
+      },
+      "file_id": {
+        "description": "The chat host's ID for this file.",
+        "minLength": 1,
+        "type": "string"
+      },
+      "file_name": {
+        "description": "File name when the host supplies it.",
+        "minLength": 1,
+        "type": "string"
+      },
+      "mime_type": {
+        "description": "MIME type when the host supplies it.",
+        "minLength": 1,
+        "type": "string"
+      }
+    },
+    "required": [
+      "download_url",
+      "file_id"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}

addedOutput schema / properties / planLimit

Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": {},
+      "properties": {
+        "executionStarted": {
+          "anyOf": [
+            {
+              "type": "boolean"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "Whether any question of this request ran."
+        },
+        "kind": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "study_answers (Free plan monthly Study answers) or response_credits (synthetic-response allowance)."
+        },
+        "limit": {
+          "anyOf": [
+            {
+              "type": "number"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "Allowance of the current period, when known."
+        },
+        "message": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "One user-facing sentence with the link(s)."
+        },
+        "outcome": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "refused (nothing started or charged), partial (only the first questions run), stopped (a run stopped at the limit), or resume_refused."
+        },
+        "periodEnd": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "When the allowance renews (ISO 8601), when known."
+        },
+        "remaining": {
+          "anyOf": [
+            {
+              "type": "number"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "Allowance left, when known."
+        },
+        "responseCreditsUrl": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "Absolute link to buy response credits; only for response_credits."
+        },
+        "resumable": {
+          "anyOf": [
+            {
+              "type": "boolean"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "True when the run can be continued in place with run_study_questions resume.runId once the plan allows it."
+        },
+        "runId": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "The run concerned, when one exists."
+        },
+        "skippedQuestionCount": {
+          "anyOf": [
+            {
+              "type": "number"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "Questions the limit kept from running."
+        },
+        "skippedQuestions": {
+          "anyOf": [
+            {
+              "items": {},
+              "type": "array"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "Questions not asked: { index (zero-based), text }."
+        },
+        "totalQuestionCount": {
+          "anyOf": [
+            {
+              "type": "number"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "Questions in the request or run, when known."
+        },
+        "upgradeUrl": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "Absolute link to the Minds plans page."
+        },
+        "used": {
+          "anyOf": [
+            {
+              "type": "number"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "Allowance used in the current period, when known."
+        }
+      },
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "Present when a plan limit refused, truncated or stopped Study work."
+}

Changed3 schema fields changedSep 28, 2026

changedInput schema / properties / attachments / description

Previous value: -"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."New value: +"Files/images processed once and given to every Audience member as context. Pass a fetchable HTTP(S) URL, or an existing Minds workspace upload under chat/<userId>/ (that storage path or its /api/uploads/chat/ URL; request the signed upload with folder \"chat\"). MCP cannot read a local path, and a file the user attached in the chat client is NOT reachable either unless that client also exposes a public URL for it — most do not. When it is not: send the file CONTENTS to import_audience_sources (UTF-8 text, Markdown, CSV, JSON), which takes contents rather than paths. A PDF or image with no public URL has no MCP route at all — it must be uploaded in the Minds app first; say so instead of retrying. Study tools import external file URLs into durable Minds storage before saving or running. 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."

changedInput schema / properties / attachments / items / properties / path / description

Previous value: -"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."New value: +"Storage path of a file already uploaded to Minds. Pass a fetchable HTTP(S) URL, or an existing Minds workspace upload under chat/<userId>/ (that storage path or its /api/uploads/chat/ URL; request the signed upload with folder \"chat\"). MCP cannot read a local path, and a file the user attached in the chat client is NOT reachable either unless that client also exposes a public URL for it — most do not. When it is not: send the file CONTENTS to import_audience_sources (UTF-8 text, Markdown, CSV, JSON), which takes contents rather than paths. A PDF or image with no public URL has no MCP route at all — it must be uploaded in the Minds app first; say so instead of retrying. Study tools import external file URLs into durable Minds storage before saving or running. 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."

changedInput schema / properties / attachments / items / properties / url / description

Previous value: -"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."New value: +"Fetchable HTTP(S), signed, or Minds workspace upload URL. Pass a fetchable HTTP(S) URL, or an existing Minds workspace upload under chat/<userId>/ (that storage path or its /api/uploads/chat/ URL; request the signed upload with folder \"chat\"). MCP cannot read a local path, and a file the user attached in the chat client is NOT reachable either unless that client also exposes a public URL for it — most do not. When it is not: send the file CONTENTS to import_audience_sources (UTF-8 text, Markdown, CSV, JSON), which takes contents rather than paths. A PDF or image with no public URL has no MCP route at all — it must be uploaded in the Minds app first; say so instead of retrying. Study tools import external file URLs into durable Minds storage before saving or running. 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."

Changed1 schema field changedSep 25, 2026

changedInput schema / properties / question / description

Previous value: -"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. If the question offers a fixed set of answer options, say so in the text as the respondent would read it. A direct question is classified automatically, and a question whose options are only prose can still be answered as free text, which yields no option breakdown. A question whose options must be ranked, or whose exact option labels and order must be preserved, belongs in a planned multi-question block, where each item carries an explicit response contract."New value: +"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. If the question offers a fixed set of answer options, say so in the text as the respondent would read it. The research reader identifies the question and its answer contract together. Include the complete authored labels, ordering and selection instructions. Numbered answer options do not by themselves make a request a multi-question battery. An invalid or ambiguous reading stops for retry or planning before execution."

Changed1 schema field changedSep 23, 2026

changedInput schema / properties / question / description

Previous value: -"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."New value: +"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. If the question offers a fixed set of answer options, say so in the text as the respondent would read it. A direct question is classified automatically, and a question whose options are only prose can still be answered as free text, which yields no option breakdown. A question whose options must be ranked, or whose exact option labels and order must be preserved, belongs in a planned multi-question block, where each item carries an explicit response contract."

Changed5 schema fields changedSep 22, 2026

addedInput schema / properties / audience

Added value: +{
+  "description": "Which Audience to ask. Give the id when known, otherwise the name.",
+  "properties": {
+    "id": {
+      "description": "Audience ID (UUID). Preferred when known.",
+      "type": "string"
+    },
+    "name": {
+      "description": "Audience name to fuzzy-match among the newest 1,000 visible Audiences. Use an exact audienceId for older records.",
+      "type": "string"
+    }
+  },
+  "type": "object"
+}

removedInput schema / properties / audienceId

Removed value: -{
-  "description": "Audience ID (UUID). Preferred when known.",
-  "type": "string"
-}

removedInput schema / properties / audienceName

Removed value: -{
-  "description": "Audience name to fuzzy-match among the newest 1,000 visible Audiences. Use an exact audienceId for older records.",
-  "type": "string"
-}

removedInput schema / properties / groupId

Removed value: -{
-  "description": "Legacy alias for audienceId. Accepted for compatibility.",
-  "type": "string"
-}

removedInput schema / properties / groupName

Removed value: -{
-  "description": "Legacy alias for audienceName. Accepted for compatibility.",
-  "type": "string"
-}

Changed1 schema field changedSep 22, 2026

changedInput schema / properties / audienceName / description

Previous value: -"Audience name to resolve via fuzzy match against the user's Audiences."New value: +"Audience name to fuzzy-match among the newest 1,000 visible Audiences. Use an exact audienceId for older records."

Changed1 schema field changedSep 20, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": {},
+  "properties": {
+    "apiBase": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Minds base URL."
+    },
+    "executionStarted": {
+      "anyOf": [
+        {
+          "type": "boolean"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "False when nothing was submitted."
+    },
+    "locale": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Study display locale."
+    },
+    "proposedQuestions": {
+      "anyOf": [
+        {
+          "items": {},
+          "type": "array"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "For planning_required: the respondent questions detected or proposed."
+    },
+    "question": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "The submitted question."
+    },
+    "questionId": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Identifier of this question; pass it to get_study_status to follow only this question."
+    },
+    "runId": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Durable run identifier."
+    },
+    "sharedStudyUrl": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Public share link, or null when link sharing is off."
+    },
+    "status": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "queued once submitted, or planning_required when the request needs a reviewed multi-question plan (nothing was submitted)."
+    },
+    "studyId": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Study the question was asked in."
+    },
+    "workspaceUrl": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Authenticated Minds workspace link for the Study."
+    }
+  },
+  "type": "object"
+}

Changed3 schema fields changedSep 10, 2026

changedInput schema / properties / attachments / description

Previous value: -"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. The Study refuses to start if Minds cannot read the asset."New value: +"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."

changedInput schema / properties / attachments / items / properties / path / description

Previous value: -"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. The Study refuses to start if Minds cannot read the asset."New value: +"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."

changedInput schema / properties / attachments / items / properties / url / description

Previous value: -"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. The Study refuses to start if Minds cannot read the asset."New value: +"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."

Changed1 schema field changedSep 2, 2026

addedInput schema / properties / attachments / items / properties / id

Added value: +{
+  "description": "Stable asset ID used by questionAttachments to assign this file to specific planned questions.",
+  "maxLength": 255,
+  "minLength": 1,
+  "type": "string"
+}

Changed3 schema fields changedSep 2, 2026

changedInput schema / properties / attachments / description

Previous value: -"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. The Study refuses to start if Minds cannot read the asset."New value: +"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. The Study refuses to start if Minds cannot read the asset."

changedInput schema / properties / attachments / items / properties / path / description

Previous value: -"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. The Study refuses to start if Minds cannot read the asset."New value: +"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. The Study refuses to start if Minds cannot read the asset."

changedInput schema / properties / attachments / items / properties / url / description

Previous value: -"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. The Study refuses to start if Minds cannot read the asset."New value: +"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. The Study refuses to start if Minds cannot read the asset."

AddedAug 27, 2026

TDQS

A4.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Adds substantial behavioral context beyond annotations (openWorld, non-idempotent): creates a private Study, starts asynchronous Minds, returns Study identifier/links, may reword, may return planning_required. Annotations already declare the mutation/open-world profile, so this extra detail earns a 4. Doesn't cover polling/latency, so not a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the core capability and scope-out in the first sentences, then the reword/planning contract, then attachment notes. Dense but well-structured; slightly long, with attachment detail partially duplicated in the schema, but every section carries distinct routing information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given a complex 6-param tool with nested objects and an output schema, the description covers scope, async behavior, reword/planning behavior, and attachment routing. Output return shape is delegated to the output schema, which is appropriate. Minor gaps: latency/polling expectations for the async answers aren't stated.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description adds material semantic guidance beyond the schema: attachments vs textAttachments vs conversationFiles, that pasted material belongs in textAttachments verbatim (not the question), and that MCP cannot read local paths. This is genuine value over the structured fields.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Asks exactly one standalone question') and resource ('one existing Audience'), and explicitly scopes out multi-question requests: 'Out of scope: a questionnaire, battery, section or any request with two or more known questions.' This clearly distinguishes it from siblings like create_study and ask_study.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit when/when-not guidance: use this for exactly one standalone question; use planned multi-question blocks for batteries. Notes the planning_required fallback for ambiguous requests and the server's reword behavior. An agent knows precisely which request shape selects this tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All Minds: Synthetic Market Research tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Ask One Standalone Audience Question

Input Schema

Output Schema

Schema Changelog

TDQS

Glama MCP Gateway

Resources