ocr_pdf

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

Annotations already cover safety (destructiveHint=false, openWorldHint=true, readOnlyHint=false), and the description adds nothing beyond deprecation status — no mention that output='pdf' writes a file to disk, no indication of processing cost/latency, and no behavior detail at all. For a tool flagged openWorldHint with write side effects, that is a real gap.

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?

Two short sentences with zero waste; the identity statement comes first and the actionable routing instruction second. Nothing to trim.

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 deprecated alias with a fully described schema, annotations, and an output schema, the description says what an agent needs to decide: same as ocr_file, use that instead. It would be complete at 5 only if it implied the fallback condition under which the alias should still be called.

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% — path, output, and output_path are each documented in the schema, including the enum meanings and the overwrite warning. The description adds no parameter meaning of its own, so the baseline 3 applies.

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 never states a verb+resource — it defines the tool only by identity ("the same tool as ocr_file"), leaving the actual function (OCR on PDFs/images) to be inferred from the name and the sibling tool. That inference is straightforward, but an agent must look elsewhere to learn what the tool does.

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?

"Prefer ocr_file" is explicit routing guidance that names the alternative and the preference, which is exactly what matters for a deprecated alias. It stops short of a 5 because it never says when this tool is ever the correct choice (presumably only when a caller is pinned to the legacy name).

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