Move To Trash

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

Annotations declare destructiveHint=false and readOnlyHint=false, and the description corroborates this by explaining the delete is soft and recoverable — useful context beyond the flags. It also adds a genuine operational constraint (never log or echo decrypted item contents), though that note is domain-wide boilerplate rather than specific to this action.

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 action-specific sentence is short and front-loaded, but the surrounding text is shared ciphers-domain boilerplate about decrypted actions and call_operation that does little for an agent choosing this specific tool. Roughly half the description is not about moving to trash.

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?

An output schema and annotations are present, so the description doesn't need to explain returns or the safety profile. It covers recoverability, the id-based targeting, and the confidentiality constraint — enough for correct invocation, with only the payload structure for params_json left thin.

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%, but the single parameter is an opaque params_json blob documented only as "JSON object of parameters for the action." The description's "by id" is the only hint that an item id belongs inside that object, which adds some value but leaves the payload shape underspecified.

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 names a concrete verb and resource — "move_to_trash soft-deletes items by id (recoverable)" — which tells an agent exactly what happens to the target item. The "recoverable" qualifier implicitly separates it from the many hard-delete siblings (delete_cipher, delete_item), but no sibling is named explicitly, so the differentiation still requires inference.

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?

Usage is only implied: "soft-deletes... (recoverable)" suggests this is the non-permanent alternative to deletion, and the closing sentence points at call_operation for other ciphers routes. There is no explicit when-to-use/when-not statement or named alternative such as vaultwarden_delete_cipher for permanent removal.

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