Move to trash

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

Annotations already flag destructive=true and idempotent=false, but the description goes further: it explains why it is non-idempotent (an arrival timestamp is appended to the name), that the relative path is preserved, that it fails when no trash exists, and that a prior read is needed to supply rev. These are behavioral facts an agent cannot derive from the annotation block.

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?

Four compact sentences, zero filler, front-loaded with the core action before the failure modes, rev requirement, and restore route. Each sentence carries a distinct constraint the agent needs.

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 two-parameter tool with no output schema, the description covers the action, the naming side effect, the failure condition, the conditional parameter requirement, and the recovery path. Nothing an agent needs to invoke this safely is missing.

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 only 50% — rev carries a schema description but path has none. The description compensates by explaining the conditional meaning of rev (required only in overwrite="rev" zones, and it is the current rev you must read first) and by noting path's relative-path preservation. That is more than the schema alone offers, though path semantics remain thin.

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 precise verb and resource ("Discard a file by moving it into the trash of its own zone") and immediately separates itself from the sibling move_file by framing this as the removal path. The note that there is no delete operation tells an agent exactly which tool covers file removal.

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?

Explicit when-to-use ("this is the only way to remove something"), the precondition that fails the call (zone has no trash configured), the conditional requirement for rev in overwrite="rev" zones, and the alternative path for undo ("To restore, move_file it back out of the trash"). Nothing about tool selection is left to inference.

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