Password-protect a PDF

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

Annotations already declare non-read-only, non-destructive, idempotent behavior. The description adds value beyond them by naming the cipher (AES-256), making clear that the result is a copy rather than an in-place mutation, and stating the observable outcome (password required to open). It omits anything about failure modes, permission needs, or what happens with an already-encrypted input.

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?

Two sentences, no filler, and the core action and its effect are front-loaded before the safety constraint. Every clause carries information.

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 a rich annotation set and an output schema present, the description need not cover return values. It covers purpose, encryption strength, copy semantics, and password provenance; the only meaningful omission is behavior on already-protected inputs and any constraints on the source file.

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 67%: input and output are documented in the schema, but the password parameter has no description there. The description fills that gap by specifying the credential's provenance ('a password the user gave you for this purpose'), which is exactly the semantics an agent needs for that parameter.

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 specific verb and resource ('Encrypt a copy') plus the mechanism (AES-256) and the resulting behavior ('needs a password to open'), which makes it clearly distinct from pdf_unlock. It does not name or contrast with any sibling explicitly, so it stops short of the top anchor.

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?

'Only use a password the user gave you for this purpose' is a real usage constraint (do not invent, reuse, or repurpose credentials), which is more than nothing. However, there is no when-to-use guidance, no prerequisites (e.g. encrypted input, file permissions), and no reference to alternatives such as pdf_unlock or pdf_flatten.

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