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

With only readOnlyHint/openWorldHint declared, the description carries extra weight and delivers genuinely useful operational facts: a hard merge cap of 30 PDFs, the compression presets available, and the x402 payment model with per-call cost ($0.0045 USDC). Cost and payment/auth requirements are exactly the kind of context annotations cannot express. It stops short of describing failure modes, size limits for other actions, or how results are returned.

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?

A single dense sentence front-loads the tool identity and engines, then enumerates capabilities, then ends with the pricing constraint. No filler, no restatement of the name, and the cost sentence is placed last where it belongs.

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 12-parameter tool with zero required parameters and no output schema, the description is adequate but incomplete: it never states which parameters are required for which action (a critical ambiguity when nothing is mandatory), nor how results come back (base64 vs raw bytes vs share links). The action taxonomy is covered, but an agent still cannot construct a correct call for, say, split or encrypt from the description alone.

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 description coverage is only 50%, so the description must compensate, and it largely does: it maps actions to parameters that the schema leaves bare — ranges for split, angle for rotate, text for watermark, quality presets (screen/ebook/printer) for compress, password for encrypt/decrypt, and files for merge. That materially explains half-documented parameters like text, angle, pages, ranges, and password. It does not cover everything (e.g., the interaction of format=binary vs default output), so not a 5.

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 names a concrete resource (PDF) plus the backing engines (qpdf + Ghostscript) and enumerates the specific operations supported: merge, split, extract, rotate, compress, watermark, encrypt/decrypt, info. That is far more than a tautology. It loses a point because it never distinguishes itself from close siblings such as pdf, pdf_to_images, pdf_fill, or doc_convert, leaving the agent to guess which PDF tool to pick.

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 text lists what actions exist but never says when to choose this tool over the many adjacent siblings (pdf, pdf_to_images, pdf_fill, doc_convert, office_convert). There are no preconditions, exclusions, or routing hints, only a capability list.

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