Skip to main content
Glama

Minds: Synthetic Market Research

Change an Existing Audience

recalibrate_audience
Destructive

Changes an existing Audience in place: it keeps its id, its Minds keep theirs (except copies below), and no Mind is deleted. Covers composition and trait edits, a population pivot, adding members, an exact chart selection (distributions), new sources and going deeper (deepen), and re-runs its research grounding. Owner, or verified Minds staff with existing direct Audience admin collaboration or an active owner-issued support grant. Staff support is limited to composition amendments: no growth, new sources, Go deeper or shared-Mind waiver. Asynchronous: the result is an accepted operation with its id, not a completed change. Queues behind another edit of the Audience and waits for a Study run on its members. Members shared with other Audiences are replaced here by copies with new ids. Reusing requestKey with identical input retries safely.

Input Schema

NameRequiredDescriptionDefault
deepenNoGo deeper, in the background: research what the Audience still lacks — every standard dimension its evidence reports missing or assumed, plus `topics` — and add it; every chart the Audience has stays, and stronger evidence replaces weaker only for the same question or dimension. Go deeper runs in the background and this tool returns at once; get_audience_creation_progress with the audienceId follows research.phase (researching, then researched). Not combinable with distributions, query or requestedDistribution. Asked while the Audience's background research is still running, it is queued behind that research and starts when it finishes.
audienceNoWhich existing Audience to change. Give the id when known, otherwise the name.
researchNoWhat to change and the evidence for it. Omit it (and distributions/deepen) to re-run the research from the original brief.
requestKeyNoStable retry key. Reuse with identical input to recover the same recalibration operation, including its completed result.
distributionsNoOptional exact active distribution selection from the grounding review. Supplying this uses selection mode and applies the user-authored composition directly, including exact shares: to set a chart to e.g. 70% Female / 30% Male, send the complete active set with that chart's `pct` values changed. They become the user's targets beside the evidence (shown as "Set by you"); no research runs and the members are re-allocated to them. Send each chart's stored `name`, `label` and `sourceIdx` from the Audience's stored grounding (structuredContent audience.grounding.distributions); the Audience's saved evidence is reattached to every chart and value it already has (names shown in the text output may be translated; use the stored ones). A chart or value it does not have yet (send `sourceIdx: -1`) is added as the user's target.
allowSharedMindsNoRecalibration rewrites member profiles and retrains knowledge on the Mind itself. Members that also belong to other Audiences are copied into this Audience first, so the other Audiences stay unchanged. Set this only when the user explicitly wants those members rewritten in place, in every Audience they belong to.
conversationFilesNoNew first-party research files added to sources.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.

Output Schema

NameRequiredDescriptionDefault
researchNoGo deeper research receipt, when deepen was supplied.
operationNoDurable recalibration receipt: id, requestKey, status, progress, statusUrl, retained result or terminal error.
audienceIdNoAudience being changed in place.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changed
    • removedInput schema / properties / distributions / items / properties / distribution / items / properties / canonical / maxLength
      Removed value: -4096
    • removedInput schema / properties / distributions / items / properties / distribution / items / properties / label / maxLength
      Removed value: -4096
    • removedInput schema / properties / distributions / items / properties / name / maxLength
      Removed value: -4096
  2. Changed2 schema fields changed
    • addedInput schema / properties / audience / properties / id / format
      Added value: +"uuid"
    • addedInput schema / properties / audience / properties / id / pattern
      Added value: +"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"
  3. Changed1 schema field changed
    • changedInput schema / properties / research / properties / requestedDistribution / description
      Previous value: -"Exact topic that must materialize as a new distribution, alongside instruction, when the user explicitly asks to add one. Without research evidence it is added as an assumption and flagged as such."New value: +"Exact topic that must materialize as a new distribution, alongside instruction, when the user explicitly asks to add one. Without research evidence it is added as an assumption and flagged as such. Other charts and targets stay; an existing one that states the same personal fact (for example personal and household income whose brackets cannot be compared) stays as a chart, and the requested one is allocated in its place."
  4. Changed2 schema fields changed
    • changedInput schema / properties / distributions / description
      Previous value: -"Optional exact active distribution selection from the grounding review. Supplying this uses selection mode and applies the user-authored composition directly, including exact shares: to set a chart to e.g. 70% Female / 30% Male, send the complete active set with that chart's `pct` values changed. They become the user's targets beside the evidence (shown as \"Set by you\"); no research runs and the members are re-allocated to them."New value: +"Optional exact active distribution selection from the grounding review. Supplying this uses selection mode and applies the user-authored composition directly, including exact shares: to set a chart to e.g. 70% Female / 30% Male, send the complete active set with that chart's `pct` values changed. They become the user's targets beside the evidence (shown as \"Set by you\"); no research runs and the members are re-allocated to them. Send each chart's stored `name`, `label` and `sourceIdx` from the Audience's stored grounding (structuredContent audience.grounding.distributions); the Audience's saved evidence is reattached to every chart and value it already has (names shown in the text output may be translated; use the stored ones). A chart or value it does not have yet (send `sourceIdx: -1`) is added as the user's target."
    • changedInput schema / properties / research / properties / instruction / description
      Previous value: -"The change the user wants, folded into the replayed original brief. Its reach decides how members change: a composition edit (\"make men 40%\", \"add an income distribution\") re-allocates only members whose segment changed; a trait change (\"now they are all vegan\", \"SMB owners instead of enterprise buyers\") evolves members in place (same name and portrait, rewritten profile, knowledge retrained); a population pivot (\"now Gen-Z students instead of retirees\") rebuilds every member in place with a new persona, portrait and knowledge; an additive instruction (\"and now add 10 African consumers\") adds new members within the plan limits and leaves the others untouched; a stated total for the same people (\"make it 10\", \"reduce to 10 people\") keeps the members who best hold the Audience's composition (and any member named or said to keep, \"keep the CEO\") and removes the rest from this Audience only (their Minds stay in the library, nobody is retrained), and asking for a copy or version (\"a 10-person version\") leaves this Audience as it is and makes a copy holding those members (the completed result's `resize` names who was kept and left out); anything else in the same instruction (\"make it 10 and add an income chart\") is applied right after the resize. Mind ids never change and no Mind is deleted. Use this, not query, to adjust the Audience."New value: +"The change the user wants, folded into the replayed original brief. Its reach decides how members change: a composition edit (\"make men 40%\", \"add an income distribution\") re-allocates only members whose segment changed; a trait change (\"now they are all vegan\", \"SMB owners instead of enterprise buyers\") evolves members in place (same name and portrait, rewritten profile, knowledge retrained); a population pivot (\"now Gen-Z students instead of retirees\") rebuilds every member in place with a new persona, portrait and knowledge; an additive instruction (\"and now add 10 African consumers\") adds new members within the plan limits and leaves the others untouched; a stated total for the same people (\"make it 10\", \"reduce to 10 people\") keeps the members who best hold the Audience's composition (and any member named or said to keep, \"keep Anna\", \"keep the CEO\"; a member named to remove, \"drop Anna\", always leaves; a name several members carry decides nothing and the result's notes say so) and removes the rest from this Audience only (their Minds stay in the library, nobody is retrained), and asking for a copy or version (\"a 10-person version\") leaves this Audience as it is and makes a copy holding those members (the completed result's `resize` names who was kept and left out); anything else in the same instruction (\"make it 10 and add an income chart\", \"20 more, and make women 60%\") is applied right after, once, while wording that only preserves (\"do not change their facts\") starts nothing. The parts are read by a model in any language and checked against the instruction's own words; an instruction that cannot be read in full changes nothing and is retried automatically (`AUDIENCE_EDIT_UNREAD` while queued). Mind ids never change and no Mind is deleted. Use this, not query, to adjust the Audience."
  5. Changed6 schema fields changed
    • changedInput schema / properties / allowSharedMinds / description
      Previous value: -"Recalibration rewrites member profiles and retrains knowledge on the Mind itself, so members that also belong to other Audiences change there too. The API refuses with 409 AUDIENCE_MINDS_SHARED (listing the Minds and the other Audiences) unless this is true. Set it only after the user explicitly accepts that reach."New value: +"Recalibration rewrites member profiles and retrains knowledge on the Mind itself. Members that also belong to other Audiences are copied into this Audience first, so the other Audiences stay unchanged. Set this only when the user explicitly wants those members rewritten in place, in every Audience they belong to."
    • changedInput schema / properties / deepen / description
      Previous value: -"Go deeper, in the background: research what the Audience still lacks — every standard dimension its evidence reports missing or assumed, plus `topics` — and add it; every chart the Audience has stays, and stronger evidence replaces weaker only for the same question or dimension. Go deeper runs in the background and this tool returns at once; get_audience_creation_progress with the audienceId follows research.phase (researching, then researched). Not combinable with distributions, query or requestedDistribution. Refused with 409 AUDIENCE_RESEARCH_RUNNING while the Audience's background research is still running (it goes deeper on its own and updates the Audience when done)."New value: +"Go deeper, in the background: research what the Audience still lacks — every standard dimension its evidence reports missing or assumed, plus `topics` — and add it; every chart the Audience has stays, and stronger evidence replaces weaker only for the same question or dimension. Go deeper runs in the background and this tool returns at once; get_audience_creation_progress with the audienceId follows research.phase (researching, then researched). Not combinable with distributions, query or requestedDistribution. Asked while the Audience's background research is still running, it is queued behind that research and starts when it finishes."
    • changedInput schema / properties / distributions / items / properties / distribution / items / properties / canonical / maxLength
      Previous value: -200New value: +4096
    • changedInput schema / properties / distributions / items / properties / distribution / items / properties / label / maxLength
      Previous value: -200New value: +4096
    • changedInput schema / properties / distributions / items / properties / name / maxLength
      Previous value: -200New value: +4096
    • changedInput schema / properties / research / properties / instruction / description
      Previous value: -"The change the user wants, folded into the replayed original brief. Its reach decides how members change: a composition edit (\"make men 40%\", \"add an income distribution\") re-allocates only members whose segment changed; a trait change (\"now they are all vegan\", \"SMB owners instead of enterprise buyers\") evolves members in place (same name and portrait, rewritten profile, knowledge retrained); a population pivot (\"now Gen-Z students instead of retirees\") rebuilds every member in place with a new persona, portrait and knowledge; an additive instruction (\"and now add 10 African consumers\") adds new members within the plan limits and leaves the others untouched. Mind ids never change and no Mind is deleted. Use this, not query, to adjust the Audience."New value: +"The change the user wants, folded into the replayed original brief. Its reach decides how members change: a composition edit (\"make men 40%\", \"add an income distribution\") re-allocates only members whose segment changed; a trait change (\"now they are all vegan\", \"SMB owners instead of enterprise buyers\") evolves members in place (same name and portrait, rewritten profile, knowledge retrained); a population pivot (\"now Gen-Z students instead of retirees\") rebuilds every member in place with a new persona, portrait and knowledge; an additive instruction (\"and now add 10 African consumers\") adds new members within the plan limits and leaves the others untouched; a stated total for the same people (\"make it 10\", \"reduce to 10 people\") keeps the members who best hold the Audience's composition (and any member named or said to keep, \"keep the CEO\") and removes the rest from this Audience only (their Minds stay in the library, nobody is retrained), and asking for a copy or version (\"a 10-person version\") leaves this Audience as it is and makes a copy holding those members (the completed result's `resize` names who was kept and left out); anything else in the same instruction (\"make it 10 and add an income chart\") is applied right after the resize. Mind ids never change and no Mind is deleted. Use this, not query, to adjust the Audience."
  6. Changed1 schema field changed
    • changedInput schema / properties / distributions / description
      Previous value: -"Optional exact active distribution selection from the grounding review. Supplying this uses selection mode and applies the user-authored composition directly."New value: +"Optional exact active distribution selection from the grounding review. Supplying this uses selection mode and applies the user-authored composition directly, including exact shares: to set a chart to e.g. 70% Female / 30% Male, send the complete active set with that chart's `pct` values changed. They become the user's targets beside the evidence (shown as \"Set by you\"); no research runs and the members are re-allocated to them."
  7. Added

TDQS

A4.8/5.0
Behavior5/5

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

Annotations already flag destructiveHint and openWorldHint, and the description goes well beyond them: asynchronous semantics ('the result is an accepted operation with its id, not a completed change'), queueing behind another edit and behind a running Study, shared-Mind copy-on-write behavior with the `allowSharedMinds` override, and requestKey-based safe retry. It also names the failure mode and its retry path (`AUDIENCE_EDIT_UNREAD`). The requestKey retry note is not a contradiction of idempotentHint=false, since it only holds for identical input under the same key.

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 and every sentence carries operational weight: identity preservation, mode coverage, permissions, async contract, side effects, retry. It is dense and partly duplicated by equally rich schema descriptions (deepen/distributions behavior appears in both), and the long parentheticals slow scanning, but there is no filler.

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

Completeness5/5

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

For a destructive, async, open-world mutation with an output schema, the description supplies exactly what the structured fields cannot: what happens to members and Minds, what is copied versus mutated, how progress is followed (get_audience_creation_progress), and who may call it. Nothing an agent needs before invoking 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; the description still earns above that by tying each mode to the parameter that triggers it (`distributions` for exact chart selection, `deepen` for going deeper) and by flagging the case where `requestedDistribution` is allocated in place of an existing chart with incomparable brackets. It does not restate the heaviest semantics — the `instruction` reach taxonomy — because the schema already carries it.

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

Purpose5/5

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

The opening sentence gives a specific verb and resource plus the key invariant: 'Changes an existing Audience in place: it keeps its id, its Minds keep theirs ... and no Mind is deleted.' It then enumerates the covered change modes (composition/trait edit, population pivot, additive members, exact `distributions` selection, `deepen`, research re-grounding), which lets an agent separate this from create_audience_from_brief, duplicate_audience, and import_audience_sources without opening a schema.

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?

It states explicitly when to use it versus an alternative ('Use this, not query, to adjust the Audience'), records the mode exclusions ('Not combinable with distributions, query or requestedDistribution' on `deepen`), and spells out the authorization gate plus staff exclusions ('Staff support is limited to composition amendments: no growth, new sources, Go deeper or shared-Mind waiver').

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.