PDF to text

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds genuinely new behavioral facts: large documents are cut at max_chars and flagged truncated, continuation is done via the pages field, and the returned text is untrusted document content. The untrusted-content warning is behavioral guidance that appears nowhere in the structured fields.

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?

Three short sentences, front-loaded with the core action and scoping. Each sentence carries distinct information (what it reads, the scanned-page caveat, the truncation/continuation rule plus the untrusted-content note); there is no padding.

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?

Given a complete output schema, the description correctly omits return-value documentation and instead covers the failure mode (no text on scanned pages), the truncation contract, and the trust level of the content. Nothing an agent needs to call it correctly is missing.

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%, and the description fills the notable gaps: it explains max_chars' truncation consequence and the truncated marker, and it explains that the pages field is the mechanism for continuing past the cut. It adds meaning beyond the bare schema text for two of three parameters.

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?

Starts with a specific verb and resource ('Read the embedded text of a PDF, page by page') and qualifies it with 'embedded', which separates it from OCR-type or structure-extraction siblings such as pdf_extract_structure or pdf_info. An agent can pick this tool apart from its many siblings without opening the 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?

The description gives the key usage condition for this tool family: scanned pages have no text (has_text false), telling the agent when this tool will not deliver. It also explains how to continue reading (use the pages field after truncation). It stops short of explicitly naming an alternative tool for scanned documents, so it is clear context rather than full when/when-not routing.

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