purge_cache_tool

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It clearly states that it purges cached content, implying a destructive action, but does not explicitly mention consequences like irreversible removal, impact on all visitors, or potential rate limits. The action is implied but not elaborated. Since 'purge' is a well-understood destructive operation, the description is minimally transparent but lacks depth about side effects.

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 extremely concise: two short sentences. The first sentence states the purpose, and the second gives usage guidance. There is zero fluff, no repetition of schema details, and every word earns its place. It is front-loaded with the core action and immediately provides actionable usage instructions.

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?

Given the tool has six parameters, mutual exclusivity, and Enterprise plan restrictions, the description covers the core usage effectively. It does not explain return values, but an output schema exists, so that is not needed. It could have mentioned that purge is irreversible or that only one mode should be used, but it already implies 'use one of'. The description is complete enough for an agent to understand what to do, though it could be more explicit about the destructive nature and any rate 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 coverage is 100%, so the baseline is 3. The description adds value by explicitly stating 'Use one of: purge_everything, files, tags, hosts, or prefixes', which conveys mutual exclusivity not stated in the schema. It also reinforces the Enterprise plan requirement for tags, hosts, and prefixes, which is already in the schema but reinforced in a usage context. This adds semantics beyond the schema.

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 clearly states the action ('Purge cached content') and the specific resource ('Cloudflare's edge'). It distinguishes itself from sibling tools, which are all list/create/update/delete operations for DNS, rules, and analytics, while this is the only purge operation. The purpose is unambiguous and specific.

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?

The description explicitly lists the five possible modes (purge_everything, files, tags, hosts, prefixes) and indicates that tags, hosts, and prefixes require an Enterprise plan. This tells the agent which parameter to use for different scenarios. Since this is the sole purge tool, there are no alternative tools to compare against, but the guidance within the tool is clear and actionable.

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