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

Annotations only declare readOnlyHint and openWorldHint; the description goes well beyond by disclosing size/page limits, the text-layer requirement, per-call pricing, that failed calls are free, the daily free tier, and the quote-then-sign payment handshake. This is exactly the behavioral context an agent needs.

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?

Front-loads purpose, then capability limits, then pricing/billing mechanics. Every sentence carries information, though the pricing paragraph is dense and slightly marketing-flavored rather than purely operational.

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 stateless read tool with no output schema, the description covers return contents, input constraints, failure behavior, and the two-step payment flow. An agent has everything needed to decide to call it, quote, and retry with payment.

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 100%, so the input schema already documents url, payment and max_pages fully. The description reinforces the payment flow ('call without payment to get a quote') but adds no syntax or format detail beyond what the schema already provides. Baseline 3 is appropriate.

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 (read), a precise resource (PDF from an http(s) URL), and the exact return shape (text page by page plus title, author and page count). This clearly separates it from sibling reading tools like read_page, page_brief and screenshot_page.

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?

Gives solid context on when it works and when it does not: text-layer PDFs up to 25 MB/300 pages succeed, scanned PDFs without a text layer are refused, and the payment quote flow is spelled out. It does not explicitly name an alternative sibling (e.g., read_page) or state when to prefer one, so it falls 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.