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

Beyond the annotations, the description discloses that pages look identical after processing, that already-searchable pages are skipped, and that the operation uses ocrmypdf (Tesseract + Ghostscript). It could be slightly more explicit about whether a new file is returned or the input is modified, but the main behavioral traits are well covered.

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 front-loaded with the tool's purpose and mechanism, then adds behavioral safety details and an alternative routing. Each clause contributes distinct value, and the metadata tags are compact rather than repetitive.

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 two-parameter tool with no output schema, the description covers the operation, visual result, mixed-document safety, alternative tool, dependency, and plan requirement. Nothing essential for an agent to select and invoke this tool correctly 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 100%, and the schema already explains both parameters: file is a 'Scanned PDF to make searchable' and lang includes format, examples, and a server-pack caveat. The tool description adds little parameter-level meaning beyond the schema, 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 states a specific verb and resource: making a scanned PDF searchable by adding an invisible OCR text layer over page images. It also explains the observable effect—text becomes findable, copyable, and indexable—and explicitly positions it against pdf_to_text, so an agent can distinguish it from siblings without opening schemas.

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?

It gives clear when-to-use guidance: scanned PDFs that need a searchable text layer. It also gives a when-not-to-use condition and names the correct alternative: 'to EXTRACT text that already exists, use pdf_to_text instead.' The note that already-searchable pages are skipped adds practical guidance for mixed documents.

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