Push the list to an ad account: audience.create the first time, then audience.sync

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

Beyond readOnlyHint=false and openWorldHint=true, the description adds genuinely useful behavior: this is a WRITE, it will not execute unless confirm is true, and there is no server-side dry run, so confirming is the only safeguard. It stops short of saying what replace mode does to existing audience membership, which is the most consequential unknown for a write.

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?

Two sentences, front-loaded with the action, ending with the safety warning. Slightly awkward API-style dotted naming ('audience.create') forces the reader to translate to tool names, but otherwise there is no wasted wording.

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 four-parameter mutation with a nested body, openWorldHint, and no output schema, the description covers the lifecycle and the confirm gate but leaves the mode semantics and the consequence of a replace sync unexplained. An agent can call it, but could plausibly wipe membership by choosing replace without any warning here.

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?

Coverage is 50%: confirm and idempotencyKey are documented in the schema, and the description partially compensates by revealing via the POST path that 'id' is the audience list id and by framing 'body' as targeting an ad account. However, the add-vs-replace 'mode' enum — the single most important semantic choice for a sync — is explained nowhere.

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 uses a concrete verb and resource ('Push the list to an ad account') and distinguishes the sync step from the initial create step in the audience lifecycle. It does not name the actual sibling tools (audiences_createList, audiences_createLookalike), so an agent must infer the mapping from 'audience.create'/'audience.sync' to the hyphen-free tool names.

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?

It supplies clear routing context: use create the first time, use sync on subsequent pushes. It also states the hard precondition that nothing is sent without confirm: true. It lacks explicit exclusions (e.g., when to use audiences_remove or audiences_addMembers instead) and never names the sibling tools directly.

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