merge_custom_audiences

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

No annotations are provided, so the description carries the full behavioral burden. It discloses that source audiences are not modified ('Independent copy'), that an Idempotency-Key is required, and that the merge is performed across a bounded set of sources. It does not mention asynchronous behavior or return values, but the key non-destructive and idempotency traits are clearly stated.

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?

Three short, information-dense sentences with no filler. The core action, scope, independence guarantee, and critical idempotency requirement are all front-loaded and every clause earns its place.

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?

For a creation-style tool, the description provides the essential selection and invocation facts: what it creates, from how many sources, that the copy is independent, and the required idempotency key. It does not specify the return shape or whether the operation is asynchronous, which could matter for follow-up polling via get_audience_operation, but the core contract is well covered.

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?

Schema description coverage is 60%; custom_audience_ids, idempotency_key, and name already carry schema descriptions. The tool description mostly restates those constraints ('2-64 source audiences', 'Requires Idempotency-Key') rather than adding new meaning. The optional ad_account_id and description parameters remain unexplained in both the schema and the description, so coverage is not fully compensated.

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 states a specific verb ('Create'), a specific resource ('a new audience'), and the exact scope (all matched members from 2-64 source audiences). It also adds 'Independent copy,' which differentiates this from in-place audience mutation tools like add/remove/replace_audience_members.

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 makes the tool's context clear: use it when you need a new audience built by merging 2-64 existing audiences as an independent copy. It does not explicitly name alternative tools or state when not to use it, but the 'new audience' and 'Independent copy' phrasing provides enough directional guidance against in-place modification tools.

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