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

Annotations already indicate the tool is not read-only (readOnlyHint: false) and not destructive (destructiveHint: false). The description adds rich behavioral context: operations are applied in order, the source document is untouched and a new render is created, 'cover' only hides content visually without deleting bytes (and carries a COVER_VISUAL_ONLY warning), AcroForm values are flattened by default, and there is no redaction operation ('op: redact' is rejected). This goes well beyond the annotations and fully discloses the tool's behaviors and limitations.

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 relatively long but every sentence contributes necessary information. It is front-loaded with the core purpose and operations, then covers parameters, behavior, error handling, and prerequisites. It could be slightly more concise by omitting some redundancy (e.g., the cover operation explanation appears both in the top-level description and in the operations parameter description), but overall it is well-structured and informative without being wordy.

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?

Despite no output schema, the description explicitly states the return fields: '{ id, url, bytes, durationMs, name, warnings }' and explains the importance of reading warnings. All five parameters are fully documented in the schema, and the description adds behavioral context for each. The tool's complexity (multiple operation types, two exclusive input sources, API key requirements, non-destructive vs visual-only actions) is thoroughly covered. The description leaves no major gaps for the agent to infer.

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 baseline is 3. However, the description adds significant meaning beyond the schema: it explains that coordinates use PDF points with origin at BOTTOM-left, that flattenFields defaults to true (with guidance on when to set false), that operations must be supplied in order, and that the warnings field must be read because out-of-range pages and unmatched field names are reported there rather than failing. These details are critical for correct usage and are not present in the schema descriptions alone.

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 states the verb ('Modify an existing PDF') and specifies the three operations: fill AcroForm fields, stamp text, paint opaque boxes. It distinguishes from the sibling tool render_pdf by contrasting when to use each: 'Use this when a document already exists... use render_pdf when the document should be generated from a template instead.' It also mentions downstream tools that consume the result, further clarifying the tool's role in the workflow.

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 provides explicit when-to-use guidance: 'Use this when a document already exists and needs values or marks; use render_pdf when the document should be generated from a template instead.' It also gives when-not-to-use guidance for the 'cover' operation: 'never use it to hide secrets or personal data... it is NOT redaction.' The description explains the exclusive source parameter choice, the need for an API key with `render` scope, and how errors are reported (via warnings). All this helps the agent select the right tool and use it correctly.

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