Reorder Pages

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

The description explicitly discloses that pages are copied into a new document, that document-level information such as tagged structure, XMP, attachments, AcroForm, and bookmarks is not carried over, and that lost items are reported in warnings. This goes well beyond what the annotations provide and helps the agent anticipate important side effects.

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 concise, front-loaded with the core operation, and every sentence carries meaningful guidance. It communicates the requirement, the data-loss behavior, and the remediation steps in three sentences without redundancy.

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?

The tool has five parameters but the schema fully documents them, while the description covers the main behavioral caveat and follow-up actions. There is no output schema, but the description mentions warnings, and the returnBase64/outputPath parameter descriptions clarify output behavior. Minor gaps such as return-value detailing are adequately covered by schema and context.

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 parameter names and types are already documented. The description adds crucial semantics not enforced by the schema—that 'order' must be a permutation listing every page exactly once—which is essential for calling the tool correctly.

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 states the specific operation ('Reorder pages') and the essential constraint on the 'order' array (every page exactly once). This clearly distinguishes the tool from sibling operations like rotate_pages, extract_pages, and delete_pages.

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 clear context for use: reordering pages in a new document and following up with other tools to restore lost document-level features. It does not explicitly state when not to use this tool versus alternatives, but the lossiness caveat effectively communicates the tradeoff.

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