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

Annotations already declare readOnlyHint=false, destructiveHint=true, idempotentHint=false and the confirmation requirement, so the primary risk profile is covered structurally. The description adds real value beyond that by disclosing the lifecycle consequence (removal is not permanent; a later submit creates a new listing) and the fact that nothing runs without confirm:true. It stops short of describing the failure/partial-success response shape, which prevents a 5.

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 compact sentences with the destructive effect front-loaded, followed by the usage condition, the confirm requirement, and the targeting choice. No sentence is filler, and the ordering matches how an agent would need to reason about the call.

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, non-idempotent tool with no output schema, the definition covers effect, irreversibility semantics, the confirmation gate, and the targeting modes. Combined with annotations and the schema, an agent has everything needed to decide and invoke correctly.

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 coverage is 80%, so the schema already documents each parameter, including the confirm/confirm_required contract. The description reinforces the targeting decision (item_ids versus all_items:true) in usage terms rather than just repeating types. It adds nothing about ad_id or project_id, so it is a modest improvement over the schema rather than a substantial one.

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 precise verb and resource ('AD items: remove') and immediately specifies the effect: ending the chosen items' listings on the LIVE ad channel. The 'chosen items' phrasing plus the trailing 'Target item_ids or all_items:true' distinguishes it from the sibling remove_all_ad_items, and 'a later submit creates a new listing' separates it from submit_ad_items.

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 gives an explicit trigger ('Use this when the user asks to take specific listings down') and states the precondition for execution ('Needs confirm:true after the user agrees'), plus the consequence that a later submit restores a listing. The invocation conditions an agent needs are fully spelled out rather than inferred.

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