Skip to main content
Glama

Minds: Synthetic Market Research

Create a Grounded Audience from a Brief

create_audience_from_brief
Idempotent

Creates an Audience from a free-text brief. The server researches the population, derives its defensible dimensions, and builds Minds with an explicit profile each and exact segment allocation.

New briefs default to the webapp draft workflow: streamed research, distributions, then proposed Minds for review. Rework with draft.preview=true, draft.id, draft.sha256 and a separate draft.rework instruction. Create the exact approved roster with draft.preview=false and its id/checksum only after user acceptance. grounding.preview=false remains available for explicitly requested direct creation. grounding.preview returns the quota axes for review before any Mind exists; passing the reviewed grounding back with its checksum creates the Audience from exactly what was reviewed. composition.memberCount states a size, and the mode ceilings that bound it come from the Audience-limits operation.

Creation is asynchronous: the result carries the operation to poll while it runs. 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 real Minds before Create; id and sha256 identify the exact reviewed roster. Rework revises that draft.
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.
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); 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.

Schema Changelog

Changes observed during successful MCP inspections.

  1. 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."
      +}
  2. 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."
  3. 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."
  4. 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"
      -}
  5. 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"
      +}
  6. 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."
  7. 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
  8. 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
  9. 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."
  10. 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"
      +}
  11. 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"
      +}
  12. 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"
      +}
  13. 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
  14. 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."
  15. 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"
      +}
  16. Added

TDQS

A4.8/5.0
Behavior5/5

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

Annotations only declare readOnly=false, destructive=false, idempotent=true, openWorld=true. The description goes well beyond: creation is asynchronous and returns an operation to poll, previews consume no generation allowance and materialize no Minds, mismatched checksums fail closed before materialization, and the Audience is private unless link sharing is explicitly enabled. It also notes refusals (MODE_CAP, PLAN_LIMIT, no-evidence refusal) and the silent downgrade of deeper modes on non-enterprise plans.

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

Conciseness4/5

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

Front-loaded with purpose and mostly information-dense, with each clause carrying a distinct mode or constraint. It is long and overlaps noticeably with the already-verbose schema descriptions, so some of paragraph two is redundant rather than additive.

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

Completeness5/5

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

With an output schema present, return values need no explanation, and the description still covers the async lifecycle, how to resume via operationId, and the privacy default. For an 8-parameter tool with nested objects and multiple creation modes, nothing an agent needs to call it correctly is missing.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3, but the description adds cross-parameter composition semantics: the preview-then-commit sequence (pass reviewed snapshot back unchanged with its checksum), the trade-off between draft.preview and grounding.preview, and why composition.memberCount should be passed when a size is stated. This sequencing value is not derivable from any single parameter description.

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 and resource ('Creates an Audience from a free-text brief') plus the mechanism: the server researches the population, derives dimensions, and builds Minds with explicit profiles and exact segment allocation. It also differentiates from siblings by routing to the Audience-limits operation for ceilings and to import_audience_sources for file contents.

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

Usage Guidelines5/5

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

Explicit routing for every mode: new briefs default to the draft workflow, rework uses draft.preview=true with id/sha256, final creation uses draft.preview=false only after user acceptance, grounding.preview is called out as quota-only review, and direct creation via grounding.preview=false is flagged as the explicitly-requested exception. Alternatives (import_audience_sources, app upload for PDFs/images, get_audience_limits) are named with the conditions that select them.

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.