List Items

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

Annotations already declare readOnly/idempotent/non-destructive, so the description is not carrying the safety burden, yet it still adds real value: it discloses that decrypted actions return plaintext item contents, warns never to log or echo them, and notes that move_to_trash is a recoverable soft-delete. The one gap is that it does not describe listing behavior such as paging or result limits.

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 plaintext warning is valuable and correctly front-loaded, but the opening two sentences mix this tool's purpose with family-level read/write semantics, and the trailing CONCEPT tag and backticked route enumeration are payload-free for an invoking agent. Roughly half the text serves the tool group rather than this call.

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?

With an output schema present, the description need not explain return shape, and it does cover the sensitive-plaintext aspect well. It is still incomplete for a listing tool: no guidance on the params_json contents or on how listing results are scoped, which is the main decision an agent faces here.

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 single parameter is a free-form params_json bag whose schema text ('JSON object of parameters for the action') conveys no field-level meaning, so the nominal 100% coverage is formal rather than substantive. The description does not say which keys the list action accepts (search terms, organization/folder filters, pagination), leaving the agent to guess the pass-through schema.

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 first sentence names the resource ('List items (vaultwarden_ciphers)'), but the following sentence 'Read and write vault items (ciphers)' describes the whole cipher family rather than this read-only action, blurring what the tool actually does. Nothing distinguishes it from close siblings such as vaultwarden_get_ciphers, vaultwarden_get_cipher, or vaultwarden_ciphers_get_item, which an agent could easily pick instead.

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: the name and 'list_items' phrase suggest a listing call, and the note that other ciphers routes are reachable via call_operation is a partial routing hint. There is no statement of when to choose this over get_item (single item) or get_ciphers, nor any prerequisites or filter conventions for listing.

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