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

With no annotations, the description carries the transparency burden. It discloses the cost ($0.001) and lists the returned data, which is useful context. However, it does not explicitly state whether the operation is read-only or if any side effects occur, nor does it explain the payment requirement flow (left to the schema). The cost disclosure is a plus, but other behavioral traits remain opaque.

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 a single, compact sentence that front-loads the purpose, enumerates key output facts, and includes pricing. Every word contributes value; there is no fluff or repetition of schema details. It is appropriately sized for a simple tool.

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?

The tool has no output schema and no annotations, so the description carries the full load for explaining what the agent gets. It lists the output facts and cost, which covers basics, but omits details about the payment flow (e.g., what happens if x_payment is omitted) and any potential error/edge-case behavior. For a paid tool, this is a noticeable gap.

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% (x_payment is described, url is not). The description adds no parameter information whatsoever. It does not mention the url parameter or clarify the x_payment optional/requirement behavior, leaving a significant gap that the schema and description combined fail to fill for the url 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?

The description clearly states the tool provides 'PDF facts' before paying for parsing, enumerating specific outputs (pages, metadata, per-page text volume, scanned-or-not estimate). This distinguishes it from siblings like parse_document or pdf_pages by positioning it as a cheap pre-parser check. Though it lacks an explicit imperative verb, the intent is unambiguous.

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 phrase 'before you pay for parsing' provides clear usage context: use this tool as a low-cost preliminary assessment before committing to a more expensive parsing operation. It implies an alternative (full parsing) without naming it explicitly, and the $0.001 price reinforces the cost-sensitive use case. It does not state explicit exclusions or when not to use it.

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