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

Annotations already declare this is a non-destructive write operation. The description adds useful behavior beyond the annotations by disclosing persistence ('Kept in the session and a sidecar') and downstream consumption by chapters and pipeline.

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 short sentences with no wasted words. The core action is front-loaded, followed immediately by persistence and downstream behavior.

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 annotations, a fully documented schema, and an output schema are present, the description supplies the key missing context: markers persist in session and sidecar and feed chapters/pipeline. It does not elaborate on permissions or error behavior, but little is missing for a simple marking tool.

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 detailed parameter meanings are already documented in the schema. The description adds only the high-level distinction between live marking and marking at a second, which is useful but not more specific than 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 ('Mark a labelled moment on a recording') plus the two modes ('live or at a second'). It also differentiates markers from the sibling 'chapters' tool by explaining that 'chapters and pipeline turn markers into chapters.'

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 context for when this is appropriate: while recording live or at a specific second. It does not state explicit exclusions or name a direct alternative, but the consumer relationship with 'chapters' and 'pipeline' makes the intended workflow 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 destructiveHint=true and readOnlyHint=false, so the agent knows this is a write operation. The description adds useful context that inputs need not match in size, fps, or audio, which is beyond the schema. But it does not mention overwrite behavior or that it creates a new file at the output path, leaving some behavioral gaps for a destructive tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single, front-loaded sentence with no wasted words. It conveys the core action and a key differentiator efficiently.

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 rich annotations, a complete input schema, and an output schema, the description covers the main purpose and a key constraint (heterogeneous inputs). Minor gap: it does not mention the overwrite/destructive aspect, but that is partially covered by annotations and the overwrite parameter 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?

Schema description coverage is 100%, so all parameters are documented in the schema. The description adds no additional meaning about parameters beyond what the schema provides; 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 ('stitch') and resource ('clips into one video'), and notes it handles title cards and heterogeneous inputs. However, it does not explicitly name the sibling tool concat, which likely handles similar stitching with matching properties, so sibling differentiation is only implied.

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?

No guidance on when to use this tool versus concat or xfade_transition, nor any exclusions or prerequisites. The mention of cuts or xfade transitions is about capability, not selection criteria.

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 with openWorldHint=false, so the agent knows this writes files in a closed local scope. The description adds the canvas/aspect constraint but does not warn about overwriting existing output paths or that the operation is non-idempotent, which is exactly the behavior the destructive flag is pointing at.

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?

One well-formed sentence, front-loaded with the verb and the tool's value proposition, with the optional canvas variants trailing. Every clause maps to a parameter or capability; nothing is 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?

An output schema exists and all parameters are documented, so the description only needs to convey core behavior, which it does. It falls slightly short on when-to-use guidance and file-writing/overwrite semantics, but for an 11-param tool with a fully documented schema this is close to sufficient.

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 every parameter is already documented, including enum values and defaults. The description restates the treatments (padding, rounded corners, drop shadow, gradient) but adds no syntax or precedence detail (e.g., how colors vs. image vs. preset interact) beyond the schema, making a baseline 3 correct.

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 ('Frame') applied to a specific resource (video or screenshot) and enumerates the distinct visual treatments (gradient, color, wallpaper; padding, rounding, shadow, canvas aspect). No sibling tool (overlay, callout, title_card, reframe) offers this composite framing behavior, so an agent can distinguish it 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?

It implies usage ('Frame a video or screenshot') and lists the canvas options, but never states when to pick this over reframe, overlay, or title_card, nor any prerequisites or exclusions. The context is inferred rather than spelled out.

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 destructiveHint=true and readOnlyHint=false, so the safety profile is partly covered. The description adds useful behavioral context: the package is secret-scanned, outputs are redacted, OCR is used, steps come from the event log, and a report.md is generated for gh issue create. It does not explicitly warn about overwriting an existing report, but the schema's overwrite parameter covers that detail.

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 a single front-loaded sentence that names the core action first and then lists the packaged artifacts. Every clause corresponds to a real output or processing step, and there is 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 18 optional parameters, full schema descriptions, annotations, and an output schema, the description is sufficiently complete at the task level. It explains what the package contains and how it is built. The main remaining gap is not naming an input recording or sessionId explicitly in the prose, but the schema covers those parameters fully.

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 all 18 parameters in detail. The description does not add syntax or meaning beyond what the schema provides; it only confirms that redaction, GIF export, OCR, and report generation are supported. Baseline 3 is appropriate when 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?

States a specific verb and resource: package a recording as a repro folder. The listed outputs (redacted clip/GIF, contact sheet, steps, OCR'd errors, environment, report.md) make clear this is a bug-report packaging tool, not a generic export, screenshot, or step guide. It is readily distinguishable from sibling tools like export_gif or contact_sheet.

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 implies the usage scenario: creating a paste-ready bug repro package for gh issue create. However, it does not explicitly say when to use this versus alternatives such as step_guide, review_recording, or manually combining screenshot/contact_sheet/export_gif. No exclusions or prerequisites are stated.

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 destructiveHint=true, idempotentHint=false and openWorldHint=false, so the risk profile is covered. The description adds only the 'bundled font' constraint (styling is fixed, not user-supplied), and says nothing about whether the source video is preserved or how overwrite protection behaves — though the schema covers the latter.

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?

One front-loaded sentence naming the action, the input formats, and the styling constraint; nothing redundant. The mention of the source tool is a compact, useful workflow cue rather than 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?

With an output schema and full parameter documentation, the essentials are covered. However, for a destructive, non-idempotent media write, the description omits whether the input video is left untouched and what happens when subtitles cannot be parsed or the chosen style conflicts with .ass styling — gaps the structured fields don't close.

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%, including the style enum's meaning and the output/overwrite defaults, so the schema does the heavy lifting. The description adds almost nothing parameter-level beyond reinforcing accepted subtitle formats, which the schema already states — baseline 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?

States a specific verb and resource: burn subtitles (SRT/ASS) into a video. The parenthetical '(e.g. from transcribe)' ties it to the upstream sibling, so the agent can place it in a workflow, though it does not explicitly contrast with adjacent post-processing tools like overlay or title_card.

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 reference to transcribe implies a when-to-use context (caption burn-in after transcription), but there is no explicit statement of when to prefer this over overlay/title_card, nor any prerequisite or exclusion.

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 destructiveHint=true, idempotentHint=false, and readOnlyHint=false, so the safety bar is low. The description adds genuine beyond-annotation context by disclosing that substituted fonts appear in fallbackFonts and uncovered characters surface in warnings, which is real behavioral information. It stops short of explaining what 'destructive' means here (the output path/overwrite interaction).

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 tight sentences with the core action front-loaded and the fallback-font caveat following. Every sentence carries information and nothing is repeated from the schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present and full parameter coverage, the description need not explain return values, and it correctly flags the fallbackFonts/warnings fields. It leaves the destructive-overwrite relationship to the schema, which is acceptable but a small gap for a tool annotated as destructive.

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 all five parameters are already documented, including from/to timing, color formats, and overwrite semantics. The description adds no parameter-level detail beyond what the schema provides, 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?

States a concrete verb and resource (annotate a video) plus the three annotation kinds it draws (timed boxes, text labels, arrows). This is enough to distinguish it functionally from generic tools like overlay or title_card, though it never names a sibling 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 implies annotation but gives no when-to-use condition, no prerequisites, and no guidance on choosing it over annotate-adjacent siblings such as overlay, title_card, or cursor. Nothing tells the agent when this is the wrong tool.

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

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

Annotations declare destructiveHint=true and readOnlyHint=false, and the description usefully clarifies the operation writes into a *copy* without re-encoding, so the source video is not mutated, and that default output lands under SCREENCAST_HOME/edits. It still does not mention that an existing output requires the overwrite flag or what happens on failure, but the annotations plus the copy semantics cover the main risk.

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, front-loaded with the core action, and the parenthetical enumerates sources compactly. The trailing subtitle sentence is slightly bolted-on but each sentence carries information an agent needs.

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 the description needn't explain returns, and the no-re-encoding/copy detail is valuable for a destructive tool. However, with zero required parameters across 11 options there are meaningful input combinations (input vs sessionId, transcript required for from:transcript) that the description does not disambiguate, leaving gaps the schema alone must close.

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 including the `from` enum and default minChapterSec values. The description restates the source options ('markers, scene changes, transcript, or a list') and subtitle muxing, adding confirmation but no format or default detail beyond the schema — the baseline 3 for full schema coverage.

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 (write) and resource (chapters) plus the accepted sources and the fact it operates on an mp4/mkv/mov copy without re-encoding. It also flags two side capabilities (YouTube text output, soft-subtitle mux) that separate it from plain subtitle tools, though it never names a sibling such as burn_subtitles.

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?

Usage is only implied through the enumerated chapter sources (markers, scenes, transcript, explicit list); there is no explicit 'use this when...' statement and no exclusion of alternatives. The natural alternative, burn_subtitles for hard-burned subs versus this tool's soft mux, is never distinguished, leaving the agent to infer the routing.

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 write, destructive, non-idempotent, and closed-world behavior. The description adds useful context about frame-exact extraction and one-file-per-segment output, but it does not elaborate on overwrite behavior or other destructive details beyond what annotations and schema 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?

Two sentences, front-loaded with the core action, and the sibling distinction is placed immediately after. No wasted text.

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 a complete input schema and an output schema, the description supplies the essential selection context and the trim alternative. It is nearly complete, though it could briefly reinforce multi-segment output destination behavior, which is currently only in the 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?

Schema description coverage is 100%, so parameter meanings are already fully documented. The description adds only the notion that each segment produces its own file; it does not provide additional syntax or constraints 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: extract frame-exact segments, with the output behavior that each segment becomes its own file. It also distinguishes the tool from the single-segment sibling trim.

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 clearly routes the agent away from single-segment use by noting trim does the same for one segment. It does not explicitly state prerequisites or all when-not conditions, but the key alternative is named.

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 disclose destructiveHint=true and idempotentHint=false, so the safety profile is covered. The description adds the CRF ladder mechanism, useful context beyond annotations, but doesn't say what gets overwritten, that output defaults under SCREENCAST_HOME/edits, or that overwrite=false by default — all relevant for a destructive, non-idempotent tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, zero waste, with the mechanism stated first and the routing hint second. Nothing redundant against the schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema and full annotations, the description doesn't need to explain return values or safety. It's sufficient to call correctly, though it leaves the overwrite/destructive semantics implied rather than stated.

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 every parameter is already documented, including CRF values per level and the downscale-only behavior of maxWidth. The description merely echoes 'CRF ladder' and 'width cap' without adding syntax or defaults beyond the schema — 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?

States a specific verb and resource ('Re-encode a video smaller') and immediately qualifies the mechanism (H.264 CRF ladder, optional width cap), which distinguishes it from encode-adjacent siblings like convert and export_preset. An agent can tell exactly what this tool produces.

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 routes the agent: 'For a platform target use export_preset' names the alternative and the condition selecting it. It doesn't address other plausible rivals (scale, convert) or note when not to compress, so it's clear but not exhaustive.

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 destructiveHint=true, idempotentHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavioral context the annotations cannot: it explains the two execution paths (stream copy when inputs match, re-encode otherwise), which tells the agent results may differ in quality/speed depending on input compatibility. It stops short of saying what happens to an existing output file or whether re-encoding loses quality, keeping it out of 5 territory.

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 tightly packed sentences with zero filler: the core behavior first, the sibling routing second. Every clause carries information an agent needs.

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, return values need no explanation, and the description covers purpose, execution modes, and alternatives. The remaining gap is the phantom `mode` reference, which leaves the agent guessing whether mode selection is automatic or exposed as a parameter.

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 inputs/output/overwrite are already documented and the baseline is 3. The description does add meaning about `inputs` (matching inputs allow stream copy, mismatched ones force a re-encode), but it also references a `mode` parameter that does not exist in the schema — a misleading pointer an agent could act on and get an error.

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 ('Join videos end to end with hard cuts') and scopes it to hard cuts only, which immediately separates it from transition-based siblings. It names the exact alternatives (xfade_transition, assemble_highlights) an agent should consider instead, so the tool is distinguishable without opening any schema.

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 gives the alternative and the condition that selects it: 'For transitions use xfade_transition or assemble_highlights.' That is the classic when-not-use routing an agent needs, and it is stated rather than implied.

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 readOnlyHint=false, yet the description never explains why: it writes a PNG to disk, has an overwrite guard defaulting to false, and can emit a poster frame instead of a sheet. Those are precisely the behaviors an agent needs before calling a destructive tool, and the description adds none of 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?

One sentence, front-loaded with the action and result, with the parenthetical qualifier earning its place by signaling cost. There is 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?

An output schema and full schema descriptions cover return values and parameters, so the description needn't restate them. But for an 11-parameter tool that writes files destructively, the absence of any note on disk output, the overwrite guard, or the even-vs-scenes tradeoff leaves a meaningful gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so every parameter including mode, count, poster, and overwrite is already documented in the schema. The description adds no syntax, defaults, or mode-selection guidance beyond what structured data provides, so 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?

States a specific verb and resource ('tile timestamped frames of a video into one image') plus the resulting artifact, so an agent knows exactly what is produced. It hints at its place in the workflow ('cheapest first look') but never names the nearest sibling, sample_frames, so differentiation is only implied.

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 cheapest first look' implies a first-pass triage use case, which is useful context. However, there is no explicit when-not guidance and no alternative named (sample_frames, review_recording, get_media_info), so the agent must infer the routing decision.

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 destructiveHint=true, non-idempotent, and non-read-only behavior, so the safety profile is covered. The description adds format-specific intent but does not elaborate on overwrite behavior, side effects, or output handling beyond what the schema already states.

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 compact sentences with the core action front-loaded and alternatives immediately afterward. There is no wasted prose.

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 and fully described input schema, the description does not need to explain return values or parameter syntax. It is nearly complete, though it could clarify overwrite/destructive behavior slightly more given that the tool writes files.

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 all six parameters including fps, width, format, output, and overwrite are documented in the schema. The description adds no parameter-level detail beyond the format list, which is already covered by the schema's format enum.

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

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource (convert media) and enumerates the exact output formats, so the agent can distinguish it from generic editing tools. It also names sibling alternatives for specific cases, making the tool's scope 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?

Explicitly routes the agent away from this tool when a size-bounded GIF/WebP is desired (prefer export_gif) and when a smaller mp4 is desired (compress or export_preset). That is concrete alternative 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 destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so the safety profile is covered structurally. The description adds one genuinely useful behavioral fact: out-of-frame rectangles are rejected rather than clamped. It says nothing about what is destroyed (e.g. overwriting an existing output) or about defaults, so it only partly extends 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?

A single front-loaded sentence with the operation first and the constraint second; no filler and nothing buried.

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, non-idempotent mutation with 7 parameters, 43% schema coverage, and an output path default under SCREENCAST_HOME/edits, the description omits coordinate-origin semantics and overwrite behavior. An output schema exists, so return values need no explanation, but the input-side gaps are material.

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 only 43%, so the description needs to compensate, yet it says nothing about x/y being the rectangle origin, whether that origin is top-left, or how width/height interact with odd dimensions. The phrase 'pixel rectangle' only weakly signals that the four required integers are pixel units.

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 gives a specific verb (crop) and resource (video) plus the unit of the operation (a pixel rectangle), which clearly separates it from generic transforms. It does not name or contrast with adjacent siblings such as reframe, scale, or trim, so an agent must still infer the boundary itself.

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?

There is no statement of when to choose crop over reframe, scale, or trim, and no prerequisites or side conditions are mentioned. The only extra clause ('one running off the frame is rejected') is a validation rule, not usage 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 destructiveHint=true and readOnlyHint=false, so the write profile is covered. The description adds real behavioral detail (hides when idle, click ripples, optional spotlight) but largely mirrors schema parameters (clicks, spotlight, hideAfterSec) and says nothing about the output file/dry-run/overwrite semantics, which only the schema carries.

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?

One sentence, front-loaded with the action, no wasted words. The nested clause "from the event log of a start_recording cursor:\"events\" recording" is syntactically awkward and needs re-reading, costing it the top score.

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 100% parameter coverage, the description needn't explain returns or per-param syntax. It supplies the crucial input-dependency context; the only gap is that destructive/write-file behavior is delegated entirely to annotations and the overwrite/dryRun params.

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 all 10 parameters documented (size scaling factor, smoothing 0–1, hideAfterSec semantics, dryRun, overwrite). The description adds only a gloss on smoothing/scale/ripples/spotlight that the schema already specifies, so 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?

States a specific verb+resource ("Draw a smoothed, scaled cursor") and names the exact input it applies to: the event log of a start_recording cursor:"events" recording. This differentiates it from keystroke_overlay/callout overlays by identifying the required recording mode, though it never names a sibling alternative directly.

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 a clear precondition for use — the recording must have no OS cursor baked in and must be cursor:"events" — so an agent knows which recordings this applies to. It stops short of explicit when-not-to-use rules or naming a fallback tool when those conditions fail.

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 destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so the mutation profile is covered structurally. The description adds useful behavioral context by saying it cuts transcript elements and also writes a re-timed .srt, but it does not elaborate on overwrite behavior, dry-run reporting, or how the output file relates to the source.

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 a single front-loaded sentence with a clarifying colon and a second clause for the .srt side effect. Every clause is informative and there is 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?

With an output schema present and full schema coverage, the description need not explain return values or every parameter detail. It covers the core action and the important side effect of writing a re-timed .srt, though it leaves usage selection against sibling editing tools implicit.

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 all parameters in detail, including the remove and fillers parameters. The description echoes the remove/filler concepts but adds no syntax or constraints beyond what the schema provides, making the baseline 3 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 states a specific verb ('Edit') and resource ('video by its transcript') and enumerates the transcript-based cut modes: quoted text, cue numbers, and fillers. This clearly distinguishes the tool from generic trimming or clipping siblings by mechanism, but it does not explicitly name or compare against those alternatives.

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?

There is no explicit guidance on when to use this tool versus siblings like trim, clip, or cut_idle, nor are prerequisites or exclusions stated. The transcript-based framing implies a use case, but the agent must infer the selection conditions.

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 destructive=true, readOnly=false and non-idempotent, so the safety profile is covered. The description adds genuinely non-structured behavior: the detector requires frozen frames AND silence, a short pad is preserved at each edge, and the call reports time saved — details an agent can't get from 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?

Two tight sentences: the operation and its detection criteria are front-loaded, and the return value follows. No filler, nothing repeated from the schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 7-parameter destructive tool with no output schema, the description covers what is cut, the safety pad, and the return value (time saved), while the schema carries paths, overwrite, and dryRun. What's missing is whether the source is left untouched (a new file under edits/) — relevant for a destructive-hinted tool.

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 all seven parameters are already documented, making 3 the baseline. The description does add a conceptual link ('keeping a short pad' ↔ keepSec, '(and silent)' ↔ useAudio) but no formats, units, or defaults 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?

Specific verb+resource: 'cut stretches where the screen is frozen (and silent)' precisely describes the operation, and 'remove dead air' frames the intent. It differentiates itself implicitly from trim/cut_by_transcript by naming the detection signal (frozen screen + silence), though it doesn't call out a sibling by name.

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 'Remove dead air' implies the use case (a recording with idle/frozen spans), but there is no explicit when-to-use vs. when-not, and no routing to alternatives such as cut_by_transcript (which removes silence/speech-based gaps) or trim. An agent must infer that this is the screen-freeze variant.

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 adds useful behavior beyond the annotations: the denoiser is adaptive FFT-based, video is copied untouched, and the tool returns the output path. With destructiveHint=true already declared, this context helps clarify the operation, though it could more explicitly state whether the source file is left unchanged.

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 short sentences are front-loaded with the core purpose, then add two important behavioral facts. There is no redundant or filler text.

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 four-parameter media transformation tool with full schema coverage, annotations, and an output schema, the description is complete enough. It covers the operation, the untouched video stream, and the returned output path without needing to restate structured details.

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 parameter meanings are already well documented in the input schema. The description does not add parameter-specific semantics beyond what the schema provides, making 3 the appropriate 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?

The description states a specific verb and resource: reduce steady background noise in a recording's audio using an adaptive FFT denoiser. The examples of fan, hum, and hiss make the purpose concrete and distinguish it from adjacent audio tools such as normalize_audio or compress.

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 a clear condition for use by naming steady background noise such as fan, hum, and hiss. It does not explicitly state when not to use it or point to sibling alternatives, 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?

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the safety profile is covered. The description adds genuine value beyond that: it explains the `problems` output tells what is missing and how to fix it, framing this as diagnosis rather than repair. It doesn't mention cost or runtime of the checks, but that's minor.

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, both load-bearing: the first scopes the checks, the second states the trigger. The trigger guidance is placed last where it's easy to find, and nothing is repeated from the schema or annotations.

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, the description needn't spell out return values, and it still flags the key `problems` field. For a read-only, zero-parameter diagnostic, everything an agent needs to decide to call it is present.

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 takes zero parameters, so there is nothing to document and the baseline of 4 applies. The description correctly requires no input to invoke 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 description names a specific action (check the setup) and enumerates exactly what is inspected: ffmpeg/ffprobe versions, optional filters, capture devices, Windows OCR, settings, and enabled toolsets. None of the siblings do diagnostics, so an agent can distinguish this from the recording/editing tools without opening the schema.

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 two explicit trigger conditions — 'Call on first use' and 'when a tool reports a missing feature' — which is precisely the when-to-use guidance an agent needs for a diagnostic tool. The alternative (remediation tools) is implicitly excluded because this only reports problems.

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 non-idempotent, so the write/safety profile is already covered. The description adds the important behavioral fact that the tool iteratively steps fps, width, and quality down until the budget is met, which is not inferable from annotations or schema. It doesn't mention overwrite semantics, but the schema spells those out.

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?

One sentence, front-loaded with the action and its purpose, then the adaptive mechanism. 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, the description doesn't need to explain return values, and full schema coverage handles parameters. What it must convey — the self-tightening export behavior — it does, though it could note the default format or the overwrite implication for full completeness.

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's phrasing frames fps/width as starting points that get reduced, which reinforces but does not meaningfully exceed the schema's own 'Starting frame rate'/'Starting width' wording.

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

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource (export GIF/WebP) plus the defining mechanism: it degrades fps/width/quality until it fits a size budget. That mechanism is what separates it from siblings like convert, compress, and export_preset. It does not explicitly name those siblings, so it falls just short of a 5.

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 usage context ('for PRs, issues, READMEs'), which implies when to reach for it. However, it offers no exclusions and doesn't route the agent away from convert, compress, or export_preset when those might be the better fit.

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 destructiveHint=true and readOnlyHint=false, so the safety profile is known. The description adds useful encoding traits (aspect, fps, bitrate, faststart) but says nothing about whether an existing output file gets replaced or where files land, which is the destructive behavior an agent should be warned about.

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?

A single tight sentence that front-loads the verb and the output format. Nothing redundant or padded.

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?

An output schema exists so return values need no explanation, and every parameter is documented in the schema. However, for a tool flagged destructive with an overwrite option, the description should mention the overwrite/replacement behavior and output location to be fully 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 enum semantics for platform, fit, output, and overwrite are fully documented in structured data. The description only reiterates the platform-driven settings (aspect, fps, bitrate) already present in the schema, adding no new meaning.

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?

Specific verb (encode) plus resource (platform-ready H.264 file) and scope (a named platform), so the agent knows exactly what the tool produces. It doesn't distinguish itself from nearby siblings like export_gif or compress, which leaves some ambiguity about which export path to take.

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 offers no when-to-use conditions and never mentions alternatives such as compress, convert, or export_gif. The only implied usage is that the platform parameter drives the settings, which the schema already states.

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 destructiveHint=true and idempotentHint=false, so the write/overwrite risk is flagged by structured data. The description adds that output goes 'to its own file' and returns that path, but does not restate the overwrite default or warn that an existing file at the target path may be replaced — context that would matter for a destructive tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with no filler; the operation and formats come first. The trailing 'Returns the output path' is largely redundant given the tool has an output schema, costing it a perfect score.

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 a full-coverage schema, annotations covering the safety profile, and an output schema handling return values, the description is sufficient to call the tool correctly. The remaining gap is sibling disambiguation against convert and the audio-processing tools, which the description does not address.

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 input, format (including the 'copy' semantics), output, and overwrite default all documented inline, so the baseline is 3. The description only repeats the format enum already listed in the schema and adds no new meaning.

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 ('Extract') and resource ('audio track of a media file'), enumerates the supported output formats, and produces a distinct artifact ('its own file'), which separates it from siblings like convert, normalize_audio, and denoise. An agent can identify the operation without opening the schema.

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?

Usage is implied by the operation itself (pull the audio track out of a media file), but the description never says when to pick this over convert, which could plausibly also produce an audio file, or over normalize_audio/denoise for audio-only post-processing. No exclusions or prerequisites are named.

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 read-only, idempotent, non-destructive, closed-world, so safety is covered; the description adds the genuinely useful trait that OCR is best-effort and results should be reviewed. It also discloses the coordinate frame (image pixels vs. desktop coordinates) and the keep/delete capture behavior. It doesn't mention performance cost beyond the ~1 s/frame note carried in the schema.

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 sentences, front-loaded with what it does and what it returns before the use cases and the best-effort caveat. No filler and no repetition of schema fields.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 12 optional parameters, an output schema, and full annotation coverage, the description supplies exactly the missing layer: the three input modes (live target, file, video frames), the coordinate semantics of returned boxes, and the accuracy caveat. An agent can pick a mode and interpret results without further reading.

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 per-parameter meaning is largely already documented (query fuzziness, regex, redact, backend, scanEverySec, maxFrames). The description's added value is the coordinate-frame distinction, but it references an `origin` option that does not exist anywhere in the input schema, which risks sending the agent after a nonexistent 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?

States a specific verb+resource (OCR over screen, image, or video frames) and specifies the return artifacts: line and match boxes in image pixels. It also distinguishes itself from capture siblings (screenshot, sample_frames) and from redact_region by positioning its output as input to redaction.

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 concrete use contexts (locate UI text, hunt secrets via regex like 'sk-|ghp_|api.?key' for redaction) and points at the downstream redact_region tool. It lacks explicit when-not guidance, e.g. when to use transcribe or review_recording instead, or that video scanning should prefer sample_frames if full-clip OCR isn't needed.

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, non-destructive, closed-world, so the safety profile is fully covered. The description adds the mechanism (ffprobe) which hints at behavior on unsupported files, but does not say what happens on a missing/corrupt file or whether probing is slow for large media.

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?

One sentence, front-loaded with the verb and resource, then the return payload. No filler, nothing repeated from structured fields.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present and annotations fully populated, the description only needs to establish what the tool does and on what input, which it does. It stops short of covering failure modes or path requirements for a tool whose whole risk surface is 'file may not exist.'

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% with a single, well-documented 'input' path parameter, so the schema carries the load. The description adds nothing about accepted path forms (local vs remote, relative vs absolute) or whether the path must already exist.

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 (probe), a specific resource (a media file), the mechanism used (ffprobe), and enumerates the exact fields returned. An agent can distinguish it from siblings like get_session or read_events purely from the text.

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?

Usage is only implied: the agent can infer this is a pre-flight inspection step before convert/compress/trim, but the description never says when to call it versus alternatives or whether it is a prerequisite for other tools. No exclusions or prerequisites are stated.

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 read-only, idempotent, non-destructive behavior, so the safety profile is covered. The description adds useful behavioral context by saying it reports live status and checks whether the output file exists on disk, which is beyond what the annotations 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?

One front-loaded sentence with no filler. It conveys purpose and the two most important pieces of returned information without 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 one-parameter read-only lookup with annotations and an output schema, the description covers enough to call correctly and understand what it returns. It could be slightly stronger by noting behavior when the session is missing, but that is a minor gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There is one parameter with 100% schema description coverage, so the schema already explains that sessionId comes from start_recording. The description says 'by id' but adds no extra format, validation, or lookup semantics beyond the schema 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?

States a specific verb and resource: inspect a single recording session by id, and adds that it reports live status and output-file existence. This clearly distinguishes it from list_sessions or the recording-control siblings, though it does not explicitly name alternatives.

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?

Usage is implied: use it when you have a session id from start_recording and need to inspect that one session. There is no explicit when-to-use guidance, exclusions, or named alternative tool for related inspection needs.

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 destructiveHint=true and readOnlyHint=false, so the agent knows this writes/overwrites something. The description usefully identifies the written artifact, but it omits operationally important facts: that OCR is expensive, that results are cached (only visible in the force parameter's schema text), and what gets overwritten when an index already exists.

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?

A single front-loaded sentence with no filler; the artifact and the downstream purpose both come immediately.

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, return values need not be explained, and the six parameters are fully documented in the schema. The remaining gap is behavioral: cost, caching and overwrite semantics are not addressed despite destructiveHint=true.

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 every parameter including force, maxFrames, transcript and sceneThreshold is already documented. The description adds no parameter-level meaning beyond what the schema provides, so the baseline of 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?

A specific verb ('Build') and resource ('a recording's text timeline'), including the concrete artifact name (<video>.index.json) and its contents. It also names the downstream consumer, search_recording, which helps separate it from neighbors like transcribe or read_events, though it doesn't explicitly contrast with those 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 phrase 'for search_recording' implies this is a prerequisite for searching, but the description never says when to use it versus alternatives such as transcribe or chapters, nor when not to run it. Usage is implied rather than stated.

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 flag destructiveHint=true and non-idempotent writes, so the safety profile is covered. The description adds genuinely non-derivable behavior: it never renders typed text because the log contains none, which prevents an agent from expecting keystroke content and explains a privacy-relevant constraint.

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, zero filler, with the core action front-loaded and the prerequisite and privacy constraint trailing efficiently. Nothing could be removed without losing information.

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, return values need not be explained, and the description covers purpose, prerequisite, and the no-typed-text guarantee. The main residual gap is routing guidance against the other visual-overlay siblings, which keeps it from a 5 for a 13-parameter tool.

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 all 13 parameters are documented inline (keys modes, size, lingerSec, overwrite, etc.), so baseline is 3. The description only adds the events-log prerequisite, which is useful linkage but not parameter-level detail 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?

States a specific verb ('Burn keycast-style badges') and resource (shortcuts, clicks, typing) sourced from the recording's input event log, which cleanly separates it from sibling overlay/callout/cursor tools. The parenthetical about start_recording events: true further pins down what it operates 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?

Gives the essential precondition — the recording must have been made with start_recording events: true — which is a real gating condition an agent needs before calling. It stops short of naming alternatives (e.g., overlay or cursor) or when NOT to use it, so it falls just short of a 5.

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 closed-world behavior. The description adds meaningful context beyond that: it enumerates DirectShow audio devices and applies a loopback heuristic (Stereo Mix or virtual-audio driver).

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?

A single tight sentence front-loads the action and resource, then adds the loopback flagging and downstream use case without 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 zero-parameter listing tool with an output schema, the description supplies enough to invoke and interpret it: what is listed, what the likely loopback flag means, and where its results belong. The output schema can carry return-value details.

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?

There are zero parameters, so the baseline is 4. No parameter guidance is needed or missing.

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 ('List DirectShow audio devices') and adds the key behavioral detail that it flags a likely loopback device. It is clearly distinguishable from sibling list_video_devices and other recording 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?

It explicitly ties the tool to start_recording's audio.device, telling the agent when this list is useful. It does not name exclusions or alternatives, but the intended workflow context is 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, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds useful behavioral detail beyond that — that both active and finished sessions are returned, and that each carries a live-process flag — but says nothing about ordering, volume, or cost of the call.

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?

A single front-loaded sentence with the resource first, scope second, and returned fields last. Every clause carries information and nothing is padded.

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, the description does not need to explain return values, and annotations cover safety; the field enumeration is mildly redundant but harmless. The one real gap is the lack of a routing hint versus get_session for a toolset with 50+ siblings.

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 takes no parameters, so the baseline is 4; the description correctly implies a no-argument, list-everything call rather than hinting at filters that don't exist.

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?

Specific verb+resource: "List all recording sessions", with scope narrowed to "(active and finished)" and a preview of the returned fields. It does not explicitly distinguish itself from the sibling get_session, which is the one obvious source of confusion for an agent choosing between 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?

Usage is only implied by the word "all" and the parenthetical scope; there is no statement telling the agent to use this instead of get_session when it already knows an ID, nor any prerequisite or ordering 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 the tool is read-only, idempotent, non-destructive, and closed-world. The description adds useful behavioral context beyond annotations: ordering is topmost first, capturability is included per backend, and entries expose a pass-through `target` string.

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 compact sentences, front-loaded with what is listed and followed immediately by how to use the returned `target`. Every sentence contributes directly to selection or 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?

The tool has an output schema, so the description need not explain return values. With complete parameter documentation, annotations covering safety, and a clear statement of contents and intended use, the definition 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?

Schema description coverage is 100%, so the schema fully documents the three filter parameters. The description does not add parameter-specific meaning, which is acceptable given the schema already carries that information.

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

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb and resource set: it lists desktop, monitors, and visible windows. It also clarifies the key output field (`target`) and how it relates to capture tools, which distinguishes it from sibling capture/manipulation 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?

It gives clear usage guidance: pass the returned `target` as-is to capture tools and use this instead of guessing a title. It does not explicitly describe when not to use the tool or name a sibling alternative, but the intended workflow is 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, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description adds the useful 'DirectShow' qualifier (implying a Windows-only enumeration) but nothing on return shape or failure modes. With annotations carrying the behavioral burden, a 3 is appropriate.

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?

A single sentence with zero filler. The resource and the consumer are front-loaded, so an agent can act on it immediately.

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?

An output schema exists, annotations are rich, and there are no parameters, so the description need not explain return values. The only small gap is that it doesn't say whether a DirectShow/platform prerequisite could make the list empty or fail, but for a zero-arg enumeration tool this is nearly 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?

The tool takes zero parameters and schema coverage is 100%, so the baseline is 4. No parameter-level explanation is needed.

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 (List) and a specific resource (DirectShow cameras), and ties the output to a concrete consumer: start_recording's webcam.device. This distinguishes it from sibling device-enumeration tools like list_audio_devices and list_targets without needing to open any schema.

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 'for start_recording's webcam.device' tells the agent exactly when to call it: to obtain a valid device value before starting a recording. It does not explicitly name exclusions or alternatives, but the intended workflow is unambiguous.

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

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

Annotations already declare destructiveHint=true and non-idempotent, and the description adds genuinely new behavioral context: the video is stream-copied (no re-encode, fast and lossless for video), and music is looped or trimmed to fit. It does not restate overwrite semantics, which the schema covers, but the stream-copy disclosure is a real behavioral detail an agent would otherwise not know.

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?

A single sentence, front-loaded with the core action and followed by the transforming operations, with zero filler. Every clause carries information.

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 full schema coverage, an output schema, and rich annotations, the description supplies the remaining important context — stream copy and music fitting behavior. Only the interaction between duck and musicVolume defaults is left implicit, a minor gap for an audio-mixing tool.

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 every parameter is already documented with types, defaults, and ranges. The description gestures at the parameters semantically ('faded, leveled', 'mixed with any existing audio' hinting at duck/musicVolume) but adds no format or syntax detail beyond the schema, so 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?

States a specific verb and resource — lay music under a video — and enumerates the operations performed (loop/trim, fade, level, mix). It is clearly distinguishable from siblings like normalize_audio or extract_audio because no sibling performs music-overlay mixing, though it never names a contrasting sibling.

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 implies when the tool applies (adding background music to an existing video) but gives no explicit when-to-use/when-not guidance and no reference to alternatives such as normalize_audio or duck-related options. The agent must infer the selection context from the tool name and purpose alone.

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 adds useful context beyond the annotations by disclosing that narration uses built-in Windows voices, works offline, and also produces an SRT. It does not mention the destructive/overwrite behavior signaled by destructiveHint=true or the overwrite default, leaving those details to the schema and 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 single sentence is front-loaded with the core purpose and contains no filler. Every phrase contributes to describing the voiceover mechanism, timing behavior, and SRT output.

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 schema coverage, annotations, and presence of an output schema, the description is mostly complete for an agent to understand the tool's role. It does not mention the required video path or overwrite implications, but those are adequately covered by the schema and annotations.

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 high at 86%, so the baseline is 3, but the description adds meaningful semantics for the nested lines array by explaining that each line is spoken at its time or marker. It also clarifies the audio-overlay and SRT output behavior, though it does not discuss rate, duck, or overwrite 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 gives a specific verb and resource: it produces an offline voiceover using built-in Windows voices and speaks each line at its time or marker. This clearly separates it from sibling audio tools like music_bed, transcribe, or burn_subtitles, though it does not explicitly name alternatives.

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?

Usage is implied by the phrase 'offline voiceover' and the explanation that lines are spoken at timestamps or markers. However, the description does not state when to use this tool instead of related siblings such as music_bed, transcribe, or burn_subtitles, nor does it give any exclusion conditions.

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 destructiveHint=true and readOnlyHint=false, so the description is not responsible for the safety profile. It adds useful behavioral context beyond the annotations: two-pass EBU R128 processing, video copy-through, and before/after loudness reporting.

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?

One compact sentence with the core operation front-loaded and no wasted text. The parenthetical implementation detail earns its place by clarifying the loudness standard.

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 a full schema, annotations, and an output schema, the description is nearly complete for correct invocation. It could mention overwrite or output-default behavior, but those are already covered in the 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?

Schema description coverage is 100%, so the schema already documents all four parameters, including target enum values and LUFS meaning. The description reinforces the delivery-target concept but adds no parameter-level detail 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?

States a specific verb and resource ('Normalize loudness'), names the delivery-target concept, and distinguishes itself from sibling audio transformations by describing the exact standard (two-pass EBU R128) and the handling of video ('video is copied').

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 delivery-target framing implies this is for final loudness compliance, but the description gives no explicit when-to-use/when-not guidance and does not name alternatives such as denoise or compress.

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 destructiveHint=true, idempotentHint=false, and readOnlyHint=false, so the write/irreversibility profile is covered. The description adds genuinely new behavioral facts: the base's audio and length are preserved and the overlay can be scaled and time-limited, which an agent could not infer from annotations or schema. It stops short of stating that a new output file is produced rather than the input being modified in place.

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?

A single front-loaded sentence packs the verb, the two media roles, the placement, and the preservation guarantee with no filler. The semicolon clause is the one piece of information an agent most needs after the action itself, so nothing needs reordering.

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, return values need no explanation, and annotations carry the destructive/non-idempotent profile. The description covers the key semantic guarantee (audio and duration preserved). The only gap is not clarifying that results land at a new output path by default versus mutating the input, though the schema's output/overwrite parameters hint at 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 description coverage is 100% across all 11 parameters, so the schema already documents x/y as pixel offsets, start/end as time bounds, and width/height as scale factors. The description only echoes those concepts at a high level ('pixel position, optionally scaled and time-limited') without adding format or edge-case detail. 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?

Names a specific verb ('Composite') and resources ('image or video ... onto a video') and clarifies intent with concrete parenthetical examples (logo, watermark, picture-in-picture). It implicitly separates itself from overlay-adjacent siblings like keystroke_overlay or callout by restricting input to an arbitrary image/video file, but it never explicitly names or contrasts those 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 examples (logo, watermark, picture-in-picture) imply when to reach for this tool, but there is no explicit when-not guidance, no mention of prerequisites (e.g., need a base video already), and no routing to alternatives such as keystroke_overlay, title_card, or backdrop for other overlay types. Usage is only inferable.

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 this is a non-read-only but non-destructive, idempotent mutation. The description adds real value beyond them by disclosing the consequence: capture halts and the gap is excluded from the output file, events, and markers. It stops short of describing edge cases such as pausing an already-paused or stopped session.

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?

A single front-loaded sentence with the action first and the consequence second; no sentence is 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?

An output schema exists, so return values need no explanation, and the annotations carry the safety profile. The description covers the essential behavior; only failure/edge-case behavior for invalid session state is absent.

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?

Only one parameter exists and schema description coverage is 100%, with the schema even noting it comes 'From start_recording.' The description adds nothing about sessionId, so the baseline 3 applies when the schema does all the work.

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

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Pause a recording') and immediately names the paired sibling resume_recording, so the agent can distinguish it from stop_recording or save_replay 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 clause 'until resume_recording nothing is captured' establishes the usage context and the pairing that selects this tool over stop_recording. There is no explicit exclusion (e.g., what to do if the session is already stopped), but the correct moment to call it is 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 destructiveHint=true and non-idempotent, and the description adds genuinely new behavioral context: the whole pipeline runs as a single re-encode with no intermediate files, which affects failure cost and output quality. It doesn't expand on overwrite/output-file clobbering, but the schema's overwrite param covers that, so the gap is minor.

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, purpose and mechanism first, preference guidance second. The parenthetical op list is dense but earns its space by signaling breadth. 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?

With an output schema present, annotations covering the safety profile, and fully described parameters, the description needs only to convey purpose and selection guidance, which it does. A brief note that a recipe can substitute for hand-built steps would round it out, but an agent has enough to act 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% and each step variant is fully documented in the schema itself, including ordering and relative-time semantics, so the description's step list largely restates structured data. It adds the useful constraint that export steps must be last, but nothing about parameters beyond that. 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 action (run multiple edits in one ffmpeg pass) and enumerates the supported edit ops, so an agent can immediately see it subsumes the individual edit siblings. The 'one re-encode, no intermediate files' line pins down the distinguishing mechanism.

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?

'Prefer it over chaining edit tools; a recipe does the usual polish in one call' explicitly names the alternative pattern and prescribes when this tool wins. This is the rare case of a stated when-to-use with a named competitor strategy.

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