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.

Automatic classification may reformulate a context-dependent question. The accepted task and its answer contract are returned together, with the original request retained separately. Requests needing clarification 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 must be fetchable HTTP(S) URLs or existing Minds workspace uploads; the Study refuses to start if its Minds cannot read one.

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 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.
`attachments`	No	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.

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.
`questionId`	No	Identifier of this question; pass it to get_study_status to follow only this question.
`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.

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.4/5.0

Behavior5/5

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

Beyond the annotations (readOnlyHint=false, idempotentHint=false, openWorldHint=true), the description discloses that classification may reformulate the question, that the accepted task plus answer contract are returned with the original request retained, that ambiguous requests return planning_required before execution, and that the Study refuses to start if Minds cannot read an attachment. This is rich behavioral context an agent could not infer from the annotations alone.

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?

The definition is front-loaded with the core action, then layers scope exclusions and attachment constraints. Every sentence carries information, though the attachment sentence partially duplicates the schema's lengthy attachment prose, making the block slightly heavier than strictly necessary.

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

Completeness5/5

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

For a mutation tool with nested params and an output schema, the description covers routing, the planning_required fallback, attachment fetchability constraints, and Study-refusal behavior — everything an agent needs to call it correctly without the output schema needing description-side explanation of return values.

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

Parameters3/5

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

Schema description coverage is 100%, so the schema already documents audience, question, attachments, and name in detail; the description largely parallels it. It adds only marginal framing, such as the note that numbered answer options do not by themselves constitute a battery, so the baseline 3 applies.

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?

The opening sentence states a precise verb+resource+scope: 'Asks exactly one standalone question of one existing Audience,' then enumerates the side effects (private Study, async answers, returns Study id and links). This cleanly distinguishes it from siblings like ask_study, run_study_questions, and plan_study_questions that operate on full question sets.

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

Usage Guidelines4/5

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

It gives an explicit negative boundary — 'Out of scope: a questionnaire, battery, section or any request with two or more known questions' — and routes that case to a 'planned multi-question block inside a Study,' which implicitly names the sibling alternative. It stops short of naming ask_study directly, but the when-to-use and when-not-to-use conditions are both clear.

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