pdf_draw

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

No annotations are provided, so the description bears full responsibility for behavioral disclosure. It only says 'Draw shapes', but fails to mention that the tool creates a new PDF (due to outputPath), whether the original file is modified, or any side effects. The behavioral impact (mutating vs. creating a new file) is not transparent.

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 extremely concise: two sentences totaling about 20 words. The first sentence front-loads the primary action and supported shapes, and the second adds a use-case context. No unnecessary words or repetition, making it efficient for an agent to parse.

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 complexity of 3 required parameters and a nested shapes array with many optional fields, the description is minimal. The schema covers parameter details well, but the description omits output behavior (creates a new PDF) and does not clarify coordinate system or default drawing behavior. Without an output schema, more context on the result would be helpful.

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%, with each parameter having a description in the schema itself. The tool description adds minimal extra meaning beyond the schema (e.g., clarifying 'circles/ellipses' matches the ellipse type). According to guidelines, with high coverage, baseline is 3, and the description does not significantly enhance parameter understanding.

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 'Draw shapes on PDF pages' and lists specific shape types (rectangles, lines, circles/ellipses), which differentiates it from sibling tools like pdf_add_image, pdf_add_text, and pdf_highlight. The verb 'draw' plus resource 'PDF pages' makes the purpose unambiguous.

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 includes 'Useful for annotations, diagrams, or marking up documents', which gives a general context, but it does not explicitly state when to use this tool versus alternatives (e.g., when to use pdf_add_image instead). No exclusion criteria or prerequisites are mentioned, so guidance is only implied.

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