ask_study

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