Edit Item

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

Annotations already declare readOnlyHint=false, destructiveHint=false and non-idempotent, so safety basics are covered. The description adds genuinely useful non-obvious context: this action handles plaintext item contents that must never be logged or echoed, and that soft-delete lives on move_to_trash rather than here. It does not say whether an edit replaces or merges fields, which matters for a non-idempotent write.

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 first sentence is front-loaded and useful, but several sentences describe other actions (list_items, get_item, create_item, move_to_trash) rather than this one, and the CONCEPT tag adds no operational value. Proportions are only partly appropriate for a single-action tool.

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 exists, so return values need not be explained. But for a non-idempotent mutation taking an arbitrary JSON parameter bag, the definition omits what an edit requires, whether partial updates are allowed, and what happens to unspecified fields — significant gaps the agent cannot resolve from structured data.

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 schema advertises 100% coverage but only documents an opaque 'params_json' JSON blob with no field breakdown, so real parameter semantics are effectively undocumented. The description does not name a single expected key (id, name, login, notes, folderId) or explain the JSON structure an agent must construct, leaving the caller to guess.

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 opens with 'Edit item (vaultwarden_ciphers)' and then describes cipher read/write generally, so the agent can infer it modifies an existing vault item. However, the bulk of the text is collection-level boilerplate and never distinguishes edit_item from the many sibling write routes (put_cipher, post_cipher_partial, put_cipher_partial, edit_member). The specific action is stated but not meaningfully differentiated.

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?

No guidance on when to use edit_item versus the numerous other cipher mutation tools in the sibling list, nor any prerequisites (item id, ownership, org/collection membership). The only routing hint given ('every other ciphers API route is reachable via call_operation') is generic and does not help select this tool.

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