pdf_validate

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

Annotations already declare readOnlyHint=true, so safety is covered, but the description adds meaningful behavioral context beyond that: the exact success/failure shape ({success: False, error, error_type}) and operation-specific result keys. It does not discuss performance, file-size limits, or what 'integrity' warnings imply, so not a 5.

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?

Front-loaded purpose, then clearly labeled 'Return Format' and 'Examples' sections; headers make it scannable. It is somewhat long because the operation-key dictionary is enumerated, which the output schema arguably already covers, so a small amount of redundancy keeps it from a 5.

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 five-mode validation tool with a full output schema and read-only annotations, the description covers purpose, all operations, failure handling, and usage examples. An agent has everything needed to select the right operation and construct a correct call.

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?

The per-operation result mapping and the two examples clarify that 'compare' requires path_a/path_b while other operations use 'path', adding real meaning beyond the 75%-covered schema. The schema descriptions still carry some of the load (e.g. 'Ignored for compare'), so this is helpful rather than fully self-sufficient.

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 ('Audit PDF quality and compliance') and enumerates the five concrete check categories (PDF/A, structure, accessibility, integrity, comparison). This is far more than a restatement of the name. It stops short of distinguishing itself from the sibling pdf_analyze, which likely overlaps in scope, so it does not earn a 5.

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 enumerated operations imply what each mode is for, and the example for 'compare' shows when path_a/path_b are needed, giving implicit usage guidance. However, there is no explicit when-to-use / when-not-to-use statement and no routing away from siblings like pdf_analyze. Adequate but with a clear gap.

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