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

With only readOnlyHint=false and destructiveHint=false as annotations, the description carries the behavioral burden and does so substantively: it discloses static-page output, signature-aware handling, link preservation, watermark stamping, image compression, PDF/A output, OCR, and ZIP sidecar metadata. It adds meaningful behavioral context without contradicting the annotations.

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 core operation is front-loaded in one clear sentence, and the remaining features are compressed into a single dense list that earns its place for a 21-parameter tool. The redundant 'Flatten PDF —' prefix duplicates the title, but otherwise the prose is efficient and well-structured.

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?

For a complex 21-parameter tool, the description gives a broad capability overview while the schema handles detailed parameter semantics, defaults, and constraints. The ZIP bundle mention hints at return shape even without an output schema, though an explicit pointer to pdf_flatten_batch for multi-file jobs would make it fully complete.

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 every parameter already has its own description, defaults, enums, conditional read-only notes, and tier requirements, so the baseline is 3. The main description adds a useful high-level grouping of features, but it does not add per-parameter syntax or conditional semantics beyond what the schema already provides.

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 opens with a specific verb+resource ('Flatten PDF forms and annotations into static page content') and enumerates a detailed feature set (modes, pages, signatures, links, watermarks, compression, PDF/A, OCR, ZIP export) that clearly separates it from most PDF tools. However, it does not explicitly distinguish this single-file tool from the sibling pdf_flatten_batch, so it falls just short of full sibling differentiation.

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 feature list conveys likely use cases, and the schema's watermarkTile parameter explicitly directs users to pdf_watermark for tiling, which is genuine alternative guidance. But the main description never states 'use this when...' or explains when to prefer pdf_flatten_batch or pdf_to_pdfa, leaving sibling selection mostly implicit.

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