create_cache_items_purge

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

Annotations declare idempotentHint=true and destructiveHint=false, suggesting a non-destructive, repeatable operation, yet the name and endpoint with 'purge' strongly imply deletion. The description does not reconcile this: it never clarifies whether it is destructive or what side effects occur. It does not explain the response shape or error behavior. Given the annotations already cover some traits, the description adds almost no behavioral context and even hints at potential contradiction.

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 short and gets to the endpoint quickly, but it mixes the endpoint into the prose awkwardly and leaves the explanation fragmented. The instruction to read GET or /schema is useful but could be better structured as a separate note. Overall it is concise but not well-organized.

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 tool with a single unstructured body parameter and no output schema explanation, the description is severely lacking. It does not clarify the purpose, the required body, the differences from sibling tools, or the impact of the operation. The agent is left to guess and must go to external documentation. This is far from complete.

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?

The only parameter 'body' is an opaque object with additionalProperties true, and the schema description coverage is 0%. The description simply says 'Request payload' and tells the user to read the GET or /schema endpoint to discover fields. This is not helpful; it places the entire documentation burden on external endpoints. There is no attempt to describe likely body properties or give an example.

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 says 'Create or act on items purge' and shows the endpoint POST /api/cache/items/purge dropped into the middle of prose. It is not a clean verb+resource statement; 'Create or act on' is vague and 'purge' is ambiguous (is it a noun or a verb?). Since the sibling create_cache_purge exists, the phrase 'items purge' weakly distinguishes it, but the purpose is still unclear without inferring it is a cache purge operation.

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?

There is no guidance on when to use this tool versus the sibling create_cache_purge, nor any mention of alternatives or prerequisites. The only hint is the endpoint path, which the agent might not understand. The instruction to read the GET or /schema endpoint first is generic and does not clarify when to call this purge.

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