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

TableJSON 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

TableJSON 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. 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."
  2. 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."
  3. 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."
  4. 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."
  5. Added

TDQS

A4.4/5.0
Behavior5/5

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

Adds substantial context beyond the annotations: asynchronous accepted-operation semantics with an operation id, queuing behind another edit and waiting for a Study run, the permission model (owner vs. verified staff with collaboration or support grant), shared members being replaced by copies with new ids, and safe retry via requestKey. The retry-key wording is consistent with idempotentHint=false rather than contradicting it, and it explains what is and is not destroyed (no Mind deleted, ids preserved).

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?

Core purpose is front-loaded and every sentence carries operational weight (permissions, async behavior, shared-Mind copying, retry safety). It is, however, extremely dense and contains material that overlaps with the already-verbose schema descriptions, and the opening parenthetical "(except copies below)" is noise that points at content far downstream.

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, open-world, non-idempotent mutation tool this is comprehensive: it covers permission prerequisites, sequencing/queueing, the accepted-operation return shape, shared member copying, and idempotency recovery. With an output schema present, it correctly does not waste space explaining return payload fields.

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

Parameters3/5

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

Schema description coverage is 100% and the nested schema descriptions are themselves highly detailed (deepen, distributions, research, allowSharedMinds, conversationFiles all carry their own semantics), so the schema already does the heavy lifting. The description adds little parameter-level meaning beyond the schema, other than restating which fields make up the edge set; a baseline 3 is appropriate.

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

Purpose5/5

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

States a specific verb+resource ("Changes an existing Audience in place") and then enumerates the concrete change modes it covers: composition and trait edits, population pivot, adding members, exact chart selection, deepen, and research re-grounding. An agent can distinguish this from create_audience_from_brief or duplicate_audience without opening any schema, and it even clarifies that asking for a "version" here leaves this Audience untouched.

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

Usage Guidelines4/5

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

Gives an explicit routing rule ("Use this, not query, to adjust the Audience") plus a when-not in the permission clause (staff support is limited to composition amendments: no growth, new sources, Go deeper or shared-Mind waiver). The alternative it names, "query", is not an actual sibling tool name, which slightly weakens the routing compared with naming ask_audience or duplicate_audience directly.

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.