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

The annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds useful context beyond that: the result set is permission-filtered to readable pages, and it explains what 'recognized' means, including the pages read and billed, which matters because it implies a prior cost or processing step.

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?

All the information is packed into one long clause-chained sentence, and the return-field inventory is dense enough to be hard to parse on a first read. The alternative-tool routing is correctly placed at the end as an action cue, but the sentence could have been split or trimmed without losing content.

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 describing the returned fields (id, name, page, originUrl, fetchedAt, page count, recognized state, viewUrl) carries real weight and is done well, including the practical note on where viewUrl can be used. It doesn't mention ordering, pagination or result limits, which is the main remaining gap for a list tool.

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 100%, and the schema already documents the optional project key and its default of all readable projects. The description adds only the framing that a project 'keeps' these PDFs; it doesn't explain key format, case sensitivity or what a null value expands to beyond what the schema states. The baseline of 3 applies.

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 identifies the resource: PDF copies that a project keeps on its wiki pages, with their ids, names, pages and origin. It distinguishes itself from read_pdf_text and search_pdf_texts by naming them as the tools for reading and searching the text, but the listing verb itself is only implied by the noun-phrase framing, so it stops short of a clean 'Lists X' statement.

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 explicitly routes the agent to read_pdf_text for the content and search_pdf_texts for searching inside it, and it adds the scoping rule that only files on readable pages are returned. It doesn't cover the negative case, such as when to use get_wiki_attachment or copy_pdf_to_wiki instead, but the guidance is clear enough for selection.

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