delete_volume_file

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

Discloses destructiveness but fails to describe recusive deletion behavior, permissions needed, or the exact role of the confirmation token. No annotations exist to provide additional guidance.

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?

Extremely concise with two front-loaded sentences, but lacks detail at the expense of completeness.

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?

Leaves out crucial context: no explanation of parameters, no reference to confirmation flow, and no output description. Incomplete for a destructive tool with four parameters.

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?

No descriptions in schema or text explaining 'name', 'path', 'env_id', or 'agent_token'. With 0% schema coverage, the description must compensate, but it does not.

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?

Clearly states it deletes a file or directory inside a volume, distinguishing it from read-only or creation tools. However, it could specify the volume name parameter.

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?

Mentions destructive nature and confirmation token requirement, implying caution and a two-step process. Does not explicitly compare to alternatives like read_volume_file or confirm_operation.

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