Transcribe the audio right after a chapter boundary

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

Beyond the annotations (idempotentHint, destructiveHint), the description discloses important runtime behavior: dependency requirements, the fact that missing dependencies are 'reported clearly, not silently skipped,' specific error types, and conditions that raise errors (un-aligned chapter without center_override_seconds). This adds substantial information an agent needs.

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 long but well-organized into paragraphs covering purpose, dependencies, parameters, return format, and error handling. It is front-loaded with the core purpose and each section earns its place. It could be slightly tighter, but the structure supports quick comprehension.

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?

The description covers all important operational aspects: what it does, when to use it, dependencies, parameter semantics, return shape, error handling, and interpretation of results. Even with an output schema, the description adds interpretation guidance and prerequisite setup, leaving no critical gap.

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?

Although the schema already contains parameter descriptions, the tool description adds actionable meaning: center_override_seconds is tied to 'a candidate gap surfaced by audiobook_inspect_chapter_boundary', language is clarified as the book's 'actual spoken language', and expected_opening_text is explained as coming from the EPUB's own chapter text. This goes beyond a bare list of parameter names.

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 ('Transcribe a few seconds of audio starting at a chapter's current recorded boundary... via a local whisper.cpp install') and explicitly distinguishes it from a sibling ('a text-based alternative/complement to audiobook_render_boundary_waveform'). An agent can tell exactly what this tool does and how it differs.

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 it ('for judging a low_confidence or fallback boundary'), names the sibling alternative (audiobook_render_boundary_waveform), and explains how the transcript should be interpreted. It does not explicitly state 'when not to use' cases, but the usage context is unambiguous.

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