Purge CDN cache

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

Annotations already declare destructiveHint=true and openWorldHint=true, so the safety profile is known. The description adds value beyond them: that purge=all causes service impact, that individual purges need exact URLs, and that scope must not be broadened. It does not describe asynchronous behavior, propagation timing, or rate limits, which would be the next level.

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?

Very tight: destructive warning first, one-sentence purpose, endpoint, then two conditional clauses and a hard constraint. No sentence is redundant and ordering is front-loaded by risk level.

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, no-output-schema tool this covers the risk profile, mode semantics, and endpoint well enough to call correctly. What is missing is the conditional requirement structure (is purge_urls mandatory when purge=individual?) and any note on purge propagation or limits.

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 carry the load, and it does for the two non-obvious parameters: it explains the purge enum semantics (all vs individual) and the conditional requirement that purge_urls be exact when individual is chosen. The domain parameter is left to its pattern, which is self-evident from the name.

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+resource ('Purge CDN cache') and tags the operation as [DESTRUCTIVE] up front, so an agent cannot mistake it for a read or a settings change. It also names the exact upstream endpoint, which distinguishes it from the sibling invoke_cdn_api generic wrapper and from get/update_caching_settings.

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?

Gives concrete selection guidance between the two modes: purge=all clears the whole domain (with a service-impact warning), purge=individual requires exact purge_urls, and 'Never broaden scope' is an explicit exclusion. It stops short of naming sibling alternatives or stating prerequisites, but the mode-selection guidance is unusually actionable.

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