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

Annotations already flag destructiveHint=true and idempotentHint=false, so the safety profile is covered. The description adds genuinely new behavioral facts: the default is a preview (no change), and REMOVED is irreversible and must be the sole field in that call. It does not describe the preview response shape, but that is a minor omission given no output schema.

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, zero filler. The irreversible-status caveat is packed inline with the enum list and the preview rule closes the definition, so the highest-risk fact is not buried.

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 destructive mutation tool with 8 parameters and no output schema, this covers the essentials: what changes, what is permanent, and how to preview safely. Missing only a note on counting_type behavior and whether unrelated fields are preserved on update.

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 only 25%, so the description carries extra weight. It names the status enum values and implies the primary/name/default_value fields, but never mentions counting_type (whose enum semantics are critical) or the identification parameters. Partial compensation, not full.

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 a specific verb (change/update) on a specific resource (conversion action) and enumerates exactly which fields are mutable: status, primary flag, name, default value. The only sibling doing a different thing is ads_create_conversion_action, and the mutating vocabulary distinguishes it without ambiguity.

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?

"Previews unless confirm is true" gives clear operational context, and "REMOVED is permanent and must be sent alone" tells the agent when the tool must be called in isolation. It stops short of explicitly routing to ads_list_conversion_actions for lookup or ads_create_conversion_action for new actions, but the intent is inferable.

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