List silence gaps found around a chapter's recorded boundary

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description reinforces this with 'Does not change anything.' It adds further behavioral context by describing the re-scan behavior, the JSON return schema, and the error condition when the chapter hasn't been aligned yet. This goes well beyond what the annotations alone convey.

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 organized into purpose, args, returns, and error handling. Each section earns its place: the purpose is front-loaded, the parameter guidance is concise, the return schema is compact, and the error condition is actionable. There is no filler or repetition of annotation fields.

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 read-only inspection tool with nested parameters and an output schema, the description covers the full call context: when to use it, what it does, what parameters mean, what the return JSON looks like, and what error to expect. The agent has everything needed to invoke it correctly and interpret results.

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?

The schema coverage signal is 0%, so the description must carry parameter meaning. It lists all parameters and adds tuning guidance ('widen noise_db (e.g. -25) for a loud passage, shorten min_silence to catch briefer pauses') that goes beyond the schema's property descriptions. It does not restate every default or range, but the schema already supplies those, and the description adds practical semantics.

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 uses a specific verb-resource pair ('Re-scan the audio around a chapter's currently recorded boundary and list every silence gap found'), which clearly states what the tool does. It also differentiates itself from sibling tools by naming follow-up tools like audiobook_render_boundary_waveform and audiobook_patch_chapter_boundary, so an agent can distinguish it without opening other 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?

The description explicitly says when this tool is most useful: for chapters that showed up in fallback_chapters or word_count_warnings from audiobook_get_status. It also tells the agent what to check first (audiobook_get_status's alignment field) and what to do next, providing clear selection and sequencing guidance relative to siblings.

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