Manually override a chapter's detected boundary

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

The description goes well beyond the destructiveHint annotation by specifying exactly what gets invalidated: encoded segments, the assembled file, and delivery, and that regeneration occurs on the next audiobook_continue_conversion or audiobook_run_until_done call. It also reassures that other chapters are unaffected and documents error conditions, providing a complete safety picture.

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 well-structured with distinct paragraphs for purpose, consequences, parameters, and return value. It is longer than necessary, but the length is justified by the destructive invalidation semantics and the need to clarify next steps. The key decision-relevant information is front-loaded.

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 essential context: trigger conditions, the destructive invalidation scope, how to obtain the corrected boundary, the exact return schema including the invalidated list and stage_now field, and what to call next. Given the tool's complexity and the presence of an output schema, no critical information 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?

Though schema coverage is reported as 0%, the description compensates by explaining each parameter in the Args block: job_id, 1-based chapter_index, and new_start_seconds as the corrected boundary typically derived from audiobook_inspect_chapter_boundary. This adds meaningful context beyond the raw schema, though it stops short of describing valid ranges or format details.

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 is explicit: it says 'Manually fix a chapter boundary that landed in the wrong place' and clarifies it 'overwrites the recorded boundary for chapter_index'. It also differentiates from sibling tools like audiobook_inspect_chapter_boundary and audiobook_render_boundary_waveform by focusing on the patching/override action rather than inspection or rendering.

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 states when to use the tool: when boundaries are surfaced via fallback_chapters, low_confidence_chapters, or word_count_warnings. It also provides an explicit workflow reference by noting the corrected boundary is typically the midpoint of a gap from audiobook_inspect_chapter_boundary, and explains that this is cheaper than restarting the job because adjacent chapters remain untouched.

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