pl_get_document

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds substantial behavioral detail: pagination at ~5000 characters, the exact response fields (content, page, total_pages, has_more), the deprecated page_number alias, native pagination for isap, and a concrete extra example for eu-compliance. It also enumerates error types, enriching the transparency beyond the annotation baseline. No contradiction with annotations exists.

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 dense paragraph, but every sentence conveys necessary information: pagination, native pagination, extra per source, and error codes. No filler or redundancy. While not broken into bullet points, its length is justified by the tool's complexity. It is front-loaded with the main purpose.

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 the tool's high complexity (source-specific IDs, optional extra, pagination modes, error taxonomy), the description covers all functional aspects necessary for correct invocation. It includes edge cases like page_number conflicts, missing required extra, and upstream_error with guidance to search first. An output schema exists, so return-value details are not needed, and the description's pagination overview complements it.

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 0%, so the description bears full responsibility for parameter meaning. It does this thoroughly: document_id is explained with source-specific formats, page is clarified as 1-based, extra is given a concrete example, and page_number is identified as a deprecated alias. Source is implicitly understood from pl_list_sources. This fully compensates for the empty schema.

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 opening phrase 'Fetch the full document' uses a specific verb and resource, clearly distinguishing it from sibling tools like pl_search (search) and pl_list_sources (list sources). It also delineates scope by enumerating document types and referencing per-source ID formats.

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?

Usage context is clear: it explains how to fetch documents and how pagination works, and it references pl_list_sources for document_id format and pl_search for pagination comparability. However, it does not explicitly state when to use this tool versus alternatives or provide 'when not to use' exclusions, though it hints at searching first before fetching.

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