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

The description goes well beyond the annotations (destructiveHint, idempotentHint) by detailing mutation modes (validate_only, preview_only, execute), the partial failure policy (completed_items_not_rolled_back), the derived idempotency key behavior, and the seat requirement. This gives the agent critical execution-time expectations.

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?

The description is verbose and repetitive; the first two words merely echo the tool name, and most of the long middle section is generic mutation/response boilerplate that doesn't help distinguish this tool. A focused description of what 'archive' does and which parameters matter would be far more useful.

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?

Although an output schema exists, the description omits core domain knowledge: what archiving an advertiser actually does, any prerequisites or side effects, and what the 12 parameters are for. The generic operational details don't compensate for this lack of tool-specific 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?

With 0% schema description coverage, the description was expected to compensate, but it only mentions seatId/seatName in the seat-authorization rule and idempotencyKey in the retry note. The remaining 10 parameters (accountId, advertiserId, dryRun, flightId, expectedVersion, etc.) are completely unexplained, forcing the agent to guess their meaning.

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 opens with 'archive advertiser,' clearly identifying the verb and resource, and the sibling tools (archive_campaign, archive_creative) confirm the scope is advertiser-specific. However, it never states what archiving does or how it differs from related operations, so it's clear but not fully explicit.

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?

No explicit guidance on when to use this tool versus alternatives like update_advertiser or delete_flight. The generic mutation boilerplate ('Task support: forbidden') offers no decision-making context, leaving the agent to infer usage from the name alone.

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