validate_captions

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

No annotations are provided, so the description carries the full behavioral burden. It discloses non-mutating behaviors ('Check', 'report', 'flag'), the adjacency/SEQ requirement, and the specific numbering convention checks. It stops short of explicitly stating that the document is not modified, but the verbs strongly imply read-only validation.

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 one dense but efficient compound sentence. Every clause adds a distinct requirement or output detail: caption adjacency, SEQ field, missing-caption reporting, and mixed numbering conventions. It is front-loaded with the main purpose and contains no filler, though it is slightly packed.

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 validation tool with one parameter and an output schema present, the description covers the essential scope, missing-caption reporting, and numbering-flagging behavior. Terms like 'body-level' and 'adjacent' are somewhat implicit, but the output schema likely covers return details, and no critical calling requirement is missing.

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 0%, and the description does not mention file_path at all. However, the single parameter is an unambiguous string named file_path, and the tool's validation context makes its purpose clear enough for an agent to populate it correctly. Minimal but adequate for a single obvious parameter.

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 a specific action ('Check... report... flag') applied to a specific resource (captions for body-level tables and images). It clearly distinguishes this tool from siblings like add_caption and validate_document by naming the exact validation scope and the mixed-numbering detection behavior.

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 when to use the tool: validating caption presence and numbering conventions. It does not explicitly name alternatives or exclusions, but the specificity of the scope makes the intended use inferable without ambiguity.

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