manage_audience

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

The description adds valuable behavior context: it explains gating ('list is not gated', 'confirm is TG_ADS_WRITE_GATE') and gives an explicit no-retry hint on access denial. However, it contradicts the annotation destructiveHint=false by exposing a delete action described as 'delete/clone: two-step confirm_hash'. This is an annotation contradiction because the tool can clearly perform destructive operations while the annotation claims it is not destructive.

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

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

The description is compact and well-structured: it front-loads the action enum and uses line breaks to separate create, delete/clone, and list gating guidance. There is no obvious fluff, though some phrasing is cryptic rather than explanatory, which slightly reduces clarity.

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

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

The tool is a multi-action manager with seven parameters and no schema descriptions, so the description carries a heavy burden. It covers create, delete/clone, and auth gating, but omits essential details for rename (which parameters are needed), how confirm_hash is obtained, and what confirm actually does. An agent could not confidently invoke every action correctly from this description alone.

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

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

With 0% schema description coverage, the description must compensate, and it does clarify file_path (one user id per line), user_ids as an array, and confirm_hash as required for delete/clone. However, it leaves title, audience_id, and the exact interplay between confirm and confirm_hash underspecified, so an agent still lacks full parameter semantics for all actions.

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

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

The description anchors the tool to 'Custom audiences' and explicitly enumerates the supported actions: list, create, rename, delete, clone. This makes the resource and operation scope clear and distinguishes it from sibling tools about ads, funds, and accounts. It lacks a single overarching verb phrase like 'Manage custom audiences', but the action list communicates the purpose well.

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

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

The description gives operation-specific guidance: create requires file_path or user_ids, delete/clone need a two-step confirm_hash, and list is not gated. It also warns that access_denied should be skipped and not retried, which helps the agent decide when to stop. It does not name sibling tools or explicitly say when manage_audience should be preferred over alternatives, but the guidance within the tool's domain is clear.

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