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

Annotations (readOnlyHint=false, destructiveHint=true) already mark this as a mutating write, and the description's 'Write...' matches — no contradiction. The description adds valuable nuance: timings follow the timeline not the recording, cut words are omitted and counted as words_cut, and override args are not written back so regeneration returns to project styling. It doesn't explicitly state what destructive action occurs (e.g., overwriting an existing output file), leaving a small gap against the destructiveHint.

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?

Three tight paragraphs, purpose front-loaded in the opening sentence. Each paragraph earns its place: core behavior, timing/cut nuance, look/override semantics, and the sidecar-vs-burn exit decision. Dense but efficient with no wasted words.

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 complex 10-parameter tool with an output schema present, the description covers the key decision points an agent needs: what it writes, the timeline-vs-recording timing behavior, cut handling, one-off override semantics, and the sidecar/burn tradeoff. It references related tools (caption_style, caption_view, export) for cross-navigation. The only omission is explicit disclosure of destructive/overwrite behavior.

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 coverage is 100%, so baseline is 3. The description adds meaning beyond the schema: it explains the one-off, not-written-back semantics of the override args and reinforces the burn timing constraint against a render of this timeline. These points complement rather than repeat the schema field 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?

First sentence states a specific verb, resource, and target: 'Write word-timed ASS captions for the current timeline to `output`.' It distinguishes itself from sibling caption tools by explicitly naming caption_style (sets the look) and caption_view (sees it), so an agent can tell this tool apart without opening their 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?

Gives explicit decision guidance: the sidecar .ass is the default exit and stays restylable; `burn` is only correct against a render of THIS timeline, with a direct warning that any other video will misalign. It also tells the agent when not to use the override args ('Leave them unset unless you specifically want a one-off') and clarifies that `export --render` does not burn captions.

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 and destructiveHint=false; the description repeats 'Read-only' but adds no further behavioral traits such as rate limits, auth needs, or side effects. It does describe output composition (probe metadata, playability, re-author record), but that is more output semantics than behavior, and with annotations covering safety, the extra value is limited.

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?

Two sentences with the purpose front-loaded and supporting details following. The second sentence is long but dense and information-bearing; there is no fluff, though it could be slightly tightened.

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 and the tool is a read-only list with no required parameters, the description sufficiently covers what the agent needs to know. It explains the main output categories (clip/card fields and cue counts), though it does not cover when to prefer this over sibling tools, which is already handled in usage guidelines.

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 single parameter `path` is fully documented in the input schema with detailed resolution semantics. The tool description adds nothing about `path`, so per the rule for >80% schema coverage, 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 opens with 'Every asset a cue can point at — clip or card — for an assets pane,' which is a specific verb-resource statement. It clearly distinguishes itself from siblings like list_media by covering both clips and cards and including cue reference counts, so an agent can tell it apart without opening 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 phrase 'the question an assets pane exists to answer' provides clear context for when to use this tool. However, it does not explicitly mention alternatives or state when not to use it, so it stops short of full routing guidance.

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, the description explains that the tool runs self-checks (near_duplicates, suspect_durations, overlaps, repeats), warns that a hit is not a verdict, and cautions about overlaps seams inventing words. This is rich, non-obvious behavioral context that materially helps an agent trust and interpret results.

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 purpose is front-loaded in the first sentence, and the subsequent paragraphs each explain a distinct behavioral check or caveat. The description is longer than minimal, but every sentence adds operational value and there is no fluff.

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 and annotations flag destructive/idempotent behavior, the description is largely complete: it defines input requirements, explains all four diagnostic checks, and warns about interpretation. A small gap is that it does not explicitly state that ingesting replaces any existing transcript, but annotations and the meaning of 'as this clip's transcript' cover it.

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 coverage is 100%, so the baseline is 3, but the description adds meaningful detail: clip_id words become (clip_id, word_index) and are used by every cue, mark, and caption afterward. This explains the downstream impact of the parameter beyond the schema's simple field documentation.

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 states a specific action ('Ingest an existing word-timed whisper JSON') and target ('as this clip's transcript'), clearly distinguishing it from tools like transcribe. It names the exact resource and the ownership outcome in a way an agent can act on.

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 makes clear this tool is for ingesting an already-existing whisper JSON rather than generating one, which implicitly routes an agent away from transcribe. It also gives follow-up guidance ('Use transcript_checks to see all four again later'), but it does not explicitly name alternatives or state when not to use it.

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, the description explains the exact write behavior: a new derived copy is written, the original is always read first, repeated calls never compound gain, and nothing ever raises on scan findings. It also documents per-event withholding versus whole-call refusal, and the behavior of suspect_neighbours and disqualified events.

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 dense but every sentence contributes: it front-loads the core purpose, explains the qualification rule, discloses write behavior, and then distinguishes this tool from siblings. Despite its length, it is efficiently structured with clear paragraphs and no 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?

Given the tool's complexity, the description fully covers the qualification criteria, the no-compound-gain guarantee, the difference from sibling tools, and the reporting behavior for suspect and disqualified events. The output schema handles return value specifics, so nothing essential 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 input schema already covers all parameters with detailed descriptions (100% coverage), so the baseline is 3. The tool description adds value by explaining how db, max_event_seconds, max_gap_seconds, confirm_suspect, and plan work together in the qualification and withholding logic, going beyond individual schema comments.

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: 'Pull down short loud non-speech events instead of cutting them out.' It clearly distinguishes itself from cut_by_transcript/cut_by_time by describing the difference in granularity and failure mode, so an agent can select it correctly.

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 contrasts this tool with cut_by_transcript/cut_by_time, explaining that this is an automatic multi-candidate scan rather than explicit ranges. It also clarifies when plan=True should be preferred and how confirm_suspect gates a specific case.

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 annotations (readOnlyHint false, idempotentHint true), the description discloses behavior richly: it reports without applying by default, keeps existing labels on words it refuses to call, distinguishes 'unmeasurable' from 'ambiguous', and states accuracy figures (~99% on clear speech, chance on overlap). It also explains that margin_db is not a threshold to trust, which is a nuanced behavioral caveat.

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 it is well-structured with bold headings and logical flow: purpose first, then how it differs from alternatives, then parameter explanations, then behavioral caveats. Each sentence earns its place; nothing is redundant. It is appropriately detailed for a complex tool with many edge cases, though it could be tightened slightly.

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 tool's complexity (7 parameters, output schema present, multiple edge cases), the description covers everything an agent needs: the core operation, when to use it, how parameters interact, the difference between ambiguous and unmeasurable, and the apply behavior. The presence of an output schema further reduces the burden of explaining return values. Nothing critical 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 input schema already provides descriptions for all 7 parameters (100% coverage), so the baseline is 3. The description adds significant meaning beyond the schema: it explains streams as ffmpeg audio ordinals in order, labels as names in the same order, margin_db as a reporting floor rather than a decision threshold, and the interplay between apply and existing labels. This extra context lifts the score to 4.

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 crisp, specific verb-resource statement: 'Label each word with the mic that was loudest while it was spoken.' This clearly distinguishes it from transcription tools (transcribe, hear) and from tools that manipulate transcript structure. It also frames the tool as a post-transcription step, which separates it from ASR workflows.

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-to-use and when-not-to-use guidance: it is a single pass over an attached transcript, never a second ASR run, and it warns that transcribing each mic separately is 'measured and dead' with concrete evidence. It also tells the user to transcribe once first, then call this tool. This is actionable and leaves no ambiguity about prerequisites.

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 and destructiveHint=false, so the safety profile is known. The description adds substantial behavioral context beyond those: it explains that `card: true` positions are shown for rhythm and are not choices, that ranking by text similarity was measured and does not work, and that `missing_synopsis` clips will never be chosen. These are non-obvious traits an agent needs to interpret the output correctly, and they do not contradict any annotation.

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-structured: it front-loads the purpose, then explains the workflow, and closes with a priority instruction. Every sentence contributes useful guidance, though the opening line ('The whole b-roll question as data...') is somewhat poetic and less concrete than the rest. It is appropriately sized for the tool's complexity, but slightly verbose.

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 tool has an output schema (not shown but flagged as present), and the description explains exactly what the output contains: clip synopsis, duration, shot positions, narration, hold length, current content, and card positions. It also explains how to act on that output via `cue_add`, and what to fix first. For a read-only briefing tool, this is complete enough for an agent to call it correctly and interpret the result.

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 100%, so the baseline is 3. The description does not add any parameter-specific meaning beyond what the schema already provides for `fps` and `path`. It focuses on the output and usage context, not the parameters, so it neither enhances nor detracts from the schema's documentation.

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 clear statement of what the tool returns: the footage catalogue with clip synopsis and duration, plus shot positions with narration, hold duration, and current content. It explicitly notes that `card: true` positions are shown for rhythm and are not choices, which distinguishes this read-only briefing tool from the write-oriented `cue_add` sibling. The verb 'Returns' and the specific resource make the purpose unmistakable.

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 usage direction: it states this is the half that reads the brief, and that choosing belongs to the user via `cue_add`. It also warns that ranking by text similarity does not work, guiding the agent away from a common but flawed heuristic, and instructs to fix `missing_synopsis` first because such clips are invisible to reasoning. This is clear when-to-use and when-not-to-use guidance.

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, and destructiveHint false, and the description adds meaningful behavioral detail beyond that: the exact mapping algorithm, asset resolution rules, shot extension to the next cue and final frame, refusal on cut cues, and the subtle fps/timebase default behavior. This is rich, non-contradictory context.

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 a one-line summary, followed by concise technical detail and a parameter note. Each sentence adds value; there is no padding or repetition of obvious annotation facts.

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 annotations, full schema descriptions, and presence of an output schema, the description covers the critical behavior, failure mode, how shots are ended, asset resolution, and fps selection. An agent has everything needed to select and invoke this tool correctly without additional inference.

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 input schema has 100% description coverage for both fps and path, so the baseline is 3. The description reinforces the fps behavior and timebase nuance, but that information already appears in the schema description; no new semantic detail is added for path or beyond what the schema provides.

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 clearly states a specific verb and resource: 'Project the cue table into contiguous shots over the current edit.' It explains the core operation in detail and differentiates itself from generic edit operations, though it does not explicitly name or contrast sibling tools such as shot_sheet or cut_by_transcript.

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?

Clear context is provided: the tool projects cues into shots, and it will refuse if a cue's word was cut, with a directive to fix it via cue_rm/cue_add first. It also gives practical guidance on the fps parameter for export alignment, but it does not explicitly state when to prefer this tool over alternatives or list exclusions.

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 flag `destructiveHint` and `idempotentHint`; the description goes beyond by detailing the routing consequence (override forces MLT writer), the cropping behavior (aspect change crops to fill, not pillarbox), and the side‑effect on caption quoting. It even mentions the `plan` flag as a safer alternative, which is exactly the kind of operational detail an agent needs. 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?

The description is moderately long but every sentence is packed with unique, actionable information. It is front‑loaded with the core purpose, then flows naturally into call patterns, behavioral consequences, and parameter details. There is no fluff or redundancy.

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 state‑changing tool with subtle rendering implications, the description covers everything: what it does, when to call it, what happens on override (routing, cropping), how to preview safely, and which sibling to use for fine‑grained adjustments. The presence of an output schema and rich parameter descriptions further reduces any missing context. Nothing essential is left out.

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 input schema already covers all four parameters with detailed descriptions (100% coverage). The main description adds extra meaning for `size` (even edges, vertical example) and `reset` (drops override), and explains the consequences of setting a size (routing, cropping). This goes beyond the schema, so a 4 is warranted; it stops short of a 5 because the schema already does much of the heavy lifting.

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-resource pairing ('Read or change the shape this project renders at') and goes on to explain exactly what the canvas is, how it relates to project state and rendering, and why it matters (caption quoting consistency). It also names a related tool (reframe) for a specific sub‑task, which distinguishes it from siblings without needing to list them.

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 call patterns: reading with no `size`, resetting with `reset`, and using `plan` to preview. It also tells the agent when to delegate to `reframe` for changing which part of a crop is kept, effectively stating when not to use this tool. This is model guidance.

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 this as destructive and idempotent, and the description aligns: it says changes persist ('restyle survives every later cut') and that `reset` drops overrides. It adds context beyond annotations by explaining how colour values are resolved (ASS quoting) and that only overrides are stored, giving an agent a clear mental model of the state mutation. Slight gap: it doesn't explicitly state that the call is idempotent, but the description implies 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 long (roughly 300 words) but well-structured with clear paragraphs. It front-loads the purpose and usage, then details colour formats, then plan/view. Every sentence contributes to the agent's decision-making. It could arguably be tighter, but for a tool with 21 parameters and a destructive mutation, the length is justified.

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 tool's complexity—21 parameters, destructive behavior, and interaction with sibling tools—the description is remarkably complete. It covers read vs write semantics, persistence, colour handling, preset/override relationships, and points to `caption_view` for verification. An agent has all the information needed to call it correctly without additional assumptions. The output schema exists, so return-value details are not required in the description.

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 input schema has 100% parameter coverage with per-field descriptions, but the tool description goes far beyond: it explains the preset options ('clean', 'karaoke', 'boxed'), how overrides work, colour format options, the relationship between `text` and `highlight` with karaoke, and the meaning of `plan` and `reset`. This adds substantial semantic value that the schema alone does not provide, especially for the 21 parameters.

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 'Read or change the caption look this project keeps,' a specific verb pair and resource. It distinguishes itself from the sibling caption_view ('Use caption_view to see the result on the actual timeline') and explains that captions are derived from this style, so an agent immediately knows this tool is the source of truth for caption appearance, not a renderer.

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?

Explicit usage rules are given: 'Call it with no arguments to read the current look and learn the field names; any argument sets that field and leaves the others alone.' It also explains the `reset` and `preset` interaction, and directs to `plan` for dry-run validation and `caption_view` for visual confirmation. No ambiguity about when to use it.

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, destructiveHint=false, and idempotentHint=true. The description adds beyond this by explaining that it reports rather than refuses (empty `cues` and a `cues_error` for missing transcripts) and describes the pagination fields (`cues_total`, `cues_next`). It also notes that cues are grouped by the project's break rules. This is useful behavioral context not covered by 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 compact and each sentence serves a purpose. It front-loads the core purpose, then usage, then error behavior, then pagination. No fluff; every line contributes to accurate tool selection and invocation.

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 that an output schema exists, the description still explains the important return fields (cues, cues_error, cues_total, cues_next) and how to navigate them. It addresses edge cases (missing transcript) and recommends an alternative for time-based lookup. For a read-only tool, this is complete.

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 100%, so the baseline is 3. The description adds meaning by explaining the relationship between `first`, `limit`, and `cues_next` (a window of `limit` from `first`), and suggests using `locate` instead of paging. It also clarifies that `cues` is a window, which goes beyond the individual parameter 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 purpose: it returns the captions a timeline would produce along with the active style, and explicitly contrasts itself with add_captions (which writes a file). This clearly distinguishes it from siblings like caption_style or cue_ls. The phrase 'The captions this timeline would produce, and the style in force' is a precise verb-resource pairing.

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: 'this is how to check a restyle, or read back what a caption actually says at some moment, before committing a file to it.' It also names the alternative (add_captions) that writes, and recommends using `locate` for finding a cue at a moment rather than paging. This gives clear when-to and when-not-to guidance.

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 carry readOnlyHint=false, destructiveHint=true, idempotentHint=true. The description adds meaningful behavioral context: the overwrite refusal guard, the side effect of writing SVG+PNG to assets/cards, the non-wrapping newline behavior, and the font-substitution fallback. 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?

Front-loaded with a one-line summary, then structured paragraphs for storage, slots, size, and error/fallback behavior. Bold warning for width/height. Every sentence earns its place; no 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?

Covers purpose, storage, parameter semantics, destructive-guard behavior, and result-reading (font_warnings). Good cross-references to card_render and card_templates. Given the output schema exists, nothing an agent needs to call 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?

Schema coverage is 100%, so the schema already documents all parameters. The description adds marginal nuance (e.g., 'nothing wraps automatically' and the pillarboxing warning for width/height), but these largely duplicate the schema text. Baseline 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?

States a specific verb+resource: 'Make a card from a template: fill its slots, write the SVG, render it.' Distinguishes from card_render and card_reauthor by naming the rendering pipeline and the storage location, so an agent can tell it apart from siblings.

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 names alternatives: 're-rendered with card_render rather than redrawn' and 'card_templates lists them with their slots.' Gives concrete conditions: leave width/height unset unless you need a different size, and read font_warnings in the result. This is clear when-to-use and when-not-to-use guidance.

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 this as destructive and idempotent; the description adds substantial behavioral detail: it sweeps all recorded cards or missing files, redraws a named card, leaves unrecorded cards untouched, and writes nothing in `plan` mode. No contradiction with 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 organized into tight paragraphs: purpose, usage context, and result interpretation. Every sentence contributes either a behavioral fact, a routing rule, or an edge case, with no 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?

Given full schema coverage, an output schema, and safety annotations, the description covers the trigger context, the sibling distinction, the unrecorded-card failure mode, and the safe planning path. 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?

The input schema already describes all three parameters at 100% coverage, including the sweep-vs-named behavior and the `plan` write-nothing behavior. The description mostly restates this rather than adding new parameter-level meaning, so the baseline 3 applies.

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: 'Draw recorded cards again at the shape this project renders at now.' It clearly distinguishes this from siblings like canvas and card_new by explaining exactly what makes card_reauthor necessary.

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 says to reach for this after `canvas`, explains why a canvas change cannot fix cards, and names `card_new` with `overwrite` as the alternative for unrecorded cards. It also recommends `plan` for dry-run behavior, giving an agent clear decision rules.

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 state idempotent and destructive hints, but the description goes far beyond them: it explains that both source and output are kept, that rendering at a different scale draws rather than resamples, that fit behavior shrinks one axis on aspect mismatch, and critically warns about font substitution producing pixel-identical renders that cannot be caught downstream. This is exactly the kind of behavioral context an agent needs and that annotations do not provide.

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 longer than a couple of sentences, but every paragraph earns its place: purpose, workflow, size semantics, and font warnings are each distinct and necessary. It is front-loaded with the core purpose and organized by concern, with no filler or redundancy beyond a minor overlap with schema 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 tool's moderate complexity, a full output schema, and strong annotations, the description is remarkably complete. It covers the entire lifecycle (author → render → use), explains the size constraints with real behavioral detail, and preempts the hardest-to-detect failure mode (font substitution). An agent can call this tool correctly with no additional knowledge.

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 coverage is 100% and the schema already documents width/height pairing and omission behavior. The description adds genuine value by explaining the non-resampling render behavior, the fit-not-distort constraint, and the consequence of aspect ratio mismatch. That extra semantic depth moves it above the baseline of 3.

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: 'Rasterise `assets/cards/<name>.svg` into the PNG `card:<name>` shows.' This clearly differentiates it from sibling tools like card_new or card_templates, which create or edit card definitions rather than render them. The purpose is unambiguous and immediately front-loaded.

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: author the SVG under assets/cards, then render it to make it usable; it also explains that the PNG is what a card: cue resolves to. It does not explicitly name alternatives or provide when-not-to-use guidance, but the implied usage is strong and sufficient for an agent to decide when this tool is the right one.

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, and destructiveHint false. The description adds significant behavioral context: it reads from the actual rendered PNG on disk (not manifest slots), it is report-only and does not block renders, it has no default floor for thresholds (with historical justification), and it refuses cards without a PNG. This goes well beyond the annotations and clearly sets expectations for an agent.

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 purpose in the first sentence. The SCENE_THRESHOLD digression in the second sentence adds context but is tangential to immediate usage. The rest is concise and relevant. Overall it is efficient, though slightly verbose with the historical note.

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, idempotent measurement tool with an output schema (not shown), the description covers all necessary operational details: prerequisites (PNG must exist), valid platform sources, the read-from-disk behavior, and refusal conditions. Nothing essential is missing for an agent to call this 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?

Schema coverage is 100%, so the baseline is 3. The main description largely repeats what the schema property descriptions already say for 'card' and 'platform' (e.g., reading from PNG, enumerating zones). It adds a minor nuance about SCENE_THRESHOLD history, but that is behavioral, not parameter-specific. No new parameter meaning is introduced beyond the schema, so a 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 opens with a clear, specific verb-resource pair: 'Measure a rendered card's ink in and around a platform's reserved band.' It distinguishes itself from siblings by being a pure measurement/report operation, and it names related tools (card_new, card_render, pack_show) that support its prerequisites. This leaves no ambiguity about what the tool does.

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 explains when the tool refuses to run (no PNG yet, unknown platform) and implies the workflow: render first via card_new/card_render. It also references pack_show to discover valid platforms. However, it does not explicitly contrast itself with alternative measurement tools (e.g., reframe_coverage), so the 'when to use this vs. alternatives' guidance is implicit rather than explicit.

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 readOnly, idempotent, and non-destructive behavior, so the description only needs to add context beyond that. It explains the returned structure (slots with purpose, required, defaults) and hints at response size ('the whole table is long'). This adds value without contradicting 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 moderately sized, front-loads the core purpose, and uses separate sentences for distinct points. It avoids redundancy with the schema, though it could be tightened by merging some sentences. Overall, it's efficient and well-ordered.

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 tool has a single optional parameter, a clear schema, rich annotations, and an output schema. The description explains what the tool returns, how to use it, and its relationship to card_new. Nothing an agent needs to invoke it correctly is missing, even without seeing the output schema.

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 already describes the `name` parameter with 100% coverage, including the default and effect. The description adds a usage pattern—'call it with no name to choose one, then with name to read only that template's slots'—which clarifies the intended sequence and helps the agent decide how to use the parameter.

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 explicitly states the tool's purpose: it returns the card templates and the slots each takes. It differentiates from siblings by positioning itself as a prerequisite to card_new ('Read this before card_new'). This is a specific verb+resource with clear scope.

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 gives explicit usage instructions: call with no `name` to choose one, then with `name` to read a specific template's slots. It also tells the agent when to use it relative to card_new ('Read this before card_new'), making the selection obvious.

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 'Read-only.' It goes well beyond the annotations by explaining precisely how the comparison is computed, what fields appear ('timeline.removed', 'timeline.added', 'manifest.keys'), how edge cases like reorders and sub-50 ms slivers are represented, and that lists past 40 entries are truncated with `_count`s. This gives an agent a clear model of the tool's behavior and output 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 dense but every sentence contributes meaningful behavioral or output-semantic detail. It is front-loaded with the core purpose and read-only guarantee, then systematically explains output structure with concrete examples. Its length is justified by the complexity of the output, though it could be slightly more scannable with explicit field lists.

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 tool's complexity, the detailed input schemas, the annotations, and the presence of an output schema, the description is remarkably complete. It covers what the tool does, how it behaves on edge cases, what the output fields mean, truncation behavior, and the meaning of `unchanged: true`. An agent has enough context to invoke it correctly and interpret its 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?

Schema description coverage is 100%, with both `path` and `steps` already documented in detail. The tool description references `steps` in the opening sentence but adds no parameter semantics beyond what the schema provides naturally, so the 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 opens with a precise statement of what the tool computes: 'What the last `steps` mutations did — what `undo` that many times would roll back.' It then states the concrete mechanism, 'Compares the snapshot every mutation already leaves against the live project,' which clearly identifies the verb and resource. The 'Read-only' tag and the contrast with `undo` distinguish it from the sibling tool that actually performs the rollback.

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 the tool: to inspect what recent mutations changed and to preview what an undo would revert, without actually undoing. It does not explicitly name alternative tools or state exclusion conditions, but the 'what undo would roll back' phrasing and 'Read-only' marker make the use case reasonably 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?

Even though annotations already declare readOnly/idempotent/non-destructive, the description adds important behavioral detail: a run is only 'explained' as the known tail defect when it is at the tail AND the frame delta matches exactly; any black run inside the picture is always a real defect. This is substantive decision logic beyond what annotations reveal.

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 compact and front-loaded: the core purpose appears in the first sentence, followed by the key usage constraint and the classification rule. Every sentence adds value and none are wasted.

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?

With annotations covering safety, an output schema present, and the input schema fully documented, the description supplies the remaining essential context: required target, the invariant classification logic, and the reference to check_frames. An agent has everything needed to decide when and how to call 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?

Schema description coverage is 100%, so the schema already documents every parameter. The description repeats the target-required rationale that already appears in the schema's target property, adding no meaning beyond that. Other parameters are left entirely to the schema, which is acceptable but not enhanced.

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: 'Scan a render for black stretches' and states the two possible verdicts (known kdenlive-export tail frame vs genuine defect). It distinguishes itself from sibling check_frames by name and by the absent no-target mode, so an agent can tell them apart without inspecting 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 says `target` is required and contrasts with check_frames' cheap no-target mode, giving a clear condition for using this tool. It does not enumerate broader when-to-use vs when-not-to-use scenarios, but the target requirement and the classification rule provide solid contextual guidance.

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 though annotations already declare the tool read-only and idempotent, the description adds substantial behavioral context: how to read the output (`agrees` first, then `delta`), what a non-zero delta implies, that `agrees` is null rather than false for audio-only renders, and when `notes` will explain a mismatch. This goes beyond what the annotations provide and significantly helps the agent interpret results.

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 dense but every sentence earns its place: purpose, positioning relative to `verify`, best timing, target forms, output-field reading order, edge case, and fps caveat. The main purpose is front-loaded, and the length is appropriate for 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?

Given the annotations, full schema coverage, and the presence of an output schema, the description is complete. It covers the key behavioral edge cases an agent needs to call and interpret the tool correctly, and it names the relevant sibling alternative. Nothing essential appears 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 coverage is 100%, so the schema already documents all three parameters well. The description adds extra value by explaining the tooling for targets ('put to `melt -consumer xml`', 'counted with ffprobe') and reinforcing the `fps` matching constraint. It does not add much about `path`, but the schema's own description for `path` is already exhaustive.

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: 'Check an export's frame count against what the timeline says it should be.' It also distinguishes itself from the sibling `verify` by explicitly positioning itself as the picture-side counterpart. An agent can immediately tell what this tool does and how it differs from nearby 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 clear when-to-use guidance: run it before rendering, and explains the target alternatives (NLE project vs finished render) and what omitting `target` does. It names the sibling `verify` as the audio-side alternative and says this tool covers the picture side. These explicit conditions leave little to inference.

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 explains the refusal behavior in detail: it will refuse when any dependency exists and will 'name every reason'. It also adds an important safety boundary not implied by the raw destructive annotation: 'The media on disk is never touched either way'. This materially improves an agent's understanding of the tool's side effects 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 front-loaded with the core purpose, then compacts all refusal conditions and alternative tools into a second dense but scannable block. Every clause earns its place: no filler words, no repeated schema information. The code formatting and named alternatives make the long conditional list easy to parse.

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 destructive, dependency-sensitive unregistration tool, the description covers the intended use window, every known blocking state, how to clear those blocks, the alternative undo route, and the disk-safety guarantee. Since an output schema exists, return-value documentation is not required from the description. An agent has enough operational information to decide when and how to call 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?

Schema coverage is 100%, so `clip_id` and `path` are already fully described in the input schema. The description contributes the operational context that clip_id refers to an import_media-registered clip and that media on disk is never touched, but it does not need to re-document parameter formats. A baseline of 3 is appropriate because the schema carries the parameter documentation burden.

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: 'Un-register a clip `import_media` added', which clearly identifies the tool as the inverse of import_media. The scope is narrowed with 'when nothing depends on it yet' and the disk-safety line prevents confusion with media-deleting operations. This distinguishes it from the many sibling removal tools such as cue_rm and hold_rm.

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 an explicit when-to-use condition: only when nothing depends on the clip yet. It then lists the dependency states that cause refusal and names the exact alternatives (`cue_rm`, `hold_rm`, `unspoken_rm`, `music reset=True`, `proofcut undo`, or `undo`) to use instead. This is unusually clear routing between the tool and its fallbacks.

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, the description discloses exactly what reset destroys (the role, back to undeclared), that setting the role is additive and not a schema bump, and that downstream tools are unaffected. This is substantial behavioral context that prevents an agent from mispredicting side effects.

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 purpose and then organizes modes and side-effect clarifications clearly. It is somewhat repetitive with the role parameter description (e.g., 'assets pane's grouping' appears in both), so it is not maximally concise, but every paragraph 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?

For a tool with 4 parameters angled semantics, the description covers all invocation modes, the allowed values, the reset behavior, and the key non-effects on sibling tools. The output schema is present, so the lack of explicit return-value detail is acceptable.

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 coverage is 100% and the schema already documents each parameter richlyging. The description adds interaction semantics between role and reset, clarifies the read mode, and names the allowed values with the ops.CLIP_ROLES constant, which goes slightly beyond the schema's individual property 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-resource pair ('Read or set a clip's import role') and precisely defines the two possible values, voiceover vs footage. It also distinguishes this tool from likely siblings by explicitly stating it has no effect on transcribe/attach_transcript or describe.

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?

Call modes are explicit: no role and no reset reads, role sets, reset clears. The description also gives clear when-not guidance by explaining that transcribe/describe do not read this field and that its purpose is purely the assets pane's grouping.

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 safety, but the description adds valuable edge-case behavior: returns bytes rather than a path, audio-only clips yield frames:[] without refusal, and boxes without magick return a sheet_error. It also discloses the cache origin (thumbnail()) and that no new cache/manifest/route is created.

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 longer than average but front-loaded with a bolded purpose, and all parts serve a function: the anecdote illustrates the failure mode, and the middle paragraphs explain cache/bytes and edge cases. It could be tightened, but it's structured and not bloated.

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?

Without an output schema, the description must explain return behavior, and it does: montage as bytes, audio-only returns empty frames, and missing magick yields sheet_error. It also covers integration with import_media and thumbnail cache, which is enough for an agent to invoke 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?

Input schema covers all four parameters with detailed descriptions, so baseline is 3. The tool description restates defaults ('Ten seconds at 1.5s spacing by default') but adds little meaning beyond that; no parameter is explained more deeply than the schema already does.

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: 'Look at a clip's own head — the first look, as an image.' It also brands it as 'The sheet to call before cueing anything to a clip you have not seen,' which clearly differentiates it from sibling tools like thumbnail or check_frames by its role in the 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?

The description gives explicit when-to-use guidance: 'The sheet to call before cueing anything to a clip you have not seen' and 'call it to see them, to look further than ten seconds, or to redraw after a re-import.' It does not explicitly name alternatives or list when-not-to-use, but the context is 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 beyond the annotations. It explains the idempotency behavior in detail: 'a deliberate rhyme, never re-reported every run' and the fingerprint mechanism: 'Stores a fingerprint of the finding's own numbers; a later run whose recomputed fingerprint disagrees means the shot moved under the mark, and the finding is reported again rather than trusted blindly.' This discloses a complex behavioral trait that the idempotentHint annotation only hints at, providing crucial context for the agent to understand side effects and constraints.

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: it opens with the core purpose in a clear, memorable line, then explains the addressing mechanism and the fingerprint behavior, and ends with usage guidance. It is concise, with no fluff, and each sentence adds value. The key constraint is front-loaded (acknowledge once), which is helpful for the agent's quick understanding.

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 complete for a tool of this complexity. It has an output schema (not shown but indicated) which likely explains the return value, so that's covered. It addresses the main edge cases: the fingerprint mismatch scenario and the refusal when no finding exists. It also provides the prerequisite of running continuity_check. Given the availability of annotations (idempotentHint, destructiveHint=false) and a rich schema, the description provides all necessary behavioral and usage context an agent needs to invoke 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?

The input schema already has 100% coverage with detailed descriptions for each parameter, including what values are valid (e.g., kind enum values). The description adds some context about how these parameters combine to form the finding's address: 'Addressed the way a cue is (`clip_id`, `word_index`), plus `kind`, since one shot can carry more than one finding.' This reinforces the relationship but doesn't add substantial new semantics beyond the schema. So it's a baseline 3, as the schema does the heavy lifting.

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 clearly states the tool's purpose: to acknowledge one continuity finding exactly once, preventing re-reporting. It specifies the resource (a continuity finding identified by clip_id, word_index, and kind) and the action (acknowledge). This distinguishes it from siblings like continuity_check (which reports findings) and continuity_reject (likely a different disposition), making it clear that this tool is for accepting/handling a specific finding.

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 guidance on when to use this tool: 'Refuses when no finding of `kind` currently sits at that cue — `continuity_check` first, then accept what it found.' This tells the agent to run continuity_check before accepting, and implies it should not be used if no matching finding exists. It also implies that this is the tool for accepting a finding, as opposed to rejecting (continuity_reject) or listing (continuity_ls). This is clear and actionable.

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 annotations that already declare readOnly/idempotent/non-destructive, the description discloses important behaviors: accepted findings can be marked accepted_stale, the cold open is walked as a pseudo-shot, overruns are structurally impossible, stubs=True has a decode cost, and scene_threshold tuning is sensitive to footage. This is rich, non-obvious behavioral information with no contradiction of 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 longer than average, but every sentence carries distinct information: definitions, edge cases, cost implications, and acknowledgement-staleness behavior. It is front-loaded with a one-line summary and uses bold labels effectively, making dense content scannable without fluff.

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 six-parameter, multi-finding analysis tool, the description covers the full decision surface: findings, parameter effects, edge cases, cost, and interaction with continuity_accept. With an output schema present, the absence of return-value discussion is acceptable; the description answers essentially any question an agent would need before calling.

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 coverage is 100%, so the baseline is 3, but the description adds semantic value by wiring parameters to finding definitions: gap separates rewind from replay, min_shot defines short_shot, stubs controls the expensive decode, and scene_threshold is given a real-world tuning example. It does not add new meaning to stub_tolerance, but the schema already covers it.

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 opening line names the tool's exact role: detecting rewinds, replays, short shots, and stubs, and 'reports, never decides.' Each finding type is defined in enough detail to distinguish for checking from sibling continuity_accept/continuity_reject/continuity_ls, which handle decisions and listing after the fact.

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 conveys strong context for when this tool is appropriate: it is a non-deciding reporter, and it explains how acknowledged findings from continuity_accept are handled, implying the accept/reject workflow. It does not explicitly name alternatives or say 'use this instead of X,' but the never-decides framing and the continuity_accept reference make the usage context clear.

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, so the safety profile is covered. The description adds behavioral context about how findings are reported: it explains the difference between stale (still exists but disagrees with the mark) and still_found=False (disappeared entirely). This clarifies the output semantics beyond what annotations convey, though it doesn't discuss edge cases like empty results or sorting.

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 compact and front-loaded: the first sentence states the core purpose, and the second paragraph clarifies a nuanced behavioral distinction. Every sentence earns its place, with no redundancy or filler. The structure efficiently conveys the tool's scope and output semantics.

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 and the path parameter is fully documented, the description covers the essential semantics of what findings are returned and the status fields. It explains the key distinction between stale and still_found, which is critical for correct interpretation. Minor details like ordering or pagination are not mentioned, but these are likely covered by the output schema. Overall, the description is complete enough for an agent 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?

The single parameter `path` is 100% covered by the schema, including a detailed description of how it resolves when bound or unbound. The tool description does not repeat parameter details, but with full schema coverage, the baseline is 3. No additional semantic value is needed from the description.

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 clearly states the tool lists accepted continuity findings and defines the status semantics (live vs stale vs still_found). It specifies the resource (accepted continuity findings) and the verb (list), distinguishing it from continuity_accept, continuity_reject, and continuity_check. The distinction between stale and still_found adds precision, making the 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 does not explicitly state when to use this tool versus alternatives. It is implicitly the listing counterpart to continuity_accept and continuity_reject, and it contrasts with continuity_check, but no explicit when-to-use or when-not-to-use guidance is given. The semantics are clear, but the tool does not proactively route the agent away from sibling tools.

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 destructiveHint annotation, the description discloses the full behavioral profile: the acknowledgement is dropped from the manifest, later runs report the finding again, a second call is refused rather than silently no-oping, nothing on the timeline moves, and undo reverses it. This is rich, non-redundant context that is fully consistent with the annotations (destructive=true, idempotent=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?

Three dense sentences, each earning its place: core purpose first, then inverse/refusal behavior, then timeline and undo semantics. It is front-loaded and efficiently structured, though the second sentence is heavy with parentheticals and could be split for readability.

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 destructive 4-parameter tool with an output schema present, the description covers the essential ground: what it does, when it is refused, what side effects occur, and how to reverse it. The output schema relieves it of explaining return values. Minor gaps like naming the list alternative are acceptable given the existing coverage.

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 coverage is 100%, so the baseline is 3. The description adds that clip_id/word_index/kind form the address 'exactly as it was accepted,' reinforcing that they must match the prior accept call. It adds modest value over the schema but does not elaborate on the path parameter or the kind values, which the schema already documents.

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?

Opens with a specific verb+resource ('Unmark a continuity finding, putting it back into continuity_check') and immediately frames itself as the inverse of continuity_accept. This clearly distinguishes it from the accept/check/ls sibling cluster without ambiguity.

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 names continuity_accept as the counterpart and describes the exact precondition (an accepted finding of that kind must sit there, else it is refused). It also notes that undo re-applies the acknowledgement. It does not explicitly name a sibling for viewing accepted findings (continuity_ls) or state 'use this only after an accept,' but the inverse framing carries the guidance.

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, the description discloses that `asset` is not checked against disk, duplicate cues are refused, the tool echoes the resolved word plus three neighbors, the out-point is derived from the next cue, and over-long shots cause a reported refusal rather than silent rewind. This is rich behavioral context with no contradiction against readOnlyHint=false, idempotentHint=true, and destructiveHint=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 long but front-loaded with a one-sentence definition and organized into focused paragraphs. It is dense rather than padded, though some historical context and convention references could be trimmed without losing operational value.

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 an 8-parameter mutation tool, the description covers addressing modes, duplicate and ambiguity failures, `src_start` placement, in-point behavior, card special cases, and the echo response. With annotations and an output schema present, nothing an agent needs to invoke this 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?

The schema already documents all 8 parameters at 100% coverage, so the baseline is 3. The tool description adds genuine cross-parameter meaning: exactly one of `word_index`/`phrase` must be given, `after`/`occurrence` disambiguate phrase matches, and `src_start` is an in-point measured in the asset's own source seconds. This goes beyond the individual parameter descriptions without duplicating all of them.

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 opening sentence states a specific action and resource: 'Add a picture cue: from `word_index` of `clip_id` onward, show `asset`.' It is unambiguous about creating cues and clearly distinguishable from sibling cue tools that list, remove, or re-resolve cues.

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 concrete when-to-use guidance: replace an existing cue by 'cue_rm it first', include `src_start` when placing a found moment versus omit it when re-using a clip, and choose `word_index` or `phrase` with disambiguation rules. It also explains when the tool refuses, so an agent can predict and correct failed calls.

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 carry readOnlyHint, idempotentHint, and destructiveHint, so the description's 'Read-only' adds no new safety info. However, it adds genuinely new behavioral context: the result is ordered by (clip_id, word_index) rather than timeline position, which is a non-obvious trait an agent needs to interpret results. 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?

Three terse sentences with no filler: purpose first, then scope, then the ordering caveat and pointer to build_shots. Every sentence earns its place and the most decision-relevant fact (what it lists) 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?

For a simple read-only listing tool with a rich output schema and full parameter coverage, the description is complete. It covers what is returned, scope control, ordering behavior, and where to go for timeline ordering. Nothing an agent needs to call or interpret this tool 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 coverage is 100%, so both parameters are already fully documented, including path resolution semantics and the clip_id filter. The description adds a small behavioral note about omitting clip_id for the whole table, which slightly extends the schema, but the heavy lifting is done by the schema itself. Baseline 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 opens with a specific verb+resource ('List the picture cue table') and clarifies that each entry is echoed with its resolved word. It implicitly distinguishes itself from the mutation siblings (cue_add, cue_rm, cue_reresolve) by declaring itself read-only, and explicitly separates itself from build_shots over the ordering question.

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 gives clear operational guidance on scope ('Omit clip_id to see every clip's cues') and explicitly routes the timeline-ordering need to build_shots, naming the alternative. It stops short of stating explicit when-not-to-use conditions versus the cue_* mutation siblings, but the read-only framing and ordering caveat give the agent enough to choose correctly.

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 carry destructiveHint=true, idempotentHint=true, and readOnlyHint=false, and the description fully complements them: it discloses exactly what gets destroyed (word_index rewritten in place), the never-guess policy for ambiguous/unresolved entries, the special 'action': 'unchanged (no phrase to re-resolve)' report, and the apply=False default safety posture. No contradiction with annotations; substantial added context.

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?

Front-loaded with the core purpose and outcome before the 'why', and the paragraphs are organized by concern (motivation, then apply semantics). It is somewhat long, but every sentence carries load — the re-record/word_index background and the no-phrase edge case earn their place. No fluff.

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 destructive, state-mutating tool with three parameters and an output schema, the description is complete: it covers apply semantics, ambiguity/unresolved handling, the no-phrase case, and the path-binding behavior is already fully documented in the schema. Nothing an agent needs to invoke 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?

Schema coverage is 100% and each parameter is well-documented, so baseline is 3. The description adds genuine value beyond the schema by explaining the semantic requirement that an entry must carry a stored phrase to be re-resolvable, and how apply interacts with ambiguity — detail not derivable from the schema alone.

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 names a specific verb ('re-resolve') and precise resource ('phrase-addressed cues, unspoken marks, music-bed boundaries') and states the outcome ('report what moved'). It is immediately distinguishable from siblings like resolve_phrase (single phrase lookup) and the unspoken_*/reframe_detect report tools because it targets the re-record/word_index-invalidation scenario explicitly.

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 a concrete trigger condition (a re-record replacing a clip's transcript, invalidating stored word_index entries) and explains the apply=False vs apply=True decision, explicitly aligning the report-only posture with reframe_detect/unspoken_detect. It does not explicitly name resolve_phrase as the alternative for single-entry lookup, but the scenario framing makes routing reasonably clear.

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 destructiveHint=true annotation, the description discloses concrete behavioral effects: refusal with a full cue listing when the address is empty, re-projection of shots from remaining cues, and that no other cue moves. It also explains why replacement must be rm-then-add, and that `undo` reverses it. This is exactly the extra behavioral context annotations cannot provide.

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 compact and front-loaded: action first, then addressing rules, then refusal behavior, then side effects, then workflow guidance. Every sentence contributes behavioral or usage value; there is no fluff or repetition of structured schema content.

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 rich input schema and the presence of an output schema, the description supplies all the missing contextual glue: how to address a cue, what happens on failure, side effects on shots, the replacement pattern, and undo behavior. The agent has everything needed to decide when and how to call 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?

Schema description coverage is 100%, with each parameter already richly documented, so the description carries little additional per-parameter burden. It does reinforce the central `word_index`/`phrase` addressing relationship and ties it to `cue_add`'s binding, but largely restates what the schema already says. Baseline 3 is appropriate here.

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 — 'Remove one picture cue' — and immediately anchors addressing to `cue_add`'s placement semantics. This cleanly distinguishes it from siblings like `cue_add`, `cue_reresolve`, `unspoken_rm`, and `hold_rm`. An agent can tell exactly what the tool does at a glance.

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 provide `word_index` or `phrase`, and explains what to do when no cue sits at the word (`cue_ls` shows the table first). It also names the replacement workflow (`cue_rm` then `cue_add`) and notes that `undo` restores it, giving clear when-to-use and alternative context. This is strong practical guidance beyond mere tool naming.

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 the destructiveHint annotation already true, the description adds substantial behavioral detail: render timestamps are never stored, conversion happens once at call time, all spans resolve before any are applied, overlapping spans are refused, and a second call is not equivalent to the first. This is exactly the contextual disclosure an agent needs for a destructive operation.

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 dense and front-loaded with the core concept before diving into details. Some content repeats what the input schema already states, but the extra length is justified by the destructive nature and the non-obvious render-time mapping.

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 complex, destructive tool with one required parameter and several interdependent behaviors, the description covers the conversion semantics, resolution order, overlap refusal, output echoes, pad behavior, plan mode, suspect-word refusal, and the critical 'second call is not the same call' warning. Nothing an agent needs to call it correctly appears to be 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 100%, and the schema already explains spans, pad, plan, path, and confirm_suspect in detail. The tool description adds some cross-cutting context about plan/confirm behaving like cut_by_transcript, but it does not substantially extend the parameter-level meaning already present in the schema.

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 names a specific verb ('Cut'), a precise resource ('spans of RENDER/TIMELINE time'), and immediately distinguishes it from source time and word indices. It also references cut_by_transcript by name, helping an agent separate the two 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 strong usage context: use it for what a human reports watching in an export, resolve all spans against the current timeline, and take spans from a fresh watch rather than reusing them across calls. It names cut_by_transcript as the analogous path and says this tool is not for source time or word indices, though it stops short of explicitly stating 'use cut_by_transcript instead in those cases.'

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' destructiveHint, the description discloses crucial behavioral traits: the timeline is snapshotted so the operation is undoable, `plan=True` writes nothing, `pad_reach` and echoed-word feedback explain boundary effects, and suspect durations trigger refusal or `suspect_boundaries` reporting. This is rich, non-obvious behavioral disclosure.

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 every sentence carries distinct value: main operation first, then mutually exclusive parameters, then side effects, then safety/refusal behavior. The structure is logical and front-loaded; the length is justified by 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?

Given the destructive nature, eight parameters, and existing output schema, the description is complete: it covers what happens, what not to do, how to preview safely, how to handle suspect boundaries, and how padding interacts with echoes. An agent has enough context to invoke this 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?

Even though schema coverage is 100%, the description substantially enriches the parameters: it explains what `pad` does in seconds, what `through_pause` means semantically, how `plan` differs from execution, and what `confirm_suspect` is for. This goes well beyond the baseline schema 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 opening sentence states a specific verb and resource: 'Cut or keep inclusive word ranges', with a concrete example showing the exact input shape. This clearly distinguishes it from the sibling `cut_by_time`, which operates on time rather than transcript word ranges.

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 constraints ('Pass exactly one of `cut` or `keep`'), mode-specific guidance (`through_pause=True` is cut-only, `plan=True` is preferred over acting and undoing), and a detailed refusal-and-retry workflow for suspect boundaries. These are actionable instructions an agent can follow without inferring.

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 declare destructiveHint=true and idempotentHint=true, and the description enriches both: the GPU cost model (~3s per window, minutes of project footage), that plan=True runs without loading the model and reports machine capability, that force replaces while a plain repeat costs nothing, and the two serious pitfalls — truncated descriptions read exactly like complete ones, and a window is never evidence of a continuous shot. 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?

Front-loaded with the core purpose and data model before the cost and pitfall discussion, and every sentence earns its place. Mild redundancy: the final paragraph restates the force/skip behavior already covered by 'Already-described clips are skipped unless force' earlier, which is the only trimming opportunity in an otherwise tight definition.

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 complex, cost-bearing, GPU-running tool with an output schema present (so return values need not be explained), the description is remarkably complete. It covers cost, machine-capability preflight, idempotency, destructive replacement semantics, and the two failure modes an agent could not guess (truncation that looks complete, narration across cuts). Nothing an agent needs to call 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?

Schema coverage is 100% and the schema descriptions are already rich, so baseline is 3. The tool description adds genuine value on top: the omitting-clip_id semantics (describe all undescribed video clips), the reframe-proof rationale for source seconds, and the concrete 'six frames as six people' example that motivates not widening window. This elevates it above the baseline.

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?

Opens with a specific verb+resource+purpose ('Describe footage in fixed windows, so b-roll can be found by what is in it'), then pins down the data model (clip_id, src_start, src_end, text). It actively distinguishes itself from transcribe ('their words are what transcribe indexes') and describes_ls is implied by the read-the-result guidance, so an agent can tell it apart from its close siblings without opening 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?

Explicit when-to-use and when-not: audio-only clips go to transcribe, already-described clips are skipped unless force, and it names plan=True as the preferred first invocation for a cost-bearing job. It even warns against widening window to save time. No alternative or condition is left to inference.

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 carry readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is covered. The description adds genuinely valuable behavioral nuance beyond that: there is no ranking/similarity score (the agent must read and choose), entries are returned in source seconds so they stay valid across edits, a window is evidence of what is visible in a span and never a continuous shot (the model narrates across cuts), and a `truncated` entry reads like a complete description but stopped mid-fact. These are exactly the kind of pitfalls an agent would otherwise misjudge.

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 (several paragraphs), but every section earns its place: purpose, the no-ranking philosophy, output format in source seconds, `contains` semantics, two critical interpretive caveats (window vs. shot, truncated), and the `windows: 0`/`describe` indexing note. It is front-loaded with the purpose and structured with bold lead-ins that make it skimmable. Slightly longer than strictly necessary, but nothing is 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 read-only search tool with an output schema present and 3 optional params, this is complete. The output schema relieves the description of explaining return structure, yet the description still supplies the interpretive keys an agent needs: how to read entries, what `truncated` and `windows: 0` mean, and the source-seconds guarantee. No critical calling 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?

Schema coverage is 100% — `path`, `clip_id`, and `contains` all carry detailed schema descriptions, so the baseline is 3. The tool description adds only marginal parameter value beyond the schema: it reinforces the `contains` semantics (already well documented in the schema) and adds the strategic advice to reach for it on large projects. It mentions the `words` output field, but that is output-related rather than parameter meaning. The schema does the heavy lifting here.

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 opening line states a specific verb and resource ('Read the footage descriptions, to find b-roll by what is in it') and then boldly declares '**This is the search.**', which sharply distinguishes it from the sibling `describe` (the indexing tool) and other media tools like `transcribe`/`hear`. An agent immediately knows what this does and what it does not do — it does not rank or score, it lists descriptions to pick from.

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 strategic guidance: 'Reach for it before reading everything on a large project' (use `contains` to filter early) and explicitly notes that a clip with `windows: 0` has not been described yet and that '`describe` is what indexes it' — routing the agent to the correct sibling. It stops short of enumerating explicit when-not-to-use conditions against other search-adjacent tools, but the context is strong enough to be actionable.

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 readOnly, idempotent, and non-destructive, and the description adds meaningful detail: 'nothing is installed and nothing is written,' feature-gated optional sections, and failures that include fixes. This goes well beyond the structured hints 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 longer than strictly necessary, but each sentence contributes a distinct fact: scope, side-effect-free behavior, optional feature gates, failure messaging, and server binding. The structure is coherent and front-loads the main purpose.

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 zero-parameter diagnostic with an output schema present, the description is complete. It covers what is probed, what is not touched, how output is organized, and how failing entries are reported. 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 tool has zero parameters)Skip and the schema is trivially covered. The description reinforces the only semantic point: it 'takes no project,' which is the key thing a caller needs to know.

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 diagnostic action: 'Probe every external binary proofcut depends on, and name each one's trap.' It also clarifies the tool takes no project, clearly distinguishing it from project-scoped 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 gives strong context for when to use it: before a project exists ('answers the question asked before there is one') and as a report-only check. It does not explicitly name an alternative tool to prefer instead, but the no-project framing is enough to route an agent correctly.

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 mark this as destructive and non-read-only, but the description goes far beyond: it explains that the writer is chosen from the project (never from an argument), details the single-source vs multi-source behavior, the resolution letterboxing vs refusal, the loudness refusal condition, and the safety rule about paths outside the bound project. It also notes that a render that exists is not necessarily correct, implying the need for verification. 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?

The description is dense but every sentence earns its place. It is front-loaded with the core purpose, then progresses through writer selection, presets, loudness, and post-export verification. No fluff or repetition. The length is justified by the complexity of the tool (8 parameters, multiple modes, and interactions).

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 tool's complexity, the description is complete. It covers the main modes, writer selection, parameter interactions, destructive behavior, and directs the user to complementary tools. The output schema exists, so return-value details are not required. An agent can correctly invoke this tool without additional documentation.

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 coverage is 100%, so the baseline is 3, but the description adds substantial semantic value. It explains parameter interactions: preset is meaningful only with export_format=null, tiktok-reels checks 9:16 and never sets shape, resolution letterboxes on single-source and is refused on multi-source, loudness is render-only, fps is ignored when auto-editor renders single-source, and path resolution rules. These are critical operational details not present in the schema.

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-resource pair ('Export the timeline as an NLE project, or render it') and immediately clarifies the two modes. It distinguishes from siblings by explicitly stating captions are not burned (add_captions) and mentions verification tools. The writer-selection logic based on project composition further sharpens the tool's unique role.

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-to-use and when-not-to-use guidance. It says captions require add_captions as a separate step, and recommends check_frames and verify after export. It also warns that tiktok-reels preset never sets the shape and directs to use canvas first. This routes the agent to the correct tools for each sub-task.

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, the description discloses important stateful behavior: 'reference is remembered: passing it stores it on the project', 'reset drops the stored reference', and 'plan resolves without writing.' It even specifies that the check is 'cheap, no frame counting, no melt' and explains what happens when no reference is present, which adds valuable context the annotations do not provide.

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 but becomes overly long, including an extended HISTORY.md anecdote that is not necessary for selecting or invoking the tool correctly. The paragraph on segment counts and the detailed example add noise, though the structure is logical and organized.

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, return values need no explanation, and the description covers all essential behavioral edge cases: no reference, stored reference, reset, plan, and what exactly is compared. Nothing an agent needs to call this 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?

All parameters already have rich descriptions in the input schema, so baseline is 3. The description primarily repeats what the schema says (e.g., reference is remembered, reset drops it, plan resolves without writing). It adds no new parameter-level meaning beyond the schema.

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: 'Compare this project against the export it is supposed to be.' It also explicitly distinguishes itself from the sibling check_frames by explaining what each tool can and cannot catch, so an agent can tell them apart without opening 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 contrasts film_check with check_frames, identifying the key difference: check_frames validates against the project's own arithmetic, while film_check compares against an external reference file. It also describes behavior in the no-reference case ('reports the project's own numbers and says there is nothing to compare them against') and names the plan and reset alternatives for safe operation.

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 establish readOnly/idempotent/non-destructive, and the description adds substantial non-redundant behavioral context: the full inventory of eight checks with their semantics (loudness is 'report only', blackdetect runs are 'explained only when it falls inside the prepend or a hold's own span'), the window-stitch false-miss recovery behavior (`boundary_misses`, recovered), the aggregation into `faults`/`ok`, and the `finishlog` side effect enabling `proofcut review serve` WARN badges keyed to sha256. 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?

The core purpose is front-loaded in the opening sentence and nearly every sentence earns its place given the tool's eight-check complexity. However, the body is one dense ~170-word paragraph built from slash-chains and semicolons that is genuinely hard to scan; the eight checks could be enumerated or broken into digestible chunks. The information is justified, but the structure is not.

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 15-parameter tool with an output schema, the description is unusually complete: it covers the coordinate/time-base semantics, the default resolution of `prepend_seconds` and `holds`, the per-check behavior including what is report-only versus fatal-adjacent, recovery mechanics, and the logging/observability contract. The output schema covers return values and the 100%-coverage schema covers parameter mechanics; the only residual gap is that the density of the checks paragraph still demands careful reading, but nothing operationally necessary 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 coverage is 100%, so the baseline is 3, but the description clearly exceeds it: it explains the coordinate system binding `final`, `prepend_seconds`, and `holds` together ('every position this reports is in `final`'s own absolute seconds'), clarifies that `prepend_seconds`/`holds` default to stored project values with live offset resolution, and gives purpose to `recheck_pad` ('the pass that separates a real miss from a false one at a window stitch') and `windowed_model` ('runs over twice the audio'). This is genuine semantic value beyond the schema's field-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 opens with a specific verb+resource pair ('Check a delivered file against this project's timeline') and immediately differentiates from siblings: it is the `verify`/`check_frames`/`check_black`/`film_check` equivalent 'for a file an external mix pass produced, not one of proofcut's own renders.' An agent can unambiguously distinguish this from its four named sibling tools without opening 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 first sentence establishes the selecting condition — external mix pass deliverables versus proofcut's own renders — which implicitly routes proofcut renders to verify/check_frames/film_check. It also gives explicit guidance on when to override defaults: 'pass either explicitly (an empty `holds` list included) to check a file against a different set than what is currently stored.' It stops short of an explicit when-not statement naming the alternative for proofcut renders, so it is clear but not fully explicit.

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, so safety is known. The description adds substantial behavioral context beyond that: it explains the cost of optional sections (5.7s wall, 46s CPU for framing), the meaning of None (not measured vs. nothing stale), and the special semantics of unused_clips and its clearable methods. No contradiction with annotations; instead, it enriches the behavioral model.

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 exceptionally well-organized: it opens with a one-line summary, then uses a bulleted list for the core sections, and separately details the optional flags with their costs. Every sentence earns its place; nothing is redundant. The front-loading of the main purpose and the structured breakdown make it easy to scan despite its length.

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 thoroughly covers all sections and optional flags, including return semantics (None cases), performance trade-offs, and even how to clear unused clips. Since an output schema exists, the description need not spell out the return structure, and indeed it doesn't. Nothing an agent needs to decide whether to call this tool or how to set its flags 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 input schema covers all four parameters with descriptions (100% coverage), so the baseline is 3. The description adds extra nuance, especially for 'holds' and 'framing', explaining when they return None and reiterating the cost rationale. This goes slightly beyond the schema's one-liners, providing the agent with better context for deciding when to pass true.

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: it produces a comprehensive report for Finish mode, listing the exact components (duration, canvas, captions, picture, marks, seams, unused clips, flags). It also differentiates from siblings by emphasizing 'the truth strip's own numbers' and by referencing optional sections that mirror dedicated check tools (framing, holds, continuity), making its aggregating role clear.

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 explains when to enable each optional section (framing, holds, continuity) and notes the computational cost for each, giving clear context for choosing to include them. It implies this tool is the go-to Finish report rather than calling the individual check tools, but it does not explicitly state 'use this instead of X' or list alternative tools for specific scenarios. Still, the cost warnings effectively guide usage.

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, the description discloses important behavioral traits: the tool reports two answers side by side without merging them, uses an impossible-family render comparison to detect substitution, and has an install flag that writes into the home directory. This adds real context about side effects and output semantics that annotations alone do not provide.

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?

Despite its length, every sentence earns its place: the opening question sets intent, the next two explain the core mechanism and non-merging behavior, and the final paragraph covers the two parameters. The structure front-loads the most important behavioral facts.

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 the tool does, how it does it, the optional behaviors, and the side-effect risk of install. The output schema is present, so return-value details do not need to be spelled out. Nothing an agent needs to correctly select and invoke this tool 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 coverage is 100%, so the baseline is 3. The description restates the path and install semantics already present in the schema and adds some rationale about why the impossible-family comparison matters, but it does not meaningfully extend the schema's parameter documentation.

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 concrete diagnostic question and then specifies exactly what the tool reports: fontconfig presence versus an actual render comparison. It clearly identifies the resource (caption font, default or project-specific) and the unique two-answer behavior that distinguishes it from 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 gives clear context for when to use the tool: when you need to know whether a caption font will actually draw on this machine, rather than just whether the family is present. It explains the path semantics and the default behavior, though it does not explicitly name alternatives or say when not to use it.

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 declare destructiveHint=true and idempotentHint=true, but the description adds meaningful behavioral context: it returns bytes in the reply, marks blank tiles as '[blank]' to avoid confusion with failed extraction, and warns that the sheet is 'a hypothesis, not a check' and is read to choose footage. It also discloses that scenes mode decodes the whole clip. 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 dense but well-organized: a one-sentence summary, a paragraph on positioning, a paragraph on modes, and a paragraph on interpretation. Every sentence earns its place, though the mode paragraph is long and could be tightened. The key contrast with shot_sheet 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?

For a 7-parameter tool with no output schema, the description covers the main behavioral concerns: what the output looks like (image tiles, bytes in reply), how modes interact, and the caveat that it's a hypothesis. It doesn't explicitly describe the full return structure, but the description's emphasis on 'bytes come back' and 'path rather than readable bytes' covers the essential return distinction. The blank-tile behavior and scenes opt-in warning are valuable completeness additions.

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 coverage is 100%, so the baseline is 3. The description adds value by explaining the relationship between interval and describe windows ('It is describe's own window length, so a tile lines up with a description'), clarifying that per_page=null returns a path rather than bytes, and explaining the path resolution behavior for bound vs unbound servers. These are semantic details beyond the schema.

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: 'Look at a clip's own footage — one labelled tile per moment, as an image.' It immediately distinguishes itself from shot_sheet ('shows an existing edit's picture track') and describe ('can search by text but cannot show'). The purpose is unmistakable and differentiated from siblings.

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 states when to use this tool: 'the first look at b-roll, recordings and gameplay' and contrasts it with shot_sheet and describe. It also explains mode selection semantics (auto, interval, describe, scenes) and when scenes is appropriate ('opt-in, since a continuous take has none'). This is explicit when/when-not guidance.

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, and destructiveHint, so the tool is safe and idempotent. The description adds pagination details (total_words, last_word, next_first) and notes that next_first is only present when words are left out, which is useful behavioral context beyond 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 concise and well-structured. It front-loads the primary use case (search) and then explains pagination in a few clear sentences. No wasted words.

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?

With an output schema present and complete schema coverage, the description sufficiently covers the key aspects: modes, pagination, and continuation. It could be a bit more explicit about the output schema fields, but overall it's complete for an agent to use effectively.

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 coverage is 100%, so the schema already describes all parameters. The description clarifies the interplay between first, last, limit, and search, and explains how next_first is used for continuation, but this is largely redundant with schema descriptions. It doesn't add major new 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 clearly states the tool reads a clip's transcript and explains the different modes (search, first/last). It distinguishes itself from siblings like cut_by_transcript by showing how search results are meant to feed into it.

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 says to prefer search over reading the whole transcript, and explains first/last semantics. It also mentions pagination with limit and next_first, providing complete 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?

Although annotations already mark the tool as destructive and idempotent, the description goes far beyond them: it explains partial-update semantics, `reset` dropping the head entirely, `plan` resolving without writing, the cue-lane prerequisite, and the reason fades are drawn from day one. This is rich behavioral context beyond the structured fields.

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 longer than average but each paragraph covers a distinct operational rule: reading, partial updates, defaults, prerequisites, reset, and plan. It is front-loaded with the core purpose; the additional rationale is dense but mostly 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?

Given the tool's complexity, the rich parameter schema, and annotations, the description covers all necessary invocation modes, preconditions, defaults, and sibling-tool relationships. The output schema exists, so the lack of return-value detail is not a gap. Nothing essential for calling this 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 coverage is 100%, so the baseline is 3, and the schema itself already documents each parameter. The description adds real value by explaining interdependencies — `asset` and `seconds` must be set together on first set — and by clarifying defaults like `src_start` at 0.0 and the distinction between `gain_db` and the fades.

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: "Read or change the cold open this project plays before its first frame." It clearly distinguishes the tool from `tail` by calling it that tool's mirror at the other end of the film, so an agent can tell them apart 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 invocation guidance: call with no arguments to read, set asset and seconds together on first set, update individually afterward, use `plan` to validate without writing, and `cue_add` first if no picture cue lane exists. It also names `tail` and `verify` as related tools, making the when-to-use boundary clear.

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 read-only/idempotent annotations, it discloses that the call reports and never attaches, writes nothing, moves no word index, may return empty `heard_words` as a valid silence answer, performs one whisper run over the span, and refuses `end` past the clip. This is substantive behavioral context the annotations do not provide.

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 dense but every sentence earns its place: purpose, trigger conditions, method, return fields, side effects, alternatives, and edge cases. The opening question front-loads the core purpose, and the bold 'Reports, never attaches' makes the side-effect statement highly 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?

For a read-only listening/verification tool with an output schema and well-documented parameters, this description covers everything an agent needs to call it correctly: when to use it, what it returns, what it does not do, cost/run characteristics, and refusal behavior. Nothing important 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 100%, and the schema already explains source seconds, refusal behavior, defaults, and language handling in detail. The description reinforces the source-seconds framing and mentions windowed passes, but it does not need to compensate because the schema already carries the parameter semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.