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

Annotations already declare destructiveHint=true and readOnlyHint=false; the description adds the genuinely useful qualifier that history is retained, which tells the agent a delete is recoverable in some form. It omits other behavioral essentials for a destructive batch mutation: no explanation of why a required idempotency_key exists (retry safety), no 25-item cap mention, and no confirmation of whether retention is permanent.

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?

A single front-loaded sentence with no filler, and the retention caveat is appended efficiently. The phrase 'change swipe-file entries' is vague enough that one clause of clarification would have earned 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 batch, destructive, 5-parameter mutation with zero schema coverage and no output schema, one sentence is not enough — the agent must infer the meaning of idempotency_key, the array limits, and the effect of each action from the raw schema alone.

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 carries the full burden, and it covers only the action semantics loosely ('restore' ≈ unarchive, 'change swipe-file entries' ≈ save_to_swipe/remove_from_swipe). The other three parameters — workspace, the ads UUID array with its 25-item cap, and the mandatory 16–128 char idempotency_key — plus the optional note receive no explanation anywhere.

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 set (batch archive, restore, delete, change) against a specific resource (swipe-file entries), which maps recognizably onto the enum actions and distinguishes it from the single-item sibling competitor_ad_get. It does not name any sibling explicitly, and 'restore' is a loose paraphrase of the enum value 'unarchive', so it stops short of a 5.

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?

'Batch' implicitly signals this is for multi-entry operations of up to 25 items versus the single-record competitor_ad_get, which is a real usage hint. However, no alternative tool (competitor_ad_reference_save, competitor_settings_save) is named and no when-not-to-use condition or prerequisite is stated.

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