pdf_extract_document

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

With no annotations, the description carries the full burden and does add real value: it discloses the return dict shape and clarifies that pageCount is the number actually returned, not the document total — a non-obvious behavior. It also warns that large documents should be chunked, implying resource constraints, though it does not state read-only safety explicitly or describe failure behavior for missing/encrypted files.

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?

Scoping and default behavior are front-loaded in the first two sentences, followed by return-shape info. Slightly dense prose with parenthetical keys, but every sentence carries information an agent needs.

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?

There is no output schema, so the description must explain returns — it does, naming 'metadata', 'pageCount', and 'pages' plus PageData per page, and clarifies the pageCount semantic. It stops short of describing what PageData fields contain, which for a nested return type would be the last missing piece.

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 baseline is 3. The description restates the range semantics ('first_page..last_page', omit both for whole document) in a useful summarized form, but adds no format detail beyond what the schema's parameter descriptions already say.

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 uses a specific verb and resource ('Extract every object of every page in a range') and states the scope precisely, distinguishing full-document from ranged extraction. It never names pdf_extract_page, the closest sibling for single-page extraction, so the differentiation is implicit rather than explicit.

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?

It gives concrete operating guidance: 'Omit both bounds for the whole document' and 'Large documents should be read in ranges, or exported with pdf_export', naming an alternative and the condition that selects it. What's missing is any routing to pdf_extract_page for single-page reads or pdf_get_metadata when only document info is needed.

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