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

Annotations already establish readOnly/idempotent/non-destructive, and the description adds real behavioral context beyond that: a hard 50-page-per-call ceiling, the failure mode where scanned pages return empty rather than erroring, and the fact that this call is free. It does not say what the page-by-page payload actually looks like or how last_page defaults beyond the 50-page note.

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 clauses, each doing distinct work: what it returns, the pagination cap and continuation, the scanned-page escape hatch with cost. Front-loaded with zero filler.

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?

No output schema exists, and the description covers the return semantics that matter (text per page, empty on scanned pages, 50-page chunks). Combined with annotations covering safety, an agent has what it needs to call this correctly.

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 only 33% (file_id is the sole documented property), so the description has to carry weight. It explains first_page usage for continuing past the page cap, but last_page is never mentioned anywhere and its default/relationship to the 50-page cap is left to inference.

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?

Names the exact resource (a PDF in the store) and the scope of the return (text, page by page), plus a 50-page call cap. It also names the sibling it is not (files_ocr) for the scanned-page case, so an agent can separate the two without opening either 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?

Gives an explicit routing rule: when pages have no text layer, use files_ocr instead (with its per-page price as a decision signal). Also tells the agent how to continue past 50 pages via first_page. No guidance on alternatives like files_read_text or google_drive_read, so it is clear but not exhaustive.

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