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

The description adds substantial behavioral detail beyond the annotations: by default it only forgets the job_id, leaves out_dir/.state/<job_id> intact, and with delete_files=True deletes only the scratch directory. It explicitly states that original mp3/epub and already-delivered files in out_dir are never touched, even when delete_files is true. This aligns with and enriches the destructiveHint=true annotation without contradicting it.

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 a concise prose section followed by Args and Returns sections. It is front-loaded with the core behavior and adds essential nuances about disk state and delete semantics. It is slightly redundant with the schema (e.g. repeating delete_files semantics), but the added clarity about what is and is not deleted earns its place.

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 fully covers what an agent needs to call this tool correctly: the registry-only default, the disk-deletion behavior, the boundary of what is never touched, the input parameters, and the return format including the error case. With annotations already signaling destructive and idempotent behavior, no important operational context 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?

Context signals indicate 0% schema description coverage, so the description must compensate for parameter meaning. It explains job_id as the registry key and delete_files as controlling whether the working directory is deleted. It also includes the default behavior ('By default this only forgets the job_id') and the exact effect of delete_files=True. The description does not explicitly state that job_id comes from audiobook_start_conversion, but the schema itself does, so this is adequately covered.

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 begins with a specific verb and resource: 'Remove a job from the registry.' It goes beyond the title by clarifying that removal is from the registry only, not necessarily from disk, and it names the related start tool implicitly through the resume behavior. This clearly distinguishes the tool from siblings like audiobook_start_conversion and audiobook_continue_conversion.

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 clearly explains the effect of calling the tool with default settings versus delete_files=True, and gives the important consequence that the same job_id/mp3/epub/out_dir can resume a forgotten job. It does not explicitly name alternatives or say 'use this when...', but the context and behavioral consequences are clear enough for an agent to decide.

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

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

The description goes well beyond the annotations by disclosing checkpointing, safe re-invocation after partial failures, that checkpointed work is never redone, and exact error outcomes including 'unknown_job' and ffmpeg failure behavior. This gives a full behavioral model for a mutating tool.

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 core behavior, then organized into Args, Returns, and Error Handling sections. Every sentence adds necessary operational information without redundancy or filler.

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 invocation, looping behavior, retry semantics, error cases, return-value reference, and parameter constraints. With an output schema available and a clear pointer to audiobook_get_status for the return schema, nothing needed to call the 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 reported at 0%, so the description must carry the parameter explanation. It does: job_id is sourced from audiobook_start_conversion, and time_budget_seconds is given with its operational meaning, range (5-300s), and default of 60.

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 ('Advance'), a clear resource ('a conversion job'), and the bounded-chunk behavior ('Do up to time_budget_seconds of work ... checkpoint to disk, and return'). It also names the stages the job moves through, which distinguishes it from related job-management tools and from audiobook_run_until_done.

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 tells the agent to re-call with the same job_id until 'done' is true, and names audiobook_run_until_done as the automatic-loop alternative. It also gives retry guidance after errors, making when-to-use and how-to-continue unambiguous.

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

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

Annotations already signal destructive and idempotent behavior, and the description reinforces and expands on them by disclosing that metadata is overwritten in place while pixel data is untouched. It also reveals a key guardrail: missing exiftool produces an error rather than a silent skip, and that a JSON copy is stamped into the JPEG Comment so nothing is lost.

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 organized into action, side effects, dependency, arguments, and return value sections, with no filler. Every sentence earns its place, especially the exiftool guardrail and the JSON Comment fallback explanation.

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 mutating tool with a nested input schema, the description covers prerequisites, failure modes, destructive behavior, dry-run semantics, and the exact return shape. Nothing an agent needs to call the tool safely and 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?

Even though top-level schema description coverage is 0%, the description compensates by explaining the role of each argument, including that dry_run returns the command without writing. It also connects image_path and metadata to sibling tool outputs, which the schema alone does not convey, though it does not enumerate every nested BookMetadataInput field.

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 action and resource: writing a book metadata record into an existing image file's EXIF/XMP/IPTC tags via exiftool. It also distinguishes the tool from siblings by noting image_path typically comes from audiobook_fetch_cover_image and metadata from audiobook_lookup_book_metadata.

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 workflow context: image_path is typically the output of audiobook_fetch_cover_image and metadata is expected from audiobook_lookup_book_metadata's record. It also explains dry_run's purpose, though it does not explicitly name alternatives or state when not to use the tool.

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

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

Annotations indicate readOnlyHint=false, destructiveHint=false, and idempotentHint=false. The description goes beyond to explain overwrite behavior (errors by default, matching source skill's 'ask before overwriting'). It also discloses that out_dir is created if missing and that network failures surface the reason. This is rich context beyond the annotations. However, the description doesn't explicitly state that the file is written to disk in a non-idempotent way (repeated calls error unless overwrite=true), but that's already implied by fetch and overwrite semantics.

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 two paragraphs plus structured sections, but it is front-loaded with the most critical information (picking by dimensions, naming convention). It's compact and each sentence earns its place. Slight redundancy: the 'overwrite' behavior is mentioned in the args list and Error Handling, but that's minor.

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?

Given the output schema exists, the description needn't list return fields, but it does anyway. It covers error scenarios (network failures, existing file without overwrite). It also explains naming convention fully. For a simple download tool, nothing is missing: how to call, what happens, and what to expect on output.

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 description coverage is 0%, so the description must compensate. It does: each parameter's purpose is described (cover_url for download, out_dir for destination, title/author for filename, overwrite for conflict handling). The description also adds that title/author are sanitized for the filename, a detail beyond the schema. However, it doesn't explain the film name pattern in detail beyond the example, but the example is enough.

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 ('Download'), the resource ('a specific cover image URL'), and the key distinction from siblings: it picks by measured width/height, not source order. It clearly differentiates from audiobook_lookup_book_metadata, which returns the covers array, and audiobook_embed_cover_metadata, which embeds metadata, avoiding confusion.

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 to use URLs from audiobook_lookup_book_metadata's covers array and warns to pick by measured dimensions. It also clarifies 'when not to use': selecting by source order or URL is incorrect. It implies when to use it (after metadata lookup, before embedding) without naming alternatives, which is sufficient for a downloader.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, but the description adds crucial behavioral context: it is safe to call as often as desired even while other job-affecting calls run, and it provides a detailed explanation of progress semantics (weighted by stage time, not just stage count). It also discloses the error response structure. No contradictions with annotations.

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 lengthy but well-organized into purpose, Args, Returns (with a full JSON schema), and Examples. The return schema is essential given the tool's complex output, and the examples provide practical context. It is front-loaded with the safety note, and every section earns its place, though it could be trimmed slightly without losing clarity.

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 is fully self-contained: it explains the tool's purpose, when to use it, the exact return schema with field meanings, error handling, and even provides usage examples. The tool is complex (multiple stages, weighted progress, various optional fields), and the description covers all necessary details for correct invocation and interpretation. There is no output schema annotation, but the inline schema fully compensates.

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 only parameter is job_id, and the schema already describes it as 'Job id returned by audiobook_start_conversion.' The description repeats this same source information without adding new details. Since schema description coverage is reported as 0% but the schema itself has a clear description, the tool adds minimal extra value beyond the schema. The parameter is simple and self-explanatory, so a baseline of 3 is appropriate.

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 explicitly states 'Read a job's current progress WITHOUT doing any work' which clearly identifies the action and resource, and differentiates from sibling tools like audiobook_continue_conversion and audiobook_run_until_done. It is a specific verb (read) with a clear object (job progress), and the emphasis on being read-only and safe to call often distinguishes it from mutation tools.

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 provides explicit when-to-use scenarios: 'Use when: checking whether a long-running job has finished yet' and 'Use when: deciding whether fallback_chapters/word_count_warnings need...' It also notes it can be called while other conversions are in flight, clarifying it is safe to poll. This gives clear guidance on when to select this tool over alternatives.

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

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.

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

Even with annotations declaring readOnlyHint, idempotentHint, and destructiveHint, the description adds concrete behavioral guarantees: no audio files are touched, no conversion job is created, and it documents both the exact JSON return shape and the 'epub_extract_error' style failure mode. This goes well beyond the annotations.

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 and front-loaded with purpose and usage context, followed by clear Args, Returns, and Error Handling sections. It is slightly long because the full return JSON schema is embedded even though an output schema exists, which costs it a point on conciseness.

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 single-parameter, read-only inspection tool, the description covers the purpose, when to use it, what it returns, and what errors to expect. The presence of an output schema further fills in return details, so nothing needed for correct invocation 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?

The description states that epub_path must be an absolute path to the .epub file, but this mostly repeats the input schema's property description, which already includes an example. With schema coverage listed at 0%, the description partially compensates by naming the requirement, but it adds no extra constraints such as file existence, valid EPUB requirement, or path format edge cases.

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: 'Parse an EPUB and preview the book metadata, chapter list, and cover art'. It also clearly differentiates this tool from conversion tools by stating it works 'WITHOUT touching any audio file or creating a conversion job', making its purpose unambiguous.

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 to use this tool before audiobook_start_conversion to sanity-check chapter detection, and to answer questions like chapter counts without needing an MP3. It does not explicitly contrast itself with audiobook_inspect_chapter_boundary, so it stops short of fully enumerating alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds genuine value on top: persistence path ($AUDIOBOOK_MCP_HOME/registry.json), most-recent-first ordering, and pagination semantics via has_more/next_offset in the return schema. No contradiction with annotations.

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?

Purpose is front-loaded, followed by a cleanly structured Args section and return schema. The return JSON block is verbose but earns its place by defining pagination fields. Some parameter detail overlaps with schema descriptions, but the overall structure is efficient and scannable.

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?

Complete for a read-only listing tool: purpose, persistence location, ordering, all parameters, and full return schema are covered, and annotations carry the safety profile. A minor gap is that it doesn't note the relationship between job_id in results and tools like get_status, but nothing essential to invoking it 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?

Despite the context signal reporting 0% schema coverage, the description documents all three parameters (out_dir exact-match filter, limit 1-100 default 20, offset default 0), adding constraint ranges and defaults beyond the schema's per-property descriptions. The description fully compensates for the coverage signal, though it slightly duplicates what the schema already states.

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?

States a specific verb and resource ('List jobs known to this server') and names the persistence location and ordering (most recent first). This clearly distinguishes it from siblings like audiobook_get_status (single job), audiobook_start_conversion, and audiobook_cancel_conversion (mutations). An agent can tell it apart 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 read-only enumeration purpose is implied, and the distinction from get_status (per-job check) is inferable but never stated. No explicit 'use this when...' guidance or named alternatives/exclusions appear. The ordering and persistence context help, but the tool does not tell the agent when to prefer it over its siblings.

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

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

Annotations already declare readOnlyHint/idempotentHint/openWorldHint, and the description layers substantial extra behavior on top: no scraping/login/CAPTCHA surface, self-throttling between calls, per-source failures landing in 'errors' (Google 429 example), only failing outright on input validation, and cover probing that reports true decoded pixel dimensions. Nothing contradicts the annotations.

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 coherently sectioned (purpose, guardrails, failure mode, args, returns, errors) and front-loaded with the core purpose. Every section adds operational value, though the 'Args' bullet partially restates what the schema's $defs already describe, and the return-format block could arguably live in the output schema.

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 tool with four external sources, six parameters, two reconcile modes, and cover probing, the description is remarkably complete: it covers source enumeration, quota behavior, error semantics, the full JSON return shape for both reconcile modes, and the known failure mode (series volumes). An agent has everything needed to call it correctly.

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?

With schema description coverage reported at 0%, the description carries the parameter-documentation burden and largely delivers: it explains reconcile=True merges sources, include_covers=True probes real pixel dimensions, and emphasizes including the volume number in title to defeat relevance-ranked series mismatches. It does not explicitly walk through author/source/google_api_key, though those are documented in the schema's own $defs, so the compensation is strong but not complete.

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 first sentence names a specific verb ('look up'), a specific resource (book/audiobook metadata and candidate cover images), and enumerates the four source APIs. This clearly distinguishes it from siblings like audiobook_fetch_cover_image (which fetches a concrete cover into a file rather than returning candidates) and the conversion/status/boundary tools.

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 explicit when/when-not guidance: personal research/cataloging use, 'not a bulk data feed', 'don't loop it over long lists of titles', and names the alternative path (a calling agent with its own browser tool may do one manual Tier 2 page visit). It also states the tool's real ceiling when Tier 1 comes up short, so an agent can decide whether to fall back.

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

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.

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

Annotations already declare idempotent and non-destructive behavior; the description adds useful behavioral details: output is a PNG image, rendering is centered on a boundary or override timestamp, and it raises an error when the chapter is not aligned and no override is provided. This is meaningful beyond the annotations, though it could say more about computational cost or why readOnlyHint is false.

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 organized into overview, args, returns, and error handling. Every section adds operational value, including the brief heuristic for interpreting the rendered waveform. There is no redundant filler.

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 rendering tool without an output schema, the description provides the return type, error condition, and intended workflow with sibling tools. It could more deeply explain what 'chapter hasn't been aligned yet' means, but the references to audiobook_inspect_chapter_boundary and audiobook_patch_chapter_boundary provide enough context for an agent to act.

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% at the top level, so the description carries the parameter documentation. It lists all four parameters, explains 1-based chapter indexing, notes the default half-window, and clarifies that center_override_seconds is used for timestamps surfaced by audiobook_inspect_chapter_boundary. Ranges and constraints are left to the schema, but the description gives sufficient invocation 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?

States a specific verb and resource: render a PNG waveform snapshot centered on a chapter boundary. It also includes the interpretive purpose (checking whether a gap is centered) and distinguishes itself from related tools by describing the visual verification workflow.

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?

Explicitly provides when-to-use guidance: use the default recorded boundary, or use center_override_seconds when audiobook_inspect_chapter_boundary surfaces a candidate gap. It also tells the agent what to do if the gap looks off-center or absent: the boundary likely needs audiobook_patch_chapter_boundary.

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

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

Annotations only provide hints like readOnlyHint=false and idempotentHint=false. The description goes further by disclosing the chunked looping mechanism, stop conditions, checkpointing behavior, no-redo guarantee, and error-handling semantics. It adds substantial behavioral context beyond the annotations and does not contradict them.

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 detailed but every sentence earns its place: core behavior, usage guidance, parameter semantics, return value extension, and error handling are each covered in compact, well-organized sections. The most important behavioral facts are 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?

This is a stateful looping operation with non-trivial stopping conditions and error behavior. The description covers how to invoke it, what its bounds are, what the return value includes, how to resume, and how errors are handled. An agent has everything needed to call it correctly.

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?

Despite the schema coverage being 0%, the description thoroughly explains each parameter: job_id's source, chunk_seconds as the internal step size, and max_total_seconds as the overall cap with a clear 'call again to keep going' semantic. This fully compensates for the lack of schema-level 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 states a specific verb and resource: 'Repeatedly advance a job... until it finishes or max_total_seconds elapses.' It also explicitly distinguishes this tool from audiobook_continue_conversion, giving an agent a clear basis for selection without reading 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 explicitly states when to use this tool (convenient one-call driving) and when to prefer the alternative (fine-grained control via audiobook_continue_conversion). It also tells the agent what to do if the job isn't done: call again with the same job_id, since completed work is never redone.

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

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

Annotations already mark idempotentHint=true and readOnlyHint=false, but the description adds substantial behavioral detail beyond that: it explains that re-calling with the same paths resumes instead of duplicating, that force_restart discards progress, that verify_first_chapter falls back to silence heuristics without failing, and that error responses include specific error types. This gives the agent an accurate model of side effects and failure modes.

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 the tool is complex and the length is mostly justified. It is well-structured with clear Args, Returns, and Error Handling sections, and the core purpose and next-step guidance are front-loaded. Minor deductions for the slightly awkward 'see tool description in code' reference and some redundancy with the already-detailed schema field descriptions.

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?

Given the complexity of a multi-stage conversion pipeline, this description is complete: it specifies the exact output JSON shape, the required next actions, error types, resumption semantics, and the behavior of optional settings. An agent has enough context to invoke this tool correctly and decide what to do next.

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 top-level schema coverage is 0%, the description compensates by highlighting the most decision-critical parameters: mp3_path/epub_path must exist, cover_image_path should come from the cover-fetch flow, verify_first_chapter is on by default and explains why, and detect_intro/detect_outro are off by default due to false-positive risk. It does not walk through every parameter, but it directs readers to field descriptions and adds meaningful behavioral context for the important ones.

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 precise verb and resource: it creates/resumes a resumable conversion job for one MP3/M4A + EPUB, then runs only the fast first stage. It explicitly distinguishes itself from the slower alignment/encoding work by naming audiobook_continue_conversion and audiobook_run_until_done, so an agent can tell it apart from sibling tools immediately.

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 explicit next-step routing: call audiobook_continue_conversion or audiobook_run_until_done and loop until 'done' is true. It also explains resumption behavior and the cover-image workflow (audiobook_lookup_book_metadata -> audiobook_fetch_cover_image -> cover_image_path), giving concrete guidance on when and how to use the tool.

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

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.

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

Annotations already cover read-only, idempotent, non-destructive behavior. The description adds useful behavioral detail: it runs ffprobe-based checks, optionally cross-checks source duration, and returns an error object when the file cannot be probed. This goes beyond the annotations without contradicting them.

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 purpose, then cleanly structured into Args and Returns sections. The inline return JSON is somewhat redundant given an output schema exists, but the overall structure is easy to parse and each section serves a clear navigational role.

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 simple verification tool with strong annotations and an output schema, this is complete: it explains what is checked, the role of each parameter, the return shape, and the error behavior. An agent has everything needed to call and interpret this tool correctly.

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 context signal reports 0% schema description coverage, the description itself documents all three parameters with meaningful explanations: m4b_path is the file to verify, source_audio_path enables duration cross-checking, and expected_chapter_count is the comparison target. This compensates well for the reported coverage gap.

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: 'sanity-check a finished M4B' and lists the exact checks performed (chapter count, duration, titles, cover art). It clearly conveys verification/QA rather than status or conversion, though it does not explicitly name or differentiate sibling tools.

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 says to run this 'before handing a result back', giving a clear temporal and workflow context for when to call it. It does not name alternatives or state when not to use it, but the purpose is specific enough that usage is well implied.

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