ocr_book

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

With no annotations, the description carries the full burden and does so admirably. It discloses the complete processing pipeline (detection, rendering, provider transcription, cache, full-text index, optional pandoc re-typeset EPUB attachment), the side effect on the book record, and the no-op condition for books with a text layer. It also surfaces relevant configuration variables, giving the agent insight into provider and model dependencies.

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 structured with a lead purpose sentence, a compact pipeline outline, a configuration list, and an Args section. Each section earns its place and the main action is front-loaded. The configuration block is somewhat lengthy for an agent that may not need these details, but it remains concise enough given the tool's complexity.

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 three-parameter tool with no schema descriptions, the description covers the parameters, the operation pipeline, side effects, and the no-op condition. An output schema exists, so return values do not need explanation. The only notable gap is explicit routing to batch alternatives, but that is a usage-guidance nuance rather than a completeness blocker. Overall, the definition is sufficiently complete for correct invocation.

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%, so the description must compensate, and it does. Each parameter is explicitly explained: book_id identifies the PDF to OCR, typeset controls pandoc re-typesetting, and import_format controls whether the EPUB is attached. Defaults are also noted, fully bridging the schema's lack of descriptions.

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 and resource: 'OCR a scanned PDF via the configured cloud provider and index the text.' This clearly identifies the operation and distinguishes it from siblings like detect_scanned_books, which only detects, and ocr_scanned_books, which implies batch processing. The singular 'book_id' argument further anchors it as a per-book tool.

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 establishes clear context: the tool targets a single scanned PDF book and leaves books with a usable text layer untouched. However, it never explicitly names alternatives like ocr_scanned_books for batch OCR or build_index for indexing-only operations. The usage guidance is implied by the singular argument and pipeline, but not stated as when-to-use versus alternatives.

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