Export attachment

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

With no annotations, the description carries the full burden of behavioral disclosure. It clearly states that the tool decrypts, writes to disk by default, returns a path, and offers an inline base64 alternative for small files. It also notes 'works for any size' for the default mode. This goes beyond the schema's parameter list and gives useful operational context, though it does not disclose potential edge cases (e.g., what counts as 'small' or overwrite behavior).

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 description is two sentences long and front-loads the core purpose. The first sentence states the action and resource; the second explains the default behavior and an alternative. Every word earns its place with no filler or repetition of schema fields.

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 tool with five parameters, a 100% covered schema, and no output schema, the description provides enough context: it explains the two output modes, the prerequisite of an unlocked vault, and the scalability of the default mode. It could go further by detailing error conditions or the exact return structure for inline mode, but it is not incomplete.

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 has 100% description coverage for all five parameters, so the baseline is 3. The description adds value by clarifying the behavior tied to the `inline` parameter (returns base64 instead of writing to disk) and explaining the default output path. This goes beyond the schema's brief parameter descriptions, especially for `inline` and `dest`, so a 4 is warranted.

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 a specific verb and resource: 'Decrypts a file attachment from an unlocked vault.' This clearly distinguishes it from sibling tools like list_attachments (which lists) and get_item (which retrieves metadata). The phrase 'file attachment from an unlocked vault' precisely scopes the operation.

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?

The description conveys when to use the tool: it requires an unlocked vault, implying a prerequisite. It also explains the two modes (default disk write vs. inline base64) and states that the default works for any size while inline is for small files. However, it does not explicitly name alternative tools or say 'use list_attachments to find attachment names,' so it falls slightly short of a 5.

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