pdfpeek: password-protect a PDF

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

Annotations are broad (readOnly=false, destructive=false, idempotent=false, openWorld=true), and the description adds a lot: AES-256 encryption, semantic split of user vs owner password, random unknown owner password by default meaning restrictions can never be lifted, fresh encryption each call, passwords never logged/stored/echoed, and forced removal of active content. It also covers failure/timeout codes (413, 422, 503) and timing (1-3s), which is genuinely beyond the annotations. It stops short of a full disclosure of why destructiveHint=false despite the mutating/scrubbing behavior, but the safety-relevant profile is well covered.

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?

Purpose and sibling routing are front-loaded in the first sentence, then behavior, limits and pricing follow in dense but non-redundant sentences. It is long, and a few clauses (pricing, free-tier, untrusted-data warning) push against strict concision, but nearly every sentence carries load-bearing operational 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?

For a mutation tool with an output schema, nested objects and one required parameter, the description covers encryption semantics, defaults, forced content stripping, error/limit conditions (413/422/503), latency, cost and free-tier limits. An agent has everything needed to call it correctly and interpret the outcome.

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%, so the schema already documents all six parameters and the nested Permissions object, giving a baseline of 3. The description adds real interpretive value beyond the schema: user_password opens the file, owner_password is what lifts permissions (all allowed by default), omitting owner_password uses an unknown random value so restrictions become permanent, and output=url returns a 24 h link. This meaning is not derivable from the field names alone.

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+resource ('Password-protect a PDF') and explicitly distinguishes itself from siblings pdf_unlock (remove a password) and pdf_redact (black out content). An agent can select it without opening any schema.

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?

Names the alternatives and the condition that selects them ('To remove a password use pdf_unlock; to black out content use pdf_redact'), plus a when-not case: encrypted input must be unlocked first (422). No routing inference is left to the agent.

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