Manage audiences

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

Annotations indicate readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true. The description adds important behavioral context: list is read-only, delete/clone require a two-step confirmation via confirm_hash and confirm, and access_denied should be skipped without retry. This goes beyond annotations by detailing the confirmation workflow and error handling. It doesn't explain what happens on create/rename errors or the output format, but given the annotations and output schema, this is a good level of disclosure.

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?

Extremely concise: two sentences that pack action enum, read-only note, confirmation requirement, and error handling. No filler, front-loaded with the core operation list.

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 multi-action tool with 7 parameters and 0% schema coverage, the description covers the action semantics and critical confirmation flow but omits parameter-to-action mapping and output details (though output schema exists, so return values are covered). It also doesn't mention required parameters for each action (e.g., audience_id for rename/delete/clone). Given the complexity, more guidance on parameter usage would improve completeness.

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 0%, so the description must compensate. It maps actions to parameters implicitly (confirm_hash and confirm for delete/clone) but doesn't describe the other parameters: title, user_ids, file_path, audience_id. For example, it doesn't say which action uses audience_id, or what file_path/user_ids are for (create/clone?). This leaves several parameters semantically unexplained. Baseline 3 is appropriate.

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?

States the resource (custom audiences) and enumerates the exact operations: list|create|rename|delete|clone. An agent knows precisely what this tool does without ambiguity, and the operation set distinguishes it from sibling tools like create_ad or edit_ad.

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?

Provides clear conditional guidance: 'list is read-only; delete/clone use two-step confirm_hash plus gate confirm' and 'code=access_denied means skip, do not retry.' This tells the agent when to set confirm_hash and confirm, and how to handle a specific error. However, it doesn't explicitly state when to use this tool vs alternatives or prerequisites for each action beyond the confirmation flow.

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