Skip to main content
Glama

Minds: Synthetic Market Research

Create a Grounded Audience from a Brief

create_audience_from_brief
Idempotent

Researches a free-text population brief and builds a new Audience of Minds with explicit profiles and exact segment allocation. A new brief returns an evidence-backed draft for review; draft.rework or the displayed review revises that draft before confirmation, and creation requires the user-accepted draft or quota snapshot and its checksum. Every new brief starts a separate draft and, once confirmed, a separate Audience. An Audience that already exists is changed in place by recalibrating it by its id, never rebuilt from a new brief. Supports reviewed respondent datasets. Creation is asynchronous and returns an operation ID. Audiences are private unless link sharing is enabled.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
nameNoOptional Audience name override. When omitted, the server names the Audience from the brief or the LLM detection result.
briefNoFree-text brief describing the population the Audience should represent. E.g. "California high school students grades 9-12", "Berlin Späti customers", "Spanish lawyers", "management team of Coca Cola". The server runs deep web research on this brief to find demographic / psychographic distributions from authoritative sources, then generates personas that proportionally reflect those distributions.
draftNoThe webapp Audience draft workflow. Preview proposes Minds before Create; id and sha256 identify the exact reviewed roster. Rework revises that draft. Set preview:false with both id and sha256 only after the user confirms the displayed draft; that confirmation needs nothing else (omit the brief and every other option): the server creates exactly the reviewed draft from its stored request.
researchNoExtra material the grounding research reads alongside the brief, and whether web search runs at all.
groundingNoReview the quota axes before any Mind exists, and pass a reviewed snapshot back unchanged to create from it.
compositionNoHow many Minds to create and how the cohort is allocated across the grounded axes.
operationIdNoResume a queued preview or creation by its returned jobId. Reads its v1 operation status without creating or charging anything. Supply this alone; do not repeat the creation brief to check progress. Once the creation completed, the result also says whether every Mind can chat yet (the Audience is ready then) and how many are still learning from their sources in the background; call it again to follow that.
conversationFilesNoResearch files (screener, questionnaire, report, respondent data), read like research.files. 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.
isLinkSharingEnabledNoSet true ONLY when the user explicitly asked for a public/shareable link. Defaults to false: the Audience is private to its owner and no share URL is generated. Enabling this publishes the Audience — including its grounding, sources and personas — at a world-readable URL that needs no login. Do not enable it to "be helpful".

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
statusNoCreation state of the Audience.
previewNoResearch and allocation preview; no Audience or Minds have been created.
audienceNoThe created or previewed Audience with its Minds and grounding.
operationNoDurable creation operation, while creation is still running.
readinessNoWhen a completed operation is read back: member rollup from GET /api/v1/audiences/{id}/progress. isReady = every Mind can chat (the Audience is ready); startsNow = a Study started now runs at once, without leftOut Minds whose training failed for good; learning = ready Minds still learning from their sources in the background; fullyTrained = none still learning; research.phase = researching while the Audience's background research runs (it is usable meanwhile), researched once merged and applied.
workspaceUrlNoMinds workspace link for the Audience.
audienceReviewNoReviewed Audience brief, distributions and creation options for the widget.
existingAudiencesNoThe caller's existing Audiences with exactly this name (id, name, workspaceUrl), when a new brief was started; this call still creates a separate Audience.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / research / properties / files / description
      Previous value: -"Optional already-uploaded research files. 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. The server analyzes these through the same extended screener/questionnaire path as the in-app New Audience uploader, including study roles, screening and quota rules, review distributions, and grounding provenance."New value: +"Optional already-uploaded research files. 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. The server analyzes these through the same extended screener/questionnaire path as the in-app New Audience uploader, including study roles, screening and quota rules, review distributions, and grounding provenance. Every file shapes the grounding, but only one classified as supporting material (not a spreadsheet) enters the members' own knowledge; the result's withheldFromMemberKnowledge names each other file with its reason (respondent_dataset, study_report, questionnaire, screener, distribution_source, tabular, or unclassified: not classified as supporting material, also when the reading failed or ran out of time)."
  2. Changed3 schema fields changed
    • changedInput schema / properties / composition / properties / audienceCreationMode / description
      Previous value: -"How the Audience is sized. \"balanced\" (default): compact and representative for everyday research. It is the only mode with a hard wall on a size you state — a memberCount above 20 is refused with 403 MODE_CAP. \"segment_coverage\": two representatives per limiting grounded cell, from a 10-Mind floor; automatic sizing stops at 50, but a memberCount you state is bounded only by your plan. \"benchmark_depth\": repeated representation of limiting grounded cells for validation-ready segmentation; bounded by your plan allowance. The deeper two require a Pro or Enterprise plan — on other plans the server SILENTLY downgrades to \"balanced\" and echoes the effective mode in structuredContent.audience.audienceCreationMode. Call get_audience_limits to see the ceilings that apply to your account."New value: +"How the Audience is sized. \"balanced\" (default): compact and representative for everyday research. It builds at most 20 Minds; a larger memberCount moves to a deeper mode your plan includes, else is built at 20 with a note. \"segment_coverage\": two representatives per limiting grounded cell, from a 10-Mind floor; automatic sizing stops at 50, but a memberCount you state is bounded only by your plan. \"benchmark_depth\": repeated representation of limiting grounded cells for validation-ready segmentation; bounded by your plan allowance. The deeper two are included only on some plans (get_audience_limits shows which apply to you) — on other plans the server SILENTLY downgrades to \"balanced\" and echoes the effective mode in structuredContent.audience.audienceCreationMode. Call get_audience_limits to see the ceilings that apply to your account."
    • changedInput schema / properties / composition / properties / memberCount / description
      Previous value: -"Exact number of Minds to create. Pass this whenever the user states a size (\"exactly 50 per region\", \"genau 50 Minds je Zelle\") instead of relying on the server to parse the number out of the brief. When omitted, the size is inferred from the brief and, failing that, from the creation mode's evidence-based automatic sizing. Two separate refusals apply: 403 MODE_CAP above 20 in \"balanced\" mode (switch to segment_coverage or benchmark_depth), and 403 PLAN_LIMIT above your plan's per-Audience cap. The 6000 accepted here is the absolute system ceiling, not your allowance — call get_audience_limits for the real one. The Audience is never created at a partial size."New value: +"Exact number of Minds to create. Pass this whenever the user states a size (\"exactly 50 per region\", \"genau 50 Minds je Zelle\") instead of relying on the server to parse the number out of the brief. When omitted, the size is inferred from the brief and, failing that, from the creation mode's evidence-based automatic sizing. The only refusal is 403 PLAN_LIMIT above your plan's per-Audience cap; above 20 in \"balanced\" see audienceCreationMode. The 6000 accepted here is the absolute system ceiling, not your allowance — call get_audience_limits for the real one. Apart from that note, the Audience is never created at a partial size."
    • changedInput schema / properties / research / properties / includeWebSearch / description
      Previous value: -"Set false to skip Exa web search and extraction completely. The Audience is then grounded only on the brief and supplied files, links, keywords, and structurally parsed respondent data. Note that a study report, questionnaire, screener or respondent dataset grounds the Audience but is deliberately withheld from the members' own knowledge, so it cannot be the evidence they answer from; with nothing left to ground on, creation is refused rather than producing Minds with no evidence. Leave it true unless the supplied sources include material the members themselves should read."New value: +"Set false to skip Exa web search and extraction completely. The Audience is then grounded only on the brief and supplied files, links, keywords, and structurally parsed respondent data. Note that a study report, questionnaire, screener or respondent dataset grounds the Audience but is deliberately withheld from the members' own knowledge, so it cannot be the evidence they answer from; with nothing else to ground on, the Audience is still created from the brief and its charts and says that its members carry no readable evidence. Leave it true unless the supplied sources include material the members themselves should read."
  3. Changed2 schema fields changed
    • changedInput schema / properties / grounding / properties / preview / description
      Previous value: -"Review the quota axes BEFORE any Mind exists. When true, the server runs research grounding and deterministic cohort allocation without creating an Audience or Minds or consuming a generation allowance. To revise a saved preview without repeating research, pass its unchanged reviewedGroundingJson/SHA pair together with groundingPreview and the revised exclusion/allocation options. Fresh research uses the same durable operation as the public REST API; this tool returns its operation immediately so the widget can stream sources and distributions. New briefs, including respondent datasets, default to the full webapp draft with proposed Minds; only a legacy full dataset payload uses a quota-only review. Setting false without reviewed evidence still returns a preview. Present the plan and wait until the user confirms it, then set grounding.preview:false with the unchanged reviewedGroundingJson/SHA pair and the same allocation options. Supplying saved evidence without an explicit false keeps it in review. The response includes effective target percentages and integer counts; explicit allocation targets that do not match grounded axes fail closed."New value: +"Review the quota axes BEFORE any Mind exists. When true, the server runs research grounding and deterministic cohort allocation without creating an Audience or Minds or consuming a generation allowance. To revise a saved preview without repeating research, pass its unchanged reviewedGroundingJson/SHA pair together with groundingPreview and the revised exclusion/allocation options. Fresh research uses the same durable operation as the public REST API; this tool returns its operation immediately so the widget can stream sources and distributions. New briefs, including respondent datasets, default to the full webapp draft with proposed Minds; only a legacy full dataset payload uses a quota-only review. Setting false without reviewed evidence still returns a preview. Present the plan and wait until the user confirms it, then set grounding.preview:false with the unchanged reviewedGroundingJson/SHA pair and the same allocation options. Supplying saved evidence without an explicit false keeps it in review. The response includes effective target percentages and integer counts; explicit allocation targets that do not match grounded axes are set aside and listed in cohortAllocation.audit.warnings (or as a target_unapplied notice on the grounding), never refused. If research did not finish, the preview says so (research_unavailable) and creating from it researches the Audience in the background."
    • changedOutput schema / properties / readiness / description
      Previous value: -"When a completed operation is read back: member rollup from GET /api/v1/audiences/{id}/progress. isReady = every Mind can chat (the Audience is ready); learning = ready Minds still learning from their sources in the background; fullyTrained = none still learning; research.phase = researching while the Audience's background research runs (it is usable meanwhile), researched once merged and applied."New value: +"When a completed operation is read back: member rollup from GET /api/v1/audiences/{id}/progress. isReady = every Mind can chat (the Audience is ready); startsNow = a Study started now runs at once, without leftOut Minds whose training failed for good; learning = ready Minds still learning from their sources in the background; fullyTrained = none still learning; research.phase = researching while the Audience's background research runs (it is usable meanwhile), researched once merged and applied."
  4. Changed1 schema field changed
    • addedOutput schema / properties / existingAudiences
      Added value: +{
      +  "anyOf": [
      +    {
      +      "items": {},
      +      "type": "array"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "description": "The caller's existing Audiences with exactly this name (id, name, workspaceUrl), when a new brief was started; this call still creates a separate Audience."
      +}
  5. Changed10 schema fields changed
    • changedInput schema / properties / composition / properties / datasetSegmentation / description
      Previous value: -"Reviewed variable roles, distributions, and privacy-safe pairwise relationships returned by preview_audience_dataset_segmentation. Requires audienceCreationMode=\"benchmark_depth\". Structural variables shape one generalizable representative cohort; outcomes remain held out and joint combinations remain audit evidence only. Copy `respondentCount` and `recommendedMindCount` through from the preview — they cap the cohort size."New value: +"Which variables of a respondent dataset shape the cohort. A draft whose research.files include a respondent dataset (XLS, XLSX, CSV, SPSS .sav; Pro plan, audienceCreationMode=\"benchmark_depth\") reads it and proposes this selection itself; its review lists every variable with its role and observed shares. Omit this on the first draft. To change the variables, revise that draft (draft.preview:true with its id and sha256, the same brief and research.files) passing {fileName, sheetName, segmentationColumns} from the review with the keys the user chose. Structural variables shape one representative cohort; outcomes stay held out."
    • changedInput schema / properties / composition / properties / datasetSegmentation / properties / columns / description
      Previous value: -"Column-level distributions from the preview. Used when `variables` is absent."New value: +"Legacy: column-level distributions, used when `variables` is absent. Omit with a selection."
    • changedInput schema / properties / composition / properties / datasetSegmentation / properties / combinations / description
      Previous value: -"Observed joint profiles as audit counts. Copy the ids and counts from the preview; per-cell values are not needed."New value: +"Legacy: observed joint profiles as audit counts. Omit with a selection."
    • addedInput schema / properties / composition / properties / datasetSegmentation / properties / fileName / description
      Added value: +"The dataset's file name, as the draft's datasetSegmentation review names it. The same file must be in research.files (or conversationFiles)."
    • changedInput schema / properties / composition / properties / datasetSegmentation / properties / recommendedMindCount / description
      Previous value: -"Preview-recommended cohort size. Caps how many Minds the benchmark run creates."New value: +"Legacy: preview-recommended cohort size, which caps the cohort. Omit with a selection."
    • changedInput schema / properties / composition / properties / datasetSegmentation / properties / respondentCount / description
      Previous value: -"Total respondent rows in the reviewed sheet, copied from the preview."New value: +"Legacy: total respondent rows in the reviewed sheet. Omit with a selection."
    • changedInput schema / properties / composition / properties / datasetSegmentation / properties / variables / description
      Previous value: -"Variable-level distributions from the preview (preferred over `columns` when present)."New value: +"Legacy: variable-level distributions (preferred over `columns` when present). Omit with a selection."
    • changedInput schema / properties / composition / properties / datasetSegmentation / required
      Previous value: -[
      -  "fileName",
      -  "segmentationColumns",
      -  "combinations"
      -]New value: +[
      +  "fileName",
      +  "segmentationColumns"
      +]
    • changedInput schema / properties / composition / properties / trainMembers / description
      Previous value: -"Deprecated; omit it. Every member of every Audience is trained individually in the background, including reviewed-dataset cohorts of more than ~40 Minds (each keeps its deterministic cohort profile and the request locale). true is accepted as a no-op; false is rejected, because it used to create untrained Minds with an empty system prompt that reported ready. Cost and time: one Mind training per member; a 100-Mind cohort takes tens of minutes to a few hours. The tool returns as soon as the Audience exists (structuredContent.audience.memberTraining reports what was queued); wait until every member reports readyToChat (get_mind_status, GET /api/v1/minds/{id}/training, or readiness.isReady from GET /api/v1/audiences/{id}/progress) before running a Study, which refuses Audiences with untrained members; the Audience is ready at that point. Members keep learning from their sources in the background for a few more minutes (readiness.learning, then readiness.fullyTrained); nothing needs to wait for it. readyToChat means the member can answer, not that it researched anything: a member whose collection found nothing keeps one generated context item and still reports ready, so check knowledgeState.fallbackOnly on the members before treating the Audience as evidence-backed."New value: +"Deprecated; omit it. Every member of every Audience is trained individually in the background, including reviewed-dataset cohorts of more than ~40 Minds (each keeps its deterministic cohort profile and the request locale). true is accepted as a no-op; false is rejected, because it used to create untrained Minds with an empty system prompt that reported ready. Cost and time: one Mind training per member; a 100-Mind cohort takes tens of minutes to a few hours. The tool returns as soon as the Audience exists (structuredContent.audience.memberTraining reports what was queued); wait until every member reports readyToChat (readiness.isReady when this tool is called again with the returned operationId) before running a Study, which refuses Audiences with untrained members; the Audience is ready at that point. Members keep learning from their sources in the background for a few more minutes (readiness.learning, then readiness.fullyTrained); nothing needs to wait for it. readyToChat means the member can answer, not that it researched anything: a member whose collection found nothing keeps one generated context item and still reports ready, so check knowledgeState.fallbackOnly on the members before treating the Audience as evidence-backed."
    • changedInput schema / properties / grounding / properties / preview / description
      Previous value: -"Review the quota axes BEFORE any Mind exists. When true, the server runs research grounding and deterministic cohort allocation without creating an Audience or Minds or consuming a generation allowance. To revise a saved preview without repeating research, pass its unchanged reviewedGroundingJson/SHA pair together with groundingPreview and the revised exclusion/allocation options. Fresh research uses the same durable operation as the public REST API; this tool returns its operation immediately so the widget can stream sources and distributions. New briefs default to the full webapp draft with proposed Minds; reviewed respondent datasets use a quota-only review. Setting false without reviewed evidence still returns a preview. Present the plan and wait until the user confirms it, then set grounding.preview:false with the unchanged reviewedGroundingJson/SHA pair and the same allocation options. Supplying saved evidence without an explicit false keeps it in review. The response includes effective target percentages and integer counts; explicit allocation targets that do not match grounded axes fail closed."New value: +"Review the quota axes BEFORE any Mind exists. When true, the server runs research grounding and deterministic cohort allocation without creating an Audience or Minds or consuming a generation allowance. To revise a saved preview without repeating research, pass its unchanged reviewedGroundingJson/SHA pair together with groundingPreview and the revised exclusion/allocation options. Fresh research uses the same durable operation as the public REST API; this tool returns its operation immediately so the widget can stream sources and distributions. New briefs, including respondent datasets, default to the full webapp draft with proposed Minds; only a legacy full dataset payload uses a quota-only review. Setting false without reviewed evidence still returns a preview. Present the plan and wait until the user confirms it, then set grounding.preview:false with the unchanged reviewedGroundingJson/SHA pair and the same allocation options. Supplying saved evidence without an explicit false keeps it in review. The response includes effective target percentages and integer counts; explicit allocation targets that do not match grounded axes fail closed."
  6. Changed2 schema fields changed
    • addedInput schema / properties / composition / properties / trainMembers
      Added value: +{
      +  "description": "Deprecated; omit it. Every member of every Audience is trained individually in the background, including reviewed-dataset cohorts of more than ~40 Minds (each keeps its deterministic cohort profile and the request locale). true is accepted as a no-op; false is rejected, because it used to create untrained Minds with an empty system prompt that reported ready. Cost and time: one Mind training per member; a 100-Mind cohort takes tens of minutes to a few hours. The tool returns as soon as the Audience exists (structuredContent.audience.memberTraining reports what was queued); wait until every member reports readyToChat (get_mind_status, GET /api/v1/minds/{id}/training, or readiness.isReady from GET /api/v1/audiences/{id}/progress) before running a Study, which refuses Audiences with untrained members; the Audience is ready at that point. Members keep learning from their sources in the background for a few more minutes (readiness.learning, then readiness.fullyTrained); nothing needs to wait for it. readyToChat means the member can answer, not that it researched anything: a member whose collection found nothing keeps one generated context item and still reports ready, so check knowledgeState.fallbackOnly on the members before treating the Audience as evidence-backed.",
      +  "type": "boolean"
      +}
    • changedInput schema / properties / draft / description
      Previous value: -"The webapp Audience draft workflow. Preview proposes Minds before Create; id and sha256 identify the exact reviewed roster. Rework revises that draft. Set preview:false with both id and sha256 only after the user confirms the displayed draft."New value: +"The webapp Audience draft workflow. Preview proposes Minds before Create; id and sha256 identify the exact reviewed roster. Rework revises that draft. Set preview:false with both id and sha256 only after the user confirms the displayed draft; that confirmation needs nothing else (omit the brief and every other option): the server creates exactly the reviewed draft from its stored request."
  7. Changed1 schema field changed
    • changedInput schema / properties / composition / properties / audienceCreationMode / description
      Previous value: -"How the Audience is sized. \"balanced\" (default): compact and representative for everyday research. It is the only mode with a hard wall on a size you state — a memberCount above 20 is refused with 403 MODE_CAP. \"segment_coverage\": two representatives per limiting grounded cell, from a 10-Mind floor; automatic sizing stops at 50, but a memberCount you state is bounded only by your plan. \"benchmark_depth\": repeated representation of limiting grounded cells for validation-ready segmentation; bounded by your plan allowance. The deeper two require a Team (enterprise) plan — on other plans the server SILENTLY downgrades to \"balanced\" and echoes the effective mode in structuredContent.audience.audienceCreationMode. Call get_audience_limits to see the ceilings that apply to your account."New value: +"How the Audience is sized. \"balanced\" (default): compact and representative for everyday research. It is the only mode with a hard wall on a size you state — a memberCount above 20 is refused with 403 MODE_CAP. \"segment_coverage\": two representatives per limiting grounded cell, from a 10-Mind floor; automatic sizing stops at 50, but a memberCount you state is bounded only by your plan. \"benchmark_depth\": repeated representation of limiting grounded cells for validation-ready segmentation; bounded by your plan allowance. The deeper two require a Pro or Enterprise plan — on other plans the server SILENTLY downgrades to \"balanced\" and echoes the effective mode in structuredContent.audience.audienceCreationMode. Call get_audience_limits to see the ceilings that apply to your account."
  8. Changed4 schema fields changed
    • changedInput schema / properties / draft / description
      Previous value: -"The webapp Audience draft workflow. Preview proposes real Minds before Create; id and sha256 identify the exact reviewed roster. Rework revises that draft."New value: +"The webapp Audience draft workflow. Preview proposes Minds before Create; id and sha256 identify the exact reviewed roster. Rework revises that draft. Set preview:false with both id and sha256 only after the user confirms the displayed draft."
    • changedInput schema / properties / grounding / properties / preview / description
      Previous value: -"Review the quota axes BEFORE any Mind exists. When true, the server runs research grounding and deterministic cohort allocation without creating an Audience or Minds or consuming a generation allowance. To revise a saved preview without repeating research, pass its unchanged reviewedGroundingJson/SHA pair together with groundingPreview and the revised exclusion/allocation options. Fresh research uses the same durable operation as the public REST API; this tool returns its operation immediately so the widget can stream sources and distributions. New briefs default to the full webapp draft with proposed Minds; set grounding.preview:true only for a quota-only review. The response includes effective target percentages and integer counts; explicit allocation targets that do not match grounded axes fail closed. Present the plan to the user, then call again without groundingPreview and pass reviewedGroundingJson plus reviewedGroundingSha256 unchanged with the same allocation options."New value: +"Review the quota axes BEFORE any Mind exists. When true, the server runs research grounding and deterministic cohort allocation without creating an Audience or Minds or consuming a generation allowance. To revise a saved preview without repeating research, pass its unchanged reviewedGroundingJson/SHA pair together with groundingPreview and the revised exclusion/allocation options. Fresh research uses the same durable operation as the public REST API; this tool returns its operation immediately so the widget can stream sources and distributions. New briefs default to the full webapp draft with proposed Minds; reviewed respondent datasets use a quota-only review. Setting false without reviewed evidence still returns a preview. Present the plan and wait until the user confirms it, then set grounding.preview:false with the unchanged reviewedGroundingJson/SHA pair and the same allocation options. Supplying saved evidence without an explicit false keeps it in review. The response includes effective target percentages and integer counts; explicit allocation targets that do not match grounded axes fail closed."
    • removedOutput schema / properties / workspaceUrl / anyOf
      Removed value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / workspaceUrl / type
      Added value: +[
      +  "string",
      +  "null"
      +]
  9. Changed3 schema fields changed
    • addedInput schema / properties / conversationFiles
      Added value: +{
      +  "description": "Research files (screener, questionnaire, report, respondent data), read like research.files. 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"
      +}
    • changedInput schema / properties / research / properties / files / description
      Previous value: -"Optional already-uploaded research files. 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. The server analyzes these through the same extended screener/questionnaire path as the in-app New Audience uploader, including study roles, screening and quota rules, review distributions, and grounding provenance."New value: +"Optional already-uploaded research files. 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. The server analyzes these through the same extended screener/questionnaire path as the in-app New Audience uploader, including study roles, screening and quota rules, review distributions, and grounding provenance."
    • changedInput schema / properties / research / properties / files / items / properties / url / description
      Previous value: -"URL of an already-uploaded file. 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: +"URL of an already-uploaded file. 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."
  10. Changed2 schema fields changed
    • changedInput schema / properties / research / properties / files / description
      Previous value: -"Optional already-uploaded research files. 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. The server analyzes these through the same extended screener/questionnaire path as the in-app New Audience uploader, including study roles, screening and quota rules, review distributions, and grounding provenance."New value: +"Optional already-uploaded research files. 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. The server analyzes these through the same extended screener/questionnaire path as the in-app New Audience uploader, including study roles, screening and quota rules, review distributions, and grounding provenance."
    • changedInput schema / properties / research / properties / files / items / properties / url / description
      Previous value: -"URL of an already-uploaded file. 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: +"URL of an already-uploaded file. 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."
  11. Changed6 schema fields changed
    • addedInput schema / properties / draft
      Added value: +{
      +  "description": "The webapp Audience draft workflow. Preview proposes real Minds before Create; id and sha256 identify the exact reviewed roster. Rework revises that draft.",
      +  "properties": {
      +    "id": {
      +      "format": "uuid",
      +      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      +      "type": "string"
      +    },
      +    "preview": {
      +      "type": "boolean"
      +    },
      +    "rework": {
      +      "maxLength": 200000,
      +      "type": "string"
      +    },
      +    "sha256": {
      +      "pattern": "^[a-f0-9]{64}$",
      +      "type": "string"
      +    }
      +  },
      +  "type": "object"
      +}
    • changedInput schema / properties / grounding / properties / preview / description
      Previous value: -"Review the quota axes BEFORE any Mind exists. When true, the server runs research grounding and deterministic cohort allocation without creating an Audience or Minds or consuming a generation allowance. To revise a saved preview without repeating research, pass its unchanged reviewedGroundingJson/SHA pair together with groundingPreview and the revised exclusion/allocation options. Fresh research uses the same durable operation as the public REST API; this tool polls it to completion. The response includes effective target percentages and integer counts; explicit allocation targets that do not match grounded axes fail closed. Present the plan to the user, then call again without groundingPreview and pass reviewedGroundingJson plus reviewedGroundingSha256 unchanged with the same allocation options."New value: +"Review the quota axes BEFORE any Mind exists. When true, the server runs research grounding and deterministic cohort allocation without creating an Audience or Minds or consuming a generation allowance. To revise a saved preview without repeating research, pass its unchanged reviewedGroundingJson/SHA pair together with groundingPreview and the revised exclusion/allocation options. Fresh research uses the same durable operation as the public REST API; this tool returns its operation immediately so the widget can stream sources and distributions. New briefs default to the full webapp draft with proposed Minds; set grounding.preview:true only for a quota-only review. The response includes effective target percentages and integer counts; explicit allocation targets that do not match grounded axes fail closed. Present the plan to the user, then call again without groundingPreview and pass reviewedGroundingJson plus reviewedGroundingSha256 unchanged with the same allocation options."
    • changedInput schema / properties / operationId / description
      Previous value: -"Resume a queued preview or creation by its returned jobId. Reads its v1 operation status without creating or charging anything. Supply this alone; do not repeat the creation brief to check progress."New value: +"Resume a queued preview or creation by its returned jobId. Reads its v1 operation status without creating or charging anything. Supply this alone; do not repeat the creation brief to check progress. Once the creation completed, the result also says whether every Mind can chat yet (the Audience is ready then) and how many are still learning from their sources in the background; call it again to follow that."
    • addedOutput schema / properties / audienceReview
      Added value: +{
      +  "description": "Reviewed Audience brief, distributions and creation options for the widget."
      +}
    • addedOutput schema / properties / preview
      Added value: +{
      +  "description": "Research and allocation preview; no Audience or Minds have been created."
      +}
    • addedOutput schema / properties / readiness
      Added value: +{
      +  "description": "When a completed operation is read back: member rollup from GET /api/v1/audiences/{id}/progress. isReady = every Mind can chat (the Audience is ready); learning = ready Minds still learning from their sources in the background; fullyTrained = none still learning; research.phase = researching while the Audience's background research runs (it is usable meanwhile), researched once merged and applied."
      +}
  12. Changed2 schema fields changed
    • changedInput schema / properties / research / properties / files / description
      Previous value: -"Optional already-uploaded research files. MCP cannot read or upload a local file:// path. Use a fetchable HTTP(S) URL, a signed URL supplied by the client for the attached file, or an existing Minds workspace upload URL/path. Study tools import external file URLs into durable Minds storage before saving or running. A workspace upload reused as a Study asset must sit under chat/<userId>/: request the signed upload with folder \"chat\" and pass that storage path or its /api/uploads/chat/ URL. A temp/, portfolio/, or context/ path — and any /api/uploads/file-access/ URL — is refused as not belonging to the workspace owner and is never re-fetched; pass a plain external URL instead. The Study refuses to start if Minds cannot read the asset. The server analyzes these through the same extended screener/questionnaire path as the in-app New Audience uploader, including study roles, screening and quota rules, review distributions, and grounding provenance."New value: +"Optional already-uploaded research files. 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. The server analyzes these through the same extended screener/questionnaire path as the in-app New Audience uploader, including study roles, screening and quota rules, review distributions, and grounding provenance."
    • changedInput schema / properties / research / properties / files / items / properties / url / description
      Previous value: -"URL of an already-uploaded file. MCP cannot read or upload a local file:// path. Use a fetchable HTTP(S) URL, a signed URL supplied by the client for the attached file, or an existing Minds workspace upload URL/path. Study tools import external file URLs into durable Minds storage before saving or running. A workspace upload reused as a Study asset must sit under chat/<userId>/: request the signed upload with folder \"chat\" and pass that storage path or its /api/uploads/chat/ URL. A temp/, portfolio/, or context/ path — and any /api/uploads/file-access/ URL — is refused as not belonging to the workspace owner and is never re-fetched; pass a plain external URL instead. The Study refuses to start if Minds cannot read the asset."New value: +"URL of an already-uploaded file. 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."
  13. Changed1 schema field changed
    • changedInput schema / properties / research / properties / includeWebSearch / description
      Previous value: -"Set false to skip Exa web search and extraction completely. The Audience is then grounded only on the brief and supplied files, links, keywords, and structurally parsed respondent data."New value: +"Set false to skip Exa web search and extraction completely. The Audience is then grounded only on the brief and supplied files, links, keywords, and structurally parsed respondent data. Note that a study report, questionnaire, screener or respondent dataset grounds the Audience but is deliberately withheld from the members' own knowledge, so it cannot be the evidence they answer from; with nothing left to ground on, creation is refused rather than producing Minds with no evidence. Leave it true unless the supplied sources include material the members themselves should read."
  14. Changed18 schema fields changed
    • removedInput schema / properties / audienceCreationMode
      Removed value: -{
      -  "description": "How the Audience is sized. \"balanced\" (default): compact and representative for everyday research. It is the only mode with a hard wall on a size you state — a memberCount above 20 is refused with 403 MODE_CAP. \"segment_coverage\": two representatives per limiting grounded cell, from a 10-Mind floor; automatic sizing stops at 50, but a memberCount you state is bounded only by your plan. \"benchmark_depth\": repeated representation of limiting grounded cells for validation-ready segmentation; bounded by your plan allowance. The deeper two require a Team (enterprise) plan — on other plans the server SILENTLY downgrades to \"balanced\" and echoes the effective mode in structuredContent.audience.audienceCreationMode. Call get_audience_limits to see the ceilings that apply to your account.",
      -  "enum": [
      -    "balanced",
      -    "segment_coverage",
      -    "benchmark_depth"
      -  ],
      -  "type": "string"
      -}
    • removedInput schema / properties / cohortAllocation
      Removed value: -{
      -  "description": "Deterministic allocation controls. Reviewed respondent datasets default to observed, which preserves the strongest privacy-safe structural relationships while keeping exact marginals; other sources default to independence. Use distributionNames/maxDistributions to choose axes, minSegmentCount for a feasible floor, and seed for reproducible external runs.",
      -  "properties": {
      -    "distributionNames": {
      -      "items": {
      -        "type": "string"
      -      },
      -      "maxItems": 500,
      -      "type": "array"
      -    },
      -    "enabled": {
      -      "type": "boolean"
      -    },
      -    "includeProfilesInResponse": {
      -      "type": "boolean"
      -    },
      -    "jointStrategy": {
      -      "enum": [
      -        "independent",
      -        "aligned",
      -        "observed"
      -      ],
      -      "type": "string"
      -    },
      -    "maxDistributions": {
      -      "maximum": 500,
      -      "minimum": 1,
      -      "type": "integer"
      -    },
      -    "minSegmentCount": {
      -      "maximum": 20,
      -      "minimum": 0,
      -      "type": "integer"
      -    },
      -    "seed": {
      -      "maxLength": 200,
      -      "type": "string"
      -    },
      -    "targetOverrides": {
      -      "items": {
      -        "properties": {
      -          "distribution": {
      -            "type": "string"
      -          },
      -          "segments": {
      -            "items": {
      -              "properties": {
      -                "label": {
      -                  "type": "string"
      -                },
      -                "pct": {
      -                  "maximum": 100,
      -                  "minimum": 0,
      -                  "type": "number"
      -                }
      -              },
      -              "required": [
      -                "label",
      -                "pct"
      -              ],
      -              "type": "object"
      -            },
      -            "maxItems": 200,
      -            "type": "array"
      -          }
      -        },
      -        "required": [
      -          "distribution",
      -          "segments"
      -        ],
      -        "type": "object"
      -      },
      -      "maxItems": 500,
      -      "type": "array"
      -    }
      -  },
      -  "type": "object"
      -}
    • addedInput schema / properties / composition
      Added value: +{
      +  "description": "How many Minds to create and how the cohort is allocated across the grounded axes.",
      +  "properties": {
      +    "audienceCreationMode": {
      +      "description": "How the Audience is sized. \"balanced\" (default): compact and representative for everyday research. It is the only mode with a hard wall on a size you state — a memberCount above 20 is refused with 403 MODE_CAP. \"segment_coverage\": two representatives per limiting grounded cell, from a 10-Mind floor; automatic sizing stops at 50, but a memberCount you state is bounded only by your plan. \"benchmark_depth\": repeated representation of limiting grounded cells for validation-ready segmentation; bounded by your plan allowance. The deeper two require a Team (enterprise) plan — on other plans the server SILENTLY downgrades to \"balanced\" and echoes the effective mode in structuredContent.audience.audienceCreationMode. Call get_audience_limits to see the ceilings that apply to your account.",
      +      "enum": [
      +        "balanced",
      +        "segment_coverage",
      +        "benchmark_depth"
      +      ],
      +      "type": "string"
      +    },
      +    "cohortAllocation": {
      +      "description": "Deterministic allocation controls. Reviewed respondent datasets default to observed, which preserves the strongest privacy-safe structural relationships while keeping exact marginals; other sources default to independence. Use distributionNames/maxDistributions to choose axes, minSegmentCount for a feasible floor, and seed for reproducible external runs.",
      +      "properties": {
      +        "distributionNames": {
      +          "items": {
      +            "type": "string"
      +          },
      +          "maxItems": 500,
      +          "type": "array"
      +        },
      +        "enabled": {
      +          "type": "boolean"
      +        },
      +        "includeProfilesInResponse": {
      +          "type": "boolean"
      +        },
      +        "jointStrategy": {
      +          "enum": [
      +            "independent",
      +            "aligned",
      +            "observed"
      +          ],
      +          "type": "string"
      +        },
      +        "maxDistributions": {
      +          "maximum": 500,
      +          "minimum": 1,
      +          "type": "integer"
      +        },
      +        "minSegmentCount": {
      +          "maximum": 20,
      +          "minimum": 0,
      +          "type": "integer"
      +        },
      +        "seed": {
      +          "maxLength": 200,
      +          "type": "string"
      +        },
      +        "targetOverrides": {
      +          "items": {
      +            "properties": {
      +              "distribution": {
      +                "type": "string"
      +              },
      +              "segments": {
      +                "items": {
      +                  "properties": {
      +                    "label": {
      +                      "type": "string"
      +                    },
      +                    "pct": {
      +                      "maximum": 100,
      +                      "minimum": 0,
      +                      "type": "number"
      +                    }
      +                  },
      +                  "required": [
      +                    "label",
      +                    "pct"
      +                  ],
      +                  "type": "object"
      +                },
      +                "maxItems": 200,
      +                "type": "array"
      +              }
      +            },
      +            "required": [
      +              "distribution",
      +              "segments"
      +            ],
      +            "type": "object"
      +          },
      +          "maxItems": 500,
      +          "type": "array"
      +        }
      +      },
      +      "type": "object"
      +    },
      +    "datasetSegmentation": {
      +      "description": "Reviewed variable roles, distributions, and privacy-safe pairwise relationships returned by preview_audience_dataset_segmentation. Requires audienceCreationMode=\"benchmark_depth\". Structural variables shape one generalizable representative cohort; outcomes remain held out and joint combinations remain audit evidence only. Copy `respondentCount` and `recommendedMindCount` through from the preview — they cap the cohort size.",
      +      "properties": {
      +        "columns": {
      +          "description": "Column-level distributions from the preview. Used when `variables` is absent.",
      +          "items": {
      +            "properties": {
      +              "distribution": {
      +                "items": {
      +                  "properties": {
      +                    "respondentCount": {
      +                      "maximum": 9007199254740991,
      +                      "minimum": 0,
      +                      "type": "integer"
      +                    },
      +                    "sharePct": {
      +                      "minimum": 0,
      +                      "type": "number"
      +                    },
      +                    "value": {
      +                      "default": "",
      +                      "type": "string"
      +                    }
      +                  },
      +                  "required": [
      +                    "value",
      +                    "respondentCount",
      +                    "sharePct"
      +                  ],
      +                  "type": "object"
      +                },
      +                "maxItems": 30,
      +                "type": "array"
      +              },
      +              "key": {
      +                "type": "string"
      +              },
      +              "label": {
      +                "type": "string"
      +              },
      +              "otherRespondentCount": {
      +                "maximum": 9007199254740991,
      +                "minimum": 0,
      +                "type": "integer"
      +              },
      +              "validRespondentCount": {
      +                "maximum": 9007199254740991,
      +                "minimum": 0,
      +                "type": "integer"
      +              }
      +            },
      +            "required": [
      +              "key",
      +              "label",
      +              "distribution"
      +            ],
      +            "type": "object"
      +          },
      +          "maxItems": 200,
      +          "type": "array"
      +        },
      +        "combinations": {
      +          "description": "Observed joint profiles as audit counts. Copy the ids and counts from the preview; per-cell values are not needed.",
      +          "items": {
      +            "properties": {
      +              "id": {
      +                "type": "string"
      +              },
      +              "respondentCount": {
      +                "exclusiveMinimum": 0,
      +                "maximum": 9007199254740991,
      +                "type": "integer"
      +              },
      +              "sharePct": {
      +                "minimum": 0,
      +                "type": "number"
      +              }
      +            },
      +            "required": [
      +              "id",
      +              "respondentCount",
      +              "sharePct"
      +            ],
      +            "type": "object"
      +          },
      +          "maxItems": 5000,
      +          "type": "array"
      +        },
      +        "fileName": {
      +          "type": "string"
      +        },
      +        "recommendedMindCount": {
      +          "description": "Preview-recommended cohort size. Caps how many Minds the benchmark run creates.",
      +          "exclusiveMinimum": 0,
      +          "maximum": 9007199254740991,
      +          "type": "integer"
      +        },
      +        "respondentCount": {
      +          "description": "Total respondent rows in the reviewed sheet, copied from the preview.",
      +          "maximum": 9007199254740991,
      +          "minimum": 0,
      +          "type": "integer"
      +        },
      +        "retainedCombinationIds": {
      +          "items": {
      +            "type": "string"
      +          },
      +          "maxItems": 5000,
      +          "type": "array"
      +        },
      +        "segmentationColumns": {
      +          "description": "Keys of the variables the user kept after review. These are the only ones that shape the cohort.",
      +          "items": {
      +            "type": "string"
      +          },
      +          "maxItems": 200,
      +          "minItems": 1,
      +          "type": "array"
      +        },
      +        "sheetName": {
      +          "type": "string"
      +        },
      +        "variables": {
      +          "description": "Variable-level distributions from the preview (preferred over `columns` when present).",
      +          "items": {
      +            "properties": {
      +              "distribution": {
      +                "items": {
      +                  "properties": {
      +                    "respondentCount": {
      +                      "maximum": 9007199254740991,
      +                      "minimum": 0,
      +                      "type": "integer"
      +                    },
      +                    "sharePct": {
      +                      "minimum": 0,
      +                      "type": "number"
      +                    },
      +                    "value": {
      +                      "default": "",
      +                      "type": "string"
      +                    }
      +                  },
      +                  "required": [
      +                    "value",
      +                    "respondentCount",
      +                    "sharePct"
      +                  ],
      +                  "type": "object"
      +                },
      +                "maxItems": 30,
      +                "type": "array"
      +              },
      +              "key": {
      +                "type": "string"
      +              },
      +              "label": {
      +                "type": "string"
      +              },
      +              "otherRespondentCount": {
      +                "maximum": 9007199254740991,
      +                "minimum": 0,
      +                "type": "integer"
      +              },
      +              "validRespondentCount": {
      +                "maximum": 9007199254740991,
      +                "minimum": 0,
      +                "type": "integer"
      +              }
      +            },
      +            "required": [
      +              "key",
      +              "label",
      +              "distribution"
      +            ],
      +            "type": "object"
      +          },
      +          "maxItems": 200,
      +          "type": "array"
      +        }
      +      },
      +      "required": [
      +        "fileName",
      +        "segmentationColumns",
      +        "combinations"
      +      ],
      +      "type": "object"
      +    },
      +    "excludeDistributions": {
      +      "description": "Exact axis names whose composition quotas should be removed. Age remains as one eligibility range without within-range shares; explicit gender membership remains enforced. Include required eligibility axes in cohortAllocation.distributionNames. Original evidence stays in reviewDistributions.",
      +      "items": {
      +        "maxLength": 200,
      +        "minLength": 1,
      +        "type": "string"
      +      },
      +      "maxItems": 200,
      +      "type": "array"
      +    },
      +    "memberCount": {
      +      "description": "Exact number of Minds to create. Pass this whenever the user states a size (\"exactly 50 per region\", \"genau 50 Minds je Zelle\") instead of relying on the server to parse the number out of the brief. When omitted, the size is inferred from the brief and, failing that, from the creation mode's evidence-based automatic sizing. Two separate refusals apply: 403 MODE_CAP above 20 in \"balanced\" mode (switch to segment_coverage or benchmark_depth), and 403 PLAN_LIMIT above your plan's per-Audience cap. The 6000 accepted here is the absolute system ceiling, not your allowance — call get_audience_limits for the real one. The Audience is never created at a partial size.",
      +      "exclusiveMinimum": 0,
      +      "maximum": 6000,
      +      "type": "integer"
      +    }
      +  },
      +  "type": "object"
      +}
    • removedInput schema / properties / datasetSegmentation
      Removed value: -{
      -  "description": "Reviewed variable roles, distributions, and privacy-safe pairwise relationships returned by preview_audience_dataset_segmentation. Requires audienceCreationMode=\"benchmark_depth\". Structural variables shape one generalizable representative cohort; outcomes remain held out and joint combinations remain audit evidence only. Copy `respondentCount` and `recommendedMindCount` through from the preview — they cap the cohort size.",
      -  "properties": {
      -    "columns": {
      -      "description": "Column-level distributions from the preview. Used when `variables` is absent.",
      -      "items": {
      -        "properties": {
      -          "distribution": {
      -            "items": {
      -              "properties": {
      -                "respondentCount": {
      -                  "maximum": 9007199254740991,
      -                  "minimum": 0,
      -                  "type": "integer"
      -                },
      -                "sharePct": {
      -                  "minimum": 0,
      -                  "type": "number"
      -                },
      -                "value": {
      -                  "default": "",
      -                  "type": "string"
      -                }
      -              },
      -              "required": [
      -                "value",
      -                "respondentCount",
      -                "sharePct"
      -              ],
      -              "type": "object"
      -            },
      -            "maxItems": 30,
      -            "type": "array"
      -          },
      -          "key": {
      -            "type": "string"
      -          },
      -          "label": {
      -            "type": "string"
      -          },
      -          "otherRespondentCount": {
      -            "maximum": 9007199254740991,
      -            "minimum": 0,
      -            "type": "integer"
      -          },
      -          "validRespondentCount": {
      -            "maximum": 9007199254740991,
      -            "minimum": 0,
      -            "type": "integer"
      -          }
      -        },
      -        "required": [
      -          "key",
      -          "label",
      -          "distribution"
      -        ],
      -        "type": "object"
      -      },
      -      "maxItems": 200,
      -      "type": "array"
      -    },
      -    "combinations": {
      -      "description": "Observed joint profiles as audit counts. Copy the ids and counts from the preview; per-cell values are not needed.",
      -      "items": {
      -        "properties": {
      -          "id": {
      -            "type": "string"
      -          },
      -          "respondentCount": {
      -            "exclusiveMinimum": 0,
      -            "maximum": 9007199254740991,
      -            "type": "integer"
      -          },
      -          "sharePct": {
      -            "minimum": 0,
      -            "type": "number"
      -          }
      -        },
      -        "required": [
      -          "id",
      -          "respondentCount",
      -          "sharePct"
      -        ],
      -        "type": "object"
      -      },
      -      "maxItems": 5000,
      -      "type": "array"
      -    },
      -    "fileName": {
      -      "type": "string"
      -    },
      -    "recommendedMindCount": {
      -      "description": "Preview-recommended cohort size. Caps how many Minds the benchmark run creates.",
      -      "exclusiveMinimum": 0,
      -      "maximum": 9007199254740991,
      -      "type": "integer"
      -    },
      -    "respondentCount": {
      -      "description": "Total respondent rows in the reviewed sheet, copied from the preview.",
      -      "maximum": 9007199254740991,
      -      "minimum": 0,
      -      "type": "integer"
      -    },
      -    "retainedCombinationIds": {
      -      "items": {
      -        "type": "string"
      -      },
      -      "maxItems": 5000,
      -      "type": "array"
      -    },
      -    "segmentationColumns": {
      -      "description": "Keys of the variables the user kept after review. These are the only ones that shape the cohort.",
      -      "items": {
      -        "type": "string"
      -      },
      -      "maxItems": 200,
      -      "minItems": 1,
      -      "type": "array"
      -    },
      -    "sheetName": {
      -      "type": "string"
      -    },
      -    "variables": {
      -      "description": "Variable-level distributions from the preview (preferred over `columns` when present).",
      -      "items": {
      -        "properties": {
      -          "distribution": {
      -            "items": {
      -              "properties": {
      -                "respondentCount": {
      -                  "maximum": 9007199254740991,
      -                  "minimum": 0,
      -                  "type": "integer"
      -                },
      -                "sharePct": {
      -                  "minimum": 0,
      -                  "type": "number"
      -                },
      -                "value": {
      -                  "default": "",
      -                  "type": "string"
      -                }
      -              },
      -              "required": [
      -                "value",
      -                "respondentCount",
      -                "sharePct"
      -              ],
      -              "type": "object"
      -            },
      -            "maxItems": 30,
      -            "type": "array"
      -          },
      -          "key": {
      -            "type": "string"
      -          },
      -          "label": {
      -            "type": "string"
      -          },
      -          "otherRespondentCount": {
      -            "maximum": 9007199254740991,
      -            "minimum": 0,
      -            "type": "integer"
      -          },
      -          "validRespondentCount": {
      -            "maximum": 9007199254740991,
      -            "minimum": 0,
      -            "type": "integer"
      -          }
      -        },
      -        "required": [
      -          "key",
      -          "label",
      -          "distribution"
      -        ],
      -        "type": "object"
      -      },
      -      "maxItems": 200,
      -      "type": "array"
      -    }
      -  },
      -  "required": [
      -    "fileName",
      -    "segmentationColumns",
      -    "combinations"
      -  ],
      -  "type": "object"
      -}
    • removedInput schema / properties / excludeDistributions
      Removed value: -{
      -  "description": "Exact axis names whose composition quotas should be removed. Age remains as one eligibility range without within-range shares; explicit gender membership remains enforced. Include required eligibility axes in cohortAllocation.distributionNames. Original evidence stays in reviewDistributions.",
      -  "items": {
      -    "maxLength": 200,
      -    "minLength": 1,
      -    "type": "string"
      -  },
      -  "maxItems": 200,
      -  "type": "array"
      -}
    • removedInput schema / properties / files
      Removed value: -{
      -  "description": "Optional already-uploaded research files. MCP cannot read or upload a local file:// path. Use a fetchable HTTP(S) URL, a signed URL supplied by the client for the attached file, or an existing Minds workspace upload URL/path. Study tools import external file URLs into durable Minds storage before saving or running. A workspace upload reused as a Study asset must sit under chat/<userId>/: request the signed upload with folder \"chat\" and pass that storage path or its /api/uploads/chat/ URL. A temp/, portfolio/, or context/ path — and any /api/uploads/file-access/ URL — is refused as not belonging to the workspace owner and is never re-fetched; pass a plain external URL instead. The Study refuses to start if Minds cannot read the asset. The server analyzes these through the same extended screener/questionnaire path as the in-app New Audience uploader, including study roles, screening and quota rules, review distributions, and grounding provenance.",
      -  "items": {
      -    "properties": {
      -      "name": {
      -        "description": "File name",
      -        "type": "string"
      -      },
      -      "url": {
      -        "description": "URL of an already-uploaded file. MCP cannot read or upload a local file:// path. Use a fetchable HTTP(S) URL, a signed URL supplied by the client for the attached file, or an existing Minds workspace upload URL/path. Study tools import external file URLs into durable Minds storage before saving or running. A workspace upload reused as a Study asset must sit under chat/<userId>/: request the signed upload with folder \"chat\" and pass that storage path or its /api/uploads/chat/ URL. A temp/, portfolio/, or context/ path — and any /api/uploads/file-access/ URL — is refused as not belonging to the workspace owner and is never re-fetched; pass a plain external URL instead. The Study refuses to start if Minds cannot read the asset.",
      -        "minLength": 1,
      -        "type": "string"
      -      }
      -    },
      -    "required": [
      -      "name",
      -      "url"
      -    ],
      -    "type": "object"
      -  },
      -  "maxItems": 20,
      -  "type": "array"
      -}
    • addedInput schema / properties / grounding
      Added value: +{
      +  "description": "Review the quota axes before any Mind exists, and pass a reviewed snapshot back unchanged to create from it.",
      +  "properties": {
      +    "preview": {
      +      "description": "Review the quota axes BEFORE any Mind exists. When true, the server runs research grounding and deterministic cohort allocation without creating an Audience or Minds or consuming a generation allowance. To revise a saved preview without repeating research, pass its unchanged reviewedGroundingJson/SHA pair together with groundingPreview and the revised exclusion/allocation options. Fresh research uses the same durable operation as the public REST API; this tool polls it to completion. The response includes effective target percentages and integer counts; explicit allocation targets that do not match grounded axes fail closed. Present the plan to the user, then call again without groundingPreview and pass reviewedGroundingJson plus reviewedGroundingSha256 unchanged with the same allocation options.",
      +      "type": "boolean"
      +    },
      +    "reviewedJson": {
      +      "description": "Exact reviewedGroundingJson returned by groundingPreview or import_audience_sources. Pass it unchanged together with reviewedGroundingSha256 on a re-preview or creation call; the server reuses this reviewed snapshot instead of rerunning grounding research.",
      +      "maxLength": 2000000,
      +      "minLength": 1,
      +      "type": "string"
      +    },
      +    "reviewedSha256": {
      +      "description": "SHA-256 returned by the same groundingPreview. Required together with reviewedGroundingJson; any mismatch is rejected before Audience or Mind materialisation.",
      +      "pattern": "^[0-9a-f]{64}$",
      +      "type": "string"
      +    }
      +  },
      +  "type": "object"
      +}
    • removedInput schema / properties / groundingPreview
      Removed value: -{
      -  "description": "Review the quota axes BEFORE any Mind exists. When true, the server runs research grounding and deterministic cohort allocation without creating an Audience or Minds or consuming a generation allowance. To revise a saved preview without repeating research, pass its unchanged reviewedGroundingJson/SHA pair together with groundingPreview and the revised exclusion/allocation options. Fresh research uses the same durable operation as the public REST API; this tool polls it to completion. The response includes effective target percentages and integer counts; explicit allocation targets that do not match grounded axes fail closed. Present the plan to the user, then call again without groundingPreview and pass reviewedGroundingJson plus reviewedGroundingSha256 unchanged with the same allocation options.",
      -  "type": "boolean"
      -}
    • removedInput schema / properties / groupCreationMode
      Removed value: -{
      -  "description": "Legacy alias for audienceCreationMode — same values, same behaviour. How the Audience is sized. \"balanced\" (default): compact and representative for everyday research. It is the only mode with a hard wall on a size you state — a memberCount above 20 is refused with 403 MODE_CAP. \"segment_coverage\": two representatives per limiting grounded cell, from a 10-Mind floor; automatic sizing stops at 50, but a memberCount you state is bounded only by your plan. \"benchmark_depth\": repeated representation of limiting grounded cells for validation-ready segmentation; bounded by your plan allowance. The deeper two require a Team (enterprise) plan — on other plans the server SILENTLY downgrades to \"balanced\" and echoes the effective mode in structuredContent.audience.audienceCreationMode. Call get_audience_limits to see the ceilings that apply to your account.",
      -  "enum": [
      -    "balanced",
      -    "segment_coverage",
      -    "benchmark_depth"
      -  ],
      -  "type": "string"
      -}
    • removedInput schema / properties / includeWebSearch
      Removed value: -{
      -  "default": true,
      -  "description": "Set false to skip Exa web search and extraction completely. The Audience is then grounded only on the brief and supplied files, links, keywords, and structurally parsed respondent data.",
      -  "type": "boolean"
      -}
    • removedInput schema / properties / keywords
      Removed value: -{
      -  "description": "Optional Exa web-search seeds added alongside the brief.",
      -  "items": {
      -    "type": "string"
      -  },
      -  "maxItems": 10,
      -  "type": "array"
      -}
    • removedInput schema / properties / links
      Removed value: -{
      -  "description": "Optional URLs scraped server-side for additional context (e.g. an article describing the population).",
      -  "items": {
      -    "type": "string"
      -  },
      -  "maxItems": 10,
      -  "type": "array"
      -}
    • removedInput schema / properties / memberCount
      Removed value: -{
      -  "description": "Exact number of Minds to create. Pass this whenever the user states a size (\"exactly 50 per region\", \"genau 50 Minds je Zelle\") instead of relying on the server to parse the number out of the brief. When omitted, the size is inferred from the brief and, failing that, from the creation mode's evidence-based automatic sizing. Two separate refusals apply: 403 MODE_CAP above 20 in \"balanced\" mode (switch to segment_coverage or benchmark_depth), and 403 PLAN_LIMIT above your plan's per-Audience cap. The 6000 accepted here is the absolute system ceiling, not your allowance — call get_audience_limits for the real one. The Audience is never created at a partial size.",
      -  "exclusiveMinimum": 0,
      -  "maximum": 6000,
      -  "type": "integer"
      -}
    • addedInput schema / properties / research
      Added value: +{
      +  "description": "Extra material the grounding research reads alongside the brief, and whether web search runs at all.",
      +  "properties": {
      +    "files": {
      +      "description": "Optional already-uploaded research files. MCP cannot read or upload a local file:// path. Use a fetchable HTTP(S) URL, a signed URL supplied by the client for the attached file, or an existing Minds workspace upload URL/path. Study tools import external file URLs into durable Minds storage before saving or running. A workspace upload reused as a Study asset must sit under chat/<userId>/: request the signed upload with folder \"chat\" and pass that storage path or its /api/uploads/chat/ URL. A temp/, portfolio/, or context/ path — and any /api/uploads/file-access/ URL — is refused as not belonging to the workspace owner and is never re-fetched; pass a plain external URL instead. The Study refuses to start if Minds cannot read the asset. The server analyzes these through the same extended screener/questionnaire path as the in-app New Audience uploader, including study roles, screening and quota rules, review distributions, and grounding provenance.",
      +      "items": {
      +        "properties": {
      +          "name": {
      +            "description": "File name",
      +            "type": "string"
      +          },
      +          "url": {
      +            "description": "URL of an already-uploaded file. MCP cannot read or upload a local file:// path. Use a fetchable HTTP(S) URL, a signed URL supplied by the client for the attached file, or an existing Minds workspace upload URL/path. Study tools import external file URLs into durable Minds storage before saving or running. A workspace upload reused as a Study asset must sit under chat/<userId>/: request the signed upload with folder \"chat\" and pass that storage path or its /api/uploads/chat/ URL. A temp/, portfolio/, or context/ path — and any /api/uploads/file-access/ URL — is refused as not belonging to the workspace owner and is never re-fetched; pass a plain external URL instead. The Study refuses to start if Minds cannot read the asset.",
      +            "minLength": 1,
      +            "type": "string"
      +          }
      +        },
      +        "required": [
      +          "name",
      +          "url"
      +        ],
      +        "type": "object"
      +      },
      +      "maxItems": 20,
      +      "type": "array"
      +    },
      +    "includeWebSearch": {
      +      "default": true,
      +      "description": "Set false to skip Exa web search and extraction completely. The Audience is then grounded only on the brief and supplied files, links, keywords, and structurally parsed respondent data.",
      +      "type": "boolean"
      +    },
      +    "keywords": {
      +      "description": "Optional Exa web-search seeds added alongside the brief.",
      +      "items": {
      +        "type": "string"
      +      },
      +      "maxItems": 10,
      +      "type": "array"
      +    },
      +    "links": {
      +      "description": "Optional URLs scraped server-side for additional context (e.g. an article describing the population).",
      +      "items": {
      +        "type": "string"
      +      },
      +      "maxItems": 10,
      +      "type": "array"
      +    }
      +  },
      +  "type": "object"
      +}
    • removedInput schema / properties / reviewedGroundingJson
      Removed value: -{
      -  "description": "Exact reviewedGroundingJson returned by groundingPreview or import_audience_sources. Pass it unchanged together with reviewedGroundingSha256 on a re-preview or creation call; the server reuses this reviewed snapshot instead of rerunning grounding research.",
      -  "maxLength": 2000000,
      -  "minLength": 1,
      -  "type": "string"
      -}
    • removedInput schema / properties / reviewedGroundingSha256
      Removed value: -{
      -  "description": "SHA-256 returned by the same groundingPreview. Required together with reviewedGroundingJson; any mismatch is rejected before Audience or Mind materialisation.",
      -  "pattern": "^[0-9a-f]{64}$",
      -  "type": "string"
      -}
    • removedInput schema / properties / text
      Removed value: -{
      -  "description": "Legacy alias for `brief`. Accepted for back-compat.",
      -  "maxLength": 200000,
      -  "minLength": 1,
      -  "type": "string"
      -}
    • removedInput schema / properties / trainMembers
      Removed value: -{
      -  "description": "Deprecated; omit it. Every member of every Audience is trained individually in the background, including reviewed-dataset cohorts of more than ~40 Minds (each keeps its deterministic cohort profile and the request locale). true is accepted as a no-op; false is rejected, because it used to create untrained Minds with an empty system prompt that reported ready. Cost and time: one Mind training per member; a 100-Mind cohort takes tens of minutes to a few hours. The tool returns as soon as the Audience exists (structuredContent.audience.memberTraining reports what was queued); wait until every member reports readyToChat (get_mind_status or GET /api/v1/minds/{id}/training) before running a Study, which refuses Audiences with untrained members.",
      -  "type": "boolean"
      -}
  15. Changed1 schema field changed
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "$schema": "http://json-schema.org/draft-07/schema#",
      +  "additionalProperties": {},
      +  "properties": {
      +    "audience": {
      +      "description": "The created or previewed Audience with its Minds and grounding."
      +    },
      +    "operation": {
      +      "description": "Durable creation operation, while creation is still running."
      +    },
      +    "status": {
      +      "description": "Creation state of the Audience."
      +    },
      +    "workspaceUrl": {
      +      "anyOf": [
      +        {
      +          "type": "string"
      +        },
      +        {
      +          "type": "null"
      +        }
      +      ],
      +      "description": "Minds workspace link for the Audience."
      +    }
      +  },
      +  "type": "object"
      +}
  16. Changed1 schema field changed
    • changedInput schema / properties / trainMembers / description
      Previous value: -"Opt-in per-Mind training for large reviewed-dataset cohorts (default false). By default a reviewed-dataset Audience of more than ~40 Minds is bulk-created immediately ready: exact demographics, but no per-Mind research training (empty system prompt, no knowledge items). Set true to create those Minds untrained instead and enqueue each one through the same per-member training pipeline the in-app draft flow uses, preserving its deterministic cohort profile and the request locale. The tool still returns as soon as the Audience exists — training continues in the background (structuredContent.audience.memberTraining reports what was queued); poll each member with GET /api/v1/minds/{id}/training. Has no effect on Audiences whose members are already trained individually."New value: +"Deprecated; omit it. Every member of every Audience is trained individually in the background, including reviewed-dataset cohorts of more than ~40 Minds (each keeps its deterministic cohort profile and the request locale). true is accepted as a no-op; false is rejected, because it used to create untrained Minds with an empty system prompt that reported ready. Cost and time: one Mind training per member; a 100-Mind cohort takes tens of minutes to a few hours. The tool returns as soon as the Audience exists (structuredContent.audience.memberTraining reports what was queued); wait until every member reports readyToChat (get_mind_status or GET /api/v1/minds/{id}/training) before running a Study, which refuses Audiences with untrained members."
  17. Changed8 schema fields changed
    • changedInput schema / properties / brief / maxLength
      Previous value: -4000New value: +200000
    • changedInput schema / properties / brief / minLength
      Previous value: -3New value: +1
    • changedInput schema / properties / excludeDistributions / description
      Previous value: -"Exact axis names (copied from a preview) that must not be used as cohort quotas. Applied deterministically after grounding; the evidence stays visible in reviewDistributions."New value: +"Exact axis names whose composition quotas should be removed. Age remains as one eligibility range without within-range shares; explicit gender membership remains enforced. Include required eligibility axes in cohortAllocation.distributionNames. Original evidence stays in reviewDistributions."
    • changedInput schema / properties / files / description
      Previous value: -"Optional already-uploaded research files. MCP cannot read or upload a local file:// path. Use a fetchable HTTP(S) URL, a signed URL supplied by the client for the attached file, or an existing Minds workspace upload URL/path. Study tools import external file URLs into durable Minds storage before saving or running. The Study refuses to start if Minds cannot read the asset. The server analyzes these through the same extended screener/questionnaire path as the in-app New Audience uploader, including study roles, screening and quota rules, review distributions, and grounding provenance."New value: +"Optional already-uploaded research files. MCP cannot read or upload a local file:// path. Use a fetchable HTTP(S) URL, a signed URL supplied by the client for the attached file, or an existing Minds workspace upload URL/path. Study tools import external file URLs into durable Minds storage before saving or running. A workspace upload reused as a Study asset must sit under chat/<userId>/: request the signed upload with folder \"chat\" and pass that storage path or its /api/uploads/chat/ URL. A temp/, portfolio/, or context/ path — and any /api/uploads/file-access/ URL — is refused as not belonging to the workspace owner and is never re-fetched; pass a plain external URL instead. The Study refuses to start if Minds cannot read the asset. The server analyzes these through the same extended screener/questionnaire path as the in-app New Audience uploader, including study roles, screening and quota rules, review distributions, and grounding provenance."
    • changedInput schema / properties / files / items / properties / url / description
      Previous value: -"URL of an already-uploaded file. MCP cannot read or upload a local file:// path. Use a fetchable HTTP(S) URL, a signed URL supplied by the client for the attached file, or an existing Minds workspace upload URL/path. Study tools import external file URLs into durable Minds storage before saving or running. The Study refuses to start if Minds cannot read the asset."New value: +"URL of an already-uploaded file. MCP cannot read or upload a local file:// path. Use a fetchable HTTP(S) URL, a signed URL supplied by the client for the attached file, or an existing Minds workspace upload URL/path. Study tools import external file URLs into durable Minds storage before saving or running. A workspace upload reused as a Study asset must sit under chat/<userId>/: request the signed upload with folder \"chat\" and pass that storage path or its /api/uploads/chat/ URL. A temp/, portfolio/, or context/ path — and any /api/uploads/file-access/ URL — is refused as not belonging to the workspace owner and is never re-fetched; pass a plain external URL instead. The Study refuses to start if Minds cannot read the asset."
    • changedInput schema / properties / groundingPreview / description
      Previous value: -"Review the quota axes BEFORE any Mind exists. When true, the server runs research grounding and deterministic cohort allocation without creating an Audience or Minds or consuming a generation allowance. To revise a saved preview without repeating research, pass its unchanged reviewedGroundingJson/SHA pair together with groundingPreview and the revised exclusion/allocation options. The response includes effective target percentages and integer counts; explicit allocation targets that do not match grounded axes fail closed. Present the plan to the user, then call again without groundingPreview and pass reviewedGroundingJson plus reviewedGroundingSha256 unchanged with the same allocation options."New value: +"Review the quota axes BEFORE any Mind exists. When true, the server runs research grounding and deterministic cohort allocation without creating an Audience or Minds or consuming a generation allowance. To revise a saved preview without repeating research, pass its unchanged reviewedGroundingJson/SHA pair together with groundingPreview and the revised exclusion/allocation options. Fresh research uses the same durable operation as the public REST API; this tool polls it to completion. The response includes effective target percentages and integer counts; explicit allocation targets that do not match grounded axes fail closed. Present the plan to the user, then call again without groundingPreview and pass reviewedGroundingJson plus reviewedGroundingSha256 unchanged with the same allocation options."
    • changedInput schema / properties / text / maxLength
      Previous value: -4000New value: +200000
    • changedInput schema / properties / text / minLength
      Previous value: -3New value: +1
  18. Changed7 schema fields changed
    • changedInput schema / properties / cohortAllocation / properties / distributionNames / maxItems
      Previous value: -200New value: +500
    • changedInput schema / properties / cohortAllocation / properties / maxDistributions / maximum
      Previous value: -200New value: +500
    • changedInput schema / properties / cohortAllocation / properties / targetOverrides / items / properties / segments / maxItems
      Previous value: -50New value: +200
    • changedInput schema / properties / cohortAllocation / properties / targetOverrides / maxItems
      Previous value: -200New value: +500
    • changedInput schema / properties / files / maxItems
      Previous value: -10New value: +20
    • changedInput schema / properties / reviewedGroundingJson / description
      Previous value: -"Exact reviewedGroundingJson returned by a prior groundingPreview. Pass it unchanged together with reviewedGroundingSha256 on a re-preview or creation call; the server reuses this reviewed snapshot instead of rerunning grounding research."New value: +"Exact reviewedGroundingJson returned by groundingPreview or import_audience_sources. Pass it unchanged together with reviewedGroundingSha256 on a re-preview or creation call; the server reuses this reviewed snapshot instead of rerunning grounding research."
    • changedInput schema / properties / reviewedGroundingJson / maxLength
      Previous value: -250000New value: +2000000
  19. Changed2 schema fields changed
    • changedInput schema / properties / groundingPreview / description
      Previous value: -"Review the quota axes BEFORE any Mind exists. When true, the server runs research grounding and deterministic cohort allocation without creating an Audience or Minds or consuming a generation allowance. The response includes effective target percentages and integer counts; explicit allocation targets that do not match grounded axes fail closed. Present the plan to the user, then call again without groundingPreview and pass reviewedGroundingJson plus reviewedGroundingSha256 unchanged with the same allocation options."New value: +"Review the quota axes BEFORE any Mind exists. When true, the server runs research grounding and deterministic cohort allocation without creating an Audience or Minds or consuming a generation allowance. To revise a saved preview without repeating research, pass its unchanged reviewedGroundingJson/SHA pair together with groundingPreview and the revised exclusion/allocation options. The response includes effective target percentages and integer counts; explicit allocation targets that do not match grounded axes fail closed. Present the plan to the user, then call again without groundingPreview and pass reviewedGroundingJson plus reviewedGroundingSha256 unchanged with the same allocation options."
    • changedInput schema / properties / reviewedGroundingJson / description
      Previous value: -"Exact reviewedGroundingJson returned by a prior groundingPreview. Pass it unchanged together with reviewedGroundingSha256 on the creation call; the server reuses this reviewed snapshot instead of rerunning grounding research."New value: +"Exact reviewedGroundingJson returned by a prior groundingPreview. Pass it unchanged together with reviewedGroundingSha256 on a re-preview or creation call; the server reuses this reviewed snapshot instead of rerunning grounding research."
  20. Changed2 schema fields changed
    • changedInput schema / properties / groundingPreview / description
      Previous value: -"Review the quota axes BEFORE any Mind exists. When true, the server runs research grounding and returns the axes it would allocate on — with Study-outcome axes demoted and listed in flaggedDistributions — without creating an Audience or Minds and without consuming a generation allowance. Present the axes to the user for approval, then call again without groundingPreview and pass reviewedGroundingJson plus reviewedGroundingSha256 unchanged so creation uses the reviewed snapshot instead of rerunning research."New value: +"Review the quota axes BEFORE any Mind exists. When true, the server runs research grounding and deterministic cohort allocation without creating an Audience or Minds or consuming a generation allowance. The response includes effective target percentages and integer counts; explicit allocation targets that do not match grounded axes fail closed. Present the plan to the user, then call again without groundingPreview and pass reviewedGroundingJson plus reviewedGroundingSha256 unchanged with the same allocation options."
    • addedInput schema / properties / operationId
      Added value: +{
      +  "description": "Resume a queued preview or creation by its returned jobId. Reads its v1 operation status without creating or charging anything. Supply this alone; do not repeat the creation brief to check progress.",
      +  "format": "uuid",
      +  "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      +  "type": "string"
      +}
  21. Changed3 schema fields changed
    • changedInput schema / properties / groundingPreview / description
      Previous value: -"Review the quota axes BEFORE any Mind exists. When true, the server runs research grounding and returns the axes it would allocate on — with Study-outcome axes demoted and listed in flaggedDistributions — without creating an Audience or Minds and without consuming a generation allowance. Present the axes to the user for approval, then call again without groundingPreview (same brief and options) to create, passing any axis names to drop as excludeDistributions."New value: +"Review the quota axes BEFORE any Mind exists. When true, the server runs research grounding and returns the axes it would allocate on — with Study-outcome axes demoted and listed in flaggedDistributions — without creating an Audience or Minds and without consuming a generation allowance. Present the axes to the user for approval, then call again without groundingPreview and pass reviewedGroundingJson plus reviewedGroundingSha256 unchanged so creation uses the reviewed snapshot instead of rerunning research."
    • addedInput schema / properties / reviewedGroundingJson
      Added value: +{
      +  "description": "Exact reviewedGroundingJson returned by a prior groundingPreview. Pass it unchanged together with reviewedGroundingSha256 on the creation call; the server reuses this reviewed snapshot instead of rerunning grounding research.",
      +  "maxLength": 250000,
      +  "minLength": 1,
      +  "type": "string"
      +}
    • addedInput schema / properties / reviewedGroundingSha256
      Added value: +{
      +  "description": "SHA-256 returned by the same groundingPreview. Required together with reviewedGroundingJson; any mismatch is rejected before Audience or Mind materialisation.",
      +  "pattern": "^[0-9a-f]{64}$",
      +  "type": "string"
      +}
  22. Changed2 schema fields changed
    • addedInput schema / properties / excludeDistributions
      Added value: +{
      +  "description": "Exact axis names (copied from a preview) that must not be used as cohort quotas. Applied deterministically after grounding; the evidence stays visible in reviewDistributions.",
      +  "items": {
      +    "maxLength": 200,
      +    "minLength": 1,
      +    "type": "string"
      +  },
      +  "maxItems": 200,
      +  "type": "array"
      +}
    • addedInput schema / properties / groundingPreview
      Added value: +{
      +  "description": "Review the quota axes BEFORE any Mind exists. When true, the server runs research grounding and returns the axes it would allocate on — with Study-outcome axes demoted and listed in flaggedDistributions — without creating an Audience or Minds and without consuming a generation allowance. Present the axes to the user for approval, then call again without groundingPreview (same brief and options) to create, passing any axis names to drop as excludeDistributions.",
      +  "type": "boolean"
      +}
  23. Changed4 schema fields changed
    • changedInput schema / properties / audienceCreationMode / description
      Previous value: -"Audience creation mode. Preferred. Use balanced for everyday research, segment_coverage for coverage of limiting grounded cells, or benchmark_depth for validation-ready repeated representation."New value: +"How the Audience is sized. \"balanced\" (default): compact and representative for everyday research. It is the only mode with a hard wall on a size you state — a memberCount above 20 is refused with 403 MODE_CAP. \"segment_coverage\": two representatives per limiting grounded cell, from a 10-Mind floor; automatic sizing stops at 50, but a memberCount you state is bounded only by your plan. \"benchmark_depth\": repeated representation of limiting grounded cells for validation-ready segmentation; bounded by your plan allowance. The deeper two require a Team (enterprise) plan — on other plans the server SILENTLY downgrades to \"balanced\" and echoes the effective mode in structuredContent.audience.audienceCreationMode. Call get_audience_limits to see the ceilings that apply to your account."
    • changedInput schema / properties / groupCreationMode / description
      Previous value: -"Audience creation mode. \"balanced\" (default): compact, representative Audience for everyday research. \"segment_coverage\": two representatives per limiting grounded audience cell, with a 10-Mind evidence floor and 50-Mind mode ceiling. \"benchmark_depth\": repeated representation of limiting grounded audience cells for validation-ready benchmark / survey-style segmentation, with the paid allowance as its ceiling. The deeper modes require a Team (enterprise) plan — on other plans the server SILENTLY downgrades to \"balanced\" and echoes the effective mode in the response (structuredContent.audience.audienceCreationMode). This field is the legacy alias for audienceCreationMode."New value: +"Legacy alias for audienceCreationMode — same values, same behaviour. How the Audience is sized. \"balanced\" (default): compact and representative for everyday research. It is the only mode with a hard wall on a size you state — a memberCount above 20 is refused with 403 MODE_CAP. \"segment_coverage\": two representatives per limiting grounded cell, from a 10-Mind floor; automatic sizing stops at 50, but a memberCount you state is bounded only by your plan. \"benchmark_depth\": repeated representation of limiting grounded cells for validation-ready segmentation; bounded by your plan allowance. The deeper two require a Team (enterprise) plan — on other plans the server SILENTLY downgrades to \"balanced\" and echoes the effective mode in structuredContent.audience.audienceCreationMode. Call get_audience_limits to see the ceilings that apply to your account."
    • changedInput schema / properties / memberCount / description
      Previous value: -"Exact number of Minds to create in the Audience. Pass this whenever the user states a size (\"exactly 50 per region\", \"genau 50 Minds je Zelle\") instead of relying on the server to parse the number out of the brief prose. When omitted, the size is inferred from the brief and, failing that, from the creation mode's evidence-based automatic sizing. Rejected with 403 PLAN_LIMIT when it exceeds the plan's per-Audience cap; the Audience is never created at a partial size."New value: +"Exact number of Minds to create. Pass this whenever the user states a size (\"exactly 50 per region\", \"genau 50 Minds je Zelle\") instead of relying on the server to parse the number out of the brief. When omitted, the size is inferred from the brief and, failing that, from the creation mode's evidence-based automatic sizing. Two separate refusals apply: 403 MODE_CAP above 20 in \"balanced\" mode (switch to segment_coverage or benchmark_depth), and 403 PLAN_LIMIT above your plan's per-Audience cap. The 6000 accepted here is the absolute system ceiling, not your allowance — call get_audience_limits for the real one. The Audience is never created at a partial size."
    • changedInput schema / properties / memberCount / maximum
      Previous value: -9007199254740991New value: +6000
  24. Changed2 schema fields changed
    • changedInput schema / properties / files / description
      Previous value: -"Optional already-uploaded research files. MCP cannot read or upload a local file:// path. Use a fetchable HTTP(S) URL, a signed URL supplied by the client for the attached file, or an existing Minds workspace upload URL/path. The Study refuses to start if Minds cannot read the asset. The server analyzes these through the same extended screener/questionnaire path as the in-app New Audience uploader, including study roles, screening and quota rules, review distributions, and grounding provenance."New value: +"Optional already-uploaded research files. MCP cannot read or upload a local file:// path. Use a fetchable HTTP(S) URL, a signed URL supplied by the client for the attached file, or an existing Minds workspace upload URL/path. Study tools import external file URLs into durable Minds storage before saving or running. The Study refuses to start if Minds cannot read the asset. The server analyzes these through the same extended screener/questionnaire path as the in-app New Audience uploader, including study roles, screening and quota rules, review distributions, and grounding provenance."
    • changedInput schema / properties / files / items / properties / url / description
      Previous value: -"URL of an already-uploaded file. MCP cannot read or upload a local file:// path. Use a fetchable HTTP(S) URL, a signed URL supplied by the client for the attached file, or an existing Minds workspace upload URL/path. The Study refuses to start if Minds cannot read the asset."New value: +"URL of an already-uploaded file. MCP cannot read or upload a local file:// path. Use a fetchable HTTP(S) URL, a signed URL supplied by the client for the attached file, or an existing Minds workspace upload URL/path. Study tools import external file URLs into durable Minds storage before saving or running. The Study refuses to start if Minds cannot read the asset."
  25. Changed1 schema field changed
    • addedInput schema / properties / trainMembers
      Added value: +{
      +  "description": "Opt-in per-Mind training for large reviewed-dataset cohorts (default false). By default a reviewed-dataset Audience of more than ~40 Minds is bulk-created immediately ready: exact demographics, but no per-Mind research training (empty system prompt, no knowledge items). Set true to create those Minds untrained instead and enqueue each one through the same per-member training pipeline the in-app draft flow uses, preserving its deterministic cohort profile and the request locale. The tool still returns as soon as the Audience exists — training continues in the background (structuredContent.audience.memberTraining reports what was queued); poll each member with GET /api/v1/minds/{id}/training. Has no effect on Audiences whose members are already trained individually.",
      +  "type": "boolean"
      +}
  26. Added

TDQS

A4.5/5.0
Behavior5/5

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

Beyond the annotations (which already declare non-read-only, open-world, idempotent, non-destructive), the description discloses that creation is asynchronous and returns an operation ID, that confirmation requires the user-accepted draft/snapshot plus its checksum, and that Audiences are private unless link sharing is enabled. These are material behavioral facts an agent needs before calling.

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?

Five sentences, front-loaded with purpose and scope, and each sentence carries distinct information (workflow, isolation rule, recalibration rule, dataset support, async, privacy). Sentences are long and dense but not redundant.

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?

For a 9-parameter nested-object tool with an output schema present, the description supplies the essential mental model (research → draft → review → confirm → async Audience), so return-value detail is correctly left to the output schema. It omits mention of some options (conversationFiles, memberCount tuning), but those are thoroughly documented in the schema.

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 description coverage is 100%, so the baseline is 3, but the description adds workflow-level meaning the schema does not: the draft-then-confirm sequence, the fact that confirmation needs the accepted draft/snapshot and checksum, and that rework revises rather than recreates. This clarifies how the parameters interact rather than merely restating them.

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 + resource ('Researches a free-text population brief and builds a new Audience of Minds') and frames the scope crisply. It distinguishes itself from the recalibration path by asserting that an existing Audience is changed in place by id and 'never rebuilt from a new brief', so the agent can tell this apart from recalibrate_audience without opening schemas.

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?

Gives clear context for the new-brief workflow, the draft/rework/review sequence, and an explicit when-not (existing Audience → recalibrate by id). It stops short of naming sibling tools like recalibrate_audience or import_audience_sources for text resources, leaving some routing to inference.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.