Skip to main content
Glama
Sign In

Infinite Audience

by io.github.no-fait
OverviewDiscussionsAdmin

Refresh Audience

refresh_audience
Destructive

Refresh one named member segment of an audience against the current IAG, then refresh the audience's own version/expiry. An audience is a composition of one or more member segments, possibly of different subtypes — there is no "primary" segment, so segment_id is required (400 SEGMENT_ID_REQUIRED if omitted, 400 SEGMENT_NOT_A_MEMBER if it is not part of this audience). Behaviour is specific to the chosen segment's subtype:

  • filter: synchronous — returns status: active immediately. record_count is null; call recount_audience if a fresh count is needed before quoting.

  • matched: with hitl false/unset (default): returns status: pending + upload_url. Instruct the user to upload their identity list to upload_url (same or updated file). After upload, call wait_for_segment(segment_id) to block until identity resolution completes. With hitl: true: the upload is staged instead — follow the analyze_audience_upload -> confirm_column_mappings / cancel_matched_upload -> wait_for_segment sequence documented on create_segment(subtype=matched) (confirm_column_mappings/cancel_matched_upload take this segment_id, not audience_id).

  • similarity: returns status: pending + workflow_run_id. Call wait_for_workflow(workflow_run_id) to monitor progress. Do not attempt to deliver until status is active.

  • propensity: returns status: pending + workflow_run_id. Call wait_for_workflow(workflow_run_id) to monitor progress. Do not attempt to deliver until status is active. Returns 422 MISSING_POSITIVE_CLASS_ID for legacy propensity segments that predate field storage — archive the affected segment with archive_segment and create a replacement using create_segment. Always call get_audience first to see the member segments and their subtypes, so you can pick (or have the user pick) the right segment_id. Requires 'creator' scope.

Input Schema

NameRequiredDescriptionDefault
hitlNoIf true: pauses similarity/propensity workflows at human-in-the-loop gates; stages a matched segment's re-upload instead of resolving automatically. Defaults to false.
segment_idYesWhich member segment of this audience to refresh. Required — there is no default/primary segment.
audience_idYesThe audience ID to refresh
compressionNoMatched subtype: replacement upload compression.none
shard_countNoMatched subtype: number of same-format shards. Every CSV shard must include its own header row.

Output Schema

NameRequiredDescriptionDefault
statusYes
subtypeYes
versionYes
guidanceNoInterpretation or recovery guidance for this result
next_stepYes
refreshedYes
count_unitNo
page_countNoNumber of objects on this page, not the organization total
segment_idYes
upload_urlNo
audience_idYes
count_stateNoUnknown means no count; available does not guarantee freshness. Recount for a current value.
upload_urlsNo
next_actionsNoSuggested next calls using returned IDs and available scopes. Not executed and not user consent.
money_displayNoCurrency amounts formatted once from source paths ending in _cents. Use verbatim; do not divide again. Null/missing source amounts are omitted, not zero.
workflow_run_idNo
population_inputNoPopulation input used for the preview; IDs refer to their current saved definitions

Schema Changelog

Changes observed during successful MCP inspections.

  1. Added
  2. Removed
  3. First observed

TDQS

A4.5/5.0
Behavior5/5

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

Annotations declare destructive/non-idempotent/openWorld, and the description goes well past them: synchronous vs pending return states per subtype, the upload_url and workflow_run_id handoffs, the hitl staging variant, the 400 SEGMENT_ID_REQUIRED / SEGMENT_NOT_A_MEMBER / 422 MISSING_POSITIVE_CLASS_ID failure modes, and the 'creator' scope requirement. This is unusually rich behavioral disclosure.

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?

Long but front-loaded and well structured with a subtype-keyed bullet list, so scanning is easy. The similarity and propensity bullets are near-verbatim duplicates and could be merged, which is the only real waste.

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, multi-subtype orchestration tool, the description covers prerequisites, per-path branching, downstream tool chains, and error recovery. An output schema exists, so return-value detail is correctly omitted.

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 schema alone justifies a 3. The description still adds semantic value: it explains why segment_id has no default (audiences may contain multiple subtypes, no 'primary'), and it clarifies that hitl stages a matched re-upload rather than merely pausing workflows. compression and shard_count are left to the schema.

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

Purpose4/5

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

Opens with a specific verb and resource: refresh one named member segment against the current IAG, then refresh the audience's version/expiry. That is far more precise than the title. It does not, however, distinguish itself from the sibling refresh_segment, which an agent could plausibly confuse it with given the near-identical name.

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 sequencing: call get_audience first to pick the right segment_id, then branch by subtype. It names the exact follow-up tools (wait_for_segment, wait_for_workflow, analyze_audience_upload, confirm_column_mappings) per case, states when delivery must not be attempted, and gives the remedy for legacy propensity segments. Nothing is left to inference.

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

All Infinite Audience toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources