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

With no annotations, the description carries the full burden. It does add one useful trait — 'two-pass', implying two ffmpeg runs and longer runtime — but says nothing about overwrite behavior on the output path, supported formats/container constraints, failure modes, or what is returned. For a tool that writes a file, that is a significant gap.

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 with the operation and default target front-loaded, no filler. It is efficient, though the terseness leaves behavioral gaps that a second short clause could have closed.

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?

Four parameters with two required, no annotations, and no output schema: the description should therefore explain what happens to the output file and what the caller gets back, but it does neither. For a mutating media-processing tool it is under-specified.

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 all four parameters are already documented in the schema, including the -14 LUFS and -1.5 dBTP defaults. The description repeats the targetLufs default rather than adding new meaning, 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: 'two-pass loudness normalization of a media file' with a concrete target ('integrated loudness, default -14 LUFS') and names the underlying mechanism ('ffmpeg loudnorm'). It is not differentiated from siblings like audio.measure or audio.mix, which an agent could plausibly confuse with normalization.

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 sentence telling the agent when to pick this over audio.measure (measure loudness) or audio.mix, nor any prerequisite or exclusion (e.g. 'run after audio.mix', 'do not use on already-normalized files'). Usage is only inferable from the purpose statement itself.

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?

With no annotations, the description carries the full behavioral burden; it does disclose that this is a loudnorm-based measurement and names the three metrics, which implies a read-only analysis. However, it does not say the call is non-destructive, whether it decodes the whole file (cost/latency), or how results are returned.

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 the returned metrics, no filler. Every clause (metrics, media file, ffmpeg loudnorm) contributes 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?

For a one-parameter read tool with no annotations and no output schema, the description names the three returned values with units, which is most of what an agent needs. The remaining gap is the shape of the response (structured fields vs raw ffmpeg output), which is never 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?

There is a single parameter with 100% schema description coverage ('Path to a local audio or video file'), so the schema already does the work and the baseline is 3. The description adds nothing about the input beyond what the schema states.

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

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

Specific verb (measure) plus the exact resource set (LUFS, dBTP, LRA) and the underlying mechanism (ffmpeg loudnorm), so an agent knows precisely what it gets back. It does not explicitly contrast itself with the sibling audio.loudnorm, so differentiation is left to inference from the verb 'measure' vs 'normalize'.

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: an agent can infer 'use this when you need loudness numbers rather than to fix them,' but the description never states when to call this versus audio.loudnorm, probe, or transcribe. No preconditions or exclusions are given.

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?

With no annotations, the description carries the burden and does so usefully: it discloses that the video stream is copied (not re-encoded) while audio is re-encoded, which is exactly the kind of behavioral fact an agent needs. It omits overwrite semantics for the output path, supported formats/codecs, and what happens if the video has no audio track.

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, front-loaded with the core operation, then the stream-handling detail, then the optional features. Every sentence earns its place with zero filler.

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

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

For a 7-parameter tool with a nested object and no annotations or output schema, the description explains the mechanism and the container/codec trade-off well. It stops short on the return value and on error/overwrite behavior for the output path, which matters since no output schema exists.

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 including the nested duck object are already documented. The description adds only the concepts of ducking and optional fades, which the schema already covers in more detail; it provides no extra syntax, ranges, 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?

States a specific verb (mix), the exact resources involved (a video's voice track plus background music), and the mechanism (sidechain-compressor ducking). This is clearly distinguishable from sibling audio tools like audio.loudnorm (normalization) and audio.measure (analysis).

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 intent — combine voice with music under ducking — is implied clearly, but there is no explicit when-to-use/when-not guidance and no reference to the sibling audio tools it could be confused with (e.g. audio.loudnorm for leveling without a music bed). Nothing tells the agent when to prefer this over a loudnorm-plus-mix sequence.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It identifies generated formats but does not state whether the output file is overwritten, whether directories are created, what permissions are needed, or that one of transcript/srt is effectively required despite the schema only requiring format and output.

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 colon and parenthetical pack format and style details efficiently. It is slightly dense but every clause carries useful 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 10 parameters and no annotations or output schema, the description covers purpose, main inputs, and outputs but omits prerequisites such as requiring transcript or srt, overwrite semantics, and differentiation from captions.render. It is adequate but leaves notable gaps for an agent to call it safely.

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 10 parameters and baseline is 3. The description maps 'karaoke word highlight, word-pop, background box' to style options and mentions SRT input/output, adding conceptual clarity but no 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?

States a specific verb and resource, 'Write captions,' and enumerates input sources and output artifact types (srt, ass, HyperFrames HTML). It does not name or differentiate from the sibling captions.render, so the agent cannot fully rule out the alternative from the description alone.

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 'from transcription segments or an SRT file' implies usage when those inputs exist, and the output formats give context. However, there is no explicit when-to-use/when-not guidance and no mention of the captions.render sibling as an alternative.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions engine behavior and that audio is kept, but omits key mutation traits: that it writes an output file, implications of the `overwrite` parameter, whether permissions are needed, and what happens on failure or success. For a 13-parameter rendering tool with no annotations, this is a significant gap.

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 sentences with no wasted words, and the main purpose is front-loaded. The third sentence is slightly awkward but efficiently covers input options and the engine-specific composition path.

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

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

Given the complexity (13 parameters, no output schema, no annotations), the description covers purpose and engine choice but lacks sibling routing guidance and return value information. It is adequate but leaves gaps an agent would need to infer.

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. The description adds marginal value by naming the input types (transcript, SRT, composition) and clarifying that composition is for the hyperframes engine, but it does not add syntax or constraints beyond what the schema provides.

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

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

The description states a specific verb (burn) and resource (captions onto a video) and mentions the two engines. It does not explicitly differentiate itself from siblings like `render` or `captions.generate`, but the purpose is clear enough for an agent to understand what it does.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage by listing accepted input types (transcription segments, SRT, composition path) but provides no explicit when-to-use versus alternatives or exclusions. It does not mention when to choose this tool over `render` or `captions.generate`.

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?

No annotations are provided, so the description carries the full burden. It usefully discloses the peer-dependency and headless-Chrome requirement plus an 'unavailable' error path, which is real behavioral value. It omits whether the render is long-running/blocking and whether writing to 'output' overwrites an existing file, which matters for a write-producing 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 sentences, front-loaded with the core action, followed by the environmental prerequisite. No filler, and both sentences carry new 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?

For a 5-parameter tool with no output schema, the description covers the action and the key environmental prerequisite. The remaining gap is the unexplained 'quality' enum and overwrite behavior on 'output', but overall an agent could call this correctly.

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

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

Schema description coverage is 80%, so the schema already documents composition, output, fps, and format. The description adds no parameter-level detail, and the undocumented 'quality' enum is left without explanation in either place. Baseline 3 is appropriate given the strong 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 and resource: renders a HyperFrames HTML composition to video. Clear enough for an agent to grasp the output. However, it does not distinguish itself from the sibling tool 'render', leaving ambiguity about which produces video from a composition versus other media.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives a precondition ('Needs the optional peer @hyperframes/producer and headless Chrome') and the failure mode, which implies when the tool will not work. It never says when to choose compose over render or any other sibling, so routing must be inferred.

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?

No annotations are provided, so the description carries the full burden. It usefully discloses what normalization actually does (scales/pads resolution, fps, audio), which is real behavioral context, but it omits failure behavior, permission/overwrite risk, and what happens when normalization is disabled.

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 waste, with the core action front-loaded and the qualifier about normalization immediately after. Nothing is redundant or 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?

There is no output schema and no annotations, and the description says nothing about the returned result, error cases, or the destructive potential of overwriting an existing output. Adequate for a basic call, but incomplete for a mutation tool with a default-on transformation.

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 four parameters are already documented in the schema. The description's normalization sentence adds a little semantic depth beyond the schema's wording but does not address ordering of `inputs` or the overwrite flag; 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 ("Join several media files into one") and clarifies the normalization step, so the operation is unambiguous. It does not explicitly contrast with siblings like compose or render, but the join semantics are distinct enough to distinguish it from trim/cut.

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 joining semantics (use when you need one continuous file from multiple inputs), but there is no explicit when-to-use/when-not guidance, no mention of alternatives like compose, and no prerequisites such as compatible codecs or matching stream layouts.

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?

With no annotations, the description carries the full burden. It does disclose one meaningful trait beyond the schema — 'always re-encoded', which warns the agent that output is lossy/reslowered rather than stream-copied. It omits other behavioral facts a mutation tool should state: that output is written to a new path (overwrite semantics are only in the schema), whether source files are modified, and what quality/profile the re-encode uses.

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 two operative constraints ('one file', 'always re-encoded') appear 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?

No annotations and no output schema mean the description must carry behavioral context, and it covers only the re-encode trait. For a four-parameter media-writing tool, it should also state that nothing is written unless output path is set, how overwrite interacts with an existing file, and how it differs from trim before an agent can call it confidently.

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 including segment start/end units and the overwrite default is already documented in the schema. The description's 'in order' duplicates the schema's 'Ranges to keep, in output order' and adds no new parameter meaning, 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?

States a specific verb and resource: keeps listed ranges of one file and joins them. The phrases 'one file' and 'in order' implicitly separate it from the multi-file concat sibling, but no sibling is named, so an agent must infer the boundary with trim/concat.

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 tool is for extracting multiple ranges from a single source. There is no explicit statement of when to prefer it over trim (single segment) or concat (multiple files), and no prerequisites or exclusions are given.

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?

With no annotations, the description must carry the behavioral load; it does disclose the side effects of the archive contents (spec.json with measured duration/resolution/fps/codecs/loudness/preset, checksums.sha256), which is genuinely useful context. It omits failure/mutation semantics: whether an existing output errors out, that overwrite is required to replace it, and that loudness normalization may run before packaging (that only appears 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?

One sentence, front-loaded on the action, with the payload as a compact parenthetical list. Every listed item earns its place, though the dense enumeration slightly slows scanning.

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

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

For a 7-parameter tool with a nested object and no annotations or output schema, the definition covers the produced archive well. It stops short of the delivery-critical edge cases: overwrite behavior, error conditions, and whether loudness normalization is applied at export time versus inherited from a sidecar.

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 baseline is 3; every parameter is already documented including defaults and ranges. The description adds the framing that captions become captions.srt and that spec.json records loudness/preset, but no syntax or format guidance 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?

A specific verb ('Build a delivery ZIP') plus an enumerated manifest of what goes in it: media file, captions.srt, spec.json, checksums.sha256. This is clearly distinct from render/transcribe/captions.render, though it never names a sibling to contrast against.

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?

Delivery packaging is implied by 'delivery ZIP' and the checksum/spec contents, but there is no explicit when-to-use, no prerequisite (e.g. 'after render'), and no statement about what happens if the .zip exists (overwrite is only in the schema).

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?

No annotations are provided, so the description must carry behavioral disclosure. It implies a non-mutating diagnostic that reports availability and versions, but it does not explicitly state side-effect behavior, latency, or what happens when a backend is missing.

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 efficient sentence with the key resources and return information front-loaded. There is 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?

For a simple zero-parameter tool this covers the core purpose, but with no output schema and no annotations the description should ideally explain the report format and failure behavior. It says versions are included but not whether availability is returned as booleans, paths, or error states.

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 are no parameter semantics to explain. The schema is empty and requires no compensation from the description; baseline 4 applies.

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

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

The description uses a specific verb (Report) and names the exact resources checked: ffmpeg/ffprobe and a local Whisper backend, plus versions. This clearly distinguishes it from the sibling media-operation tools like render and transcribe.

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 name and description as a diagnostic/preflight check, but the description does not explicitly say when to call it, when not to, or that it should precede tools like render or transcribe.

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?

No annotations are supplied, so the description carries the full burden. It does the most important part by naming the returned fields (which substitutes for the missing output schema), and 'Inspect' implies a non-destructive read, but it never explicitly states the file is unmodified, nor how it behaves on unsupported/corrupt containers or missing files.

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 a colon-delimited field list — no filler, and the highest-value information (what it inspects and what it returns) arrives 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?

For a one-parameter read tool with no annotations and no output schema, the description covers the essentials and compensates for the missing output schema by listing return fields. Minor gaps remain around error/unsupported-format behavior, but nothing an agent strictly needs to invoke it correctly is missing.

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

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

There is a single required parameter, and the schema already documents it at 100% coverage ('Absolute or relative path to a local media file'). The description adds nothing about path semantics (remote URLs, symlinks, tilde expansion), 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?

Names a specific verb (Inspect) and resource (a local media file) and then enumerates exactly what it yields: container, duration, size, per-stream codec/resolution/fps/audio. That enumeration makes it unmistakable as the metadata-read tool among mutating siblings like trim, cut, concat, or transcode.

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 rather than stated: an agent can infer this is the read-only first step before trim/cut/render, but the description never says when to reach for probe versus a sibling, nor any when-not-to-use condition or prerequisite (file must exist, container must be supported).

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?

With no annotations, the description carries the full load. It does disclose useful behavior beyond the schema: that focusX/focusY only bias the crop in crop mode, and that "follow" invokes an optional, lazily-loaded face detector, hinting at added latency. It omits that this is a compute-heavy write operation producing a new file, and says nothing about output overwrite semantics or failure modes.

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

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

Three tight sentences with the verb, targets and mode list front-loaded. Minor redundancy: the mode enumeration restates the schema enum and the per-parameter mode descriptions, so a few words could be cut.

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 10-parameter tool with no annotations and no output schema, the description covers modes, crop focus and subject tracking adequately, and the schema fully documents defaults and ranges. It leaves the write-side story (overwrite behavior, cost of processing long videos) unaddressed, which is the main remaining 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 coverage is 100%, so the baseline is 3, but the description adds interaction semantics the schema's per-field text does not: focusX/focusY are gated to crop mode, and "follow" is a time-varying subject tracker rather than a static offset. That crossover context is genuine added value.

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 ("Reframe a video") plus the exact target aspect ratios and the three supported modes. No sibling (trim, cut, compose, render) does reframing, so an agent can route here decisively 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?

The description establishes the default mode ("centered crop (default)") and mode-specific constraints, which helps pick a mode, but it offers no guidance on when to choose reframe over siblings like render or compose, nor any prerequisites. 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?

With no annotations, the description carries the full burden, and it discloses substantial behavior: preset codecs, overlay clamping and warnings, captions burned after composition, two-pass loudness normalization, and measured return values. It omits some operational side effects, such as overwrite behavior and likely processing cost, but the core behavior is well explained.

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

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

The description is front-loaded with the primary action and then covers presets, layers, captions, timeline stills, loudness, and returns in one dense paragraph. Every clause carries information, but the single-block structure and long parentheticals make it harder to scan than it could be.

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 12-parameter tool with nested objects, no annotations, and no output schema, the description is substantially complete: it explains presets, composition layers, captions, timeline behavior, loudness normalization, and return fields. The main gaps are operational details such as overwrite semantics and processing cost, which the schema only partially covers.

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 the parameters thoroughly. The description adds conceptual grouping and some cross-parameter behavior, such as layers being timed, stacked, and clamped, but it does not need to compensate for schema gaps and mostly restates the structured model.

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 specific verbs and resources: encoding a file, assembling a timeline, applying a fixed delivery preset, compositing layers, burning captions, and normalizing loudness. It clearly distinguishes the tool from a simple transcoder, but it does not explicitly separate it from siblings such as compose, trim, cut, or captions.render.

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 opening phrase implies usage contexts: encoding with a fixed delivery preset or assembling a timeline. However, there is no explicit when-to-use guidance, no when-not-to-use guidance, and no named alternatives among the many sibling tools. The agent must infer the routing decision from the feature list.

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?

With no annotations, the description carries the full burden and does reasonably well: it discloses the internal pipeline (ffmpeg resample to 16 kHz mono) and the return payload (segments plus word-level timestamps). It omits operational traits such as runtime cost, model availability failure modes, and any length limits.

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 action, the backend constraint, the preprocessing step, and the return shape all appear in order of importance.

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 no annotations and no output schema, the description usefully covers both the processing behaviour and what comes back, which is the main gap a missing output schema creates. Remaining gaps are minor: no failure modes (e.g. missing ggml model file) and no performance expectations.

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 four parameters are already documented in the schema. The description only echoes the backend concept and the word-timestamp output, adding no syntax, defaults, or edge-case meaning beyond the structured fields.

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 (transcribe) and resource (local audio or video file) plus the implementation (local Whisper backend, whisper.cpp or faster-whisper). It is clearly distinguishable from siblings like render or audio.mix, but it never explicitly contrasts with captions.generate, the closest neighbour.

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 repeated emphasis on 'local' implies the tool operates on on-disk files with an offline backend, which implicitly excludes remote/URL sources. However, there is no explicit statement of when to choose this over captions.generate, nor any prerequisite or exclusion 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?

With no annotations, the description carries the burden well by disclosing a genuinely non-obvious trait: stream-copies on keyframe boundaries and re-encodes otherwise, which signals a speed/quality tradeoff an agent would not learn from the schema. It stops short of stating that the tool writes a file (with overwrite semantics) or what happens on invalid ranges.

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 zero waste; the core action is front-loaded and the behavioral caveat follows. Nothing extraneous 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 6-parameter mutating tool with no annotations and no output schema, the description covers mechanics but omits output information (what is returned, e.g. output path), error conditions on out-of-range start/end, and the fact that existing files are only replaced when overwrite is set.

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 input/start/end/output/reencode/overwrite are already documented. The keyframe sentence adds context for why reencode is auto-detected, but provides no additional syntax, units, 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 concrete verb and resource: 'Cut one range out of a media file.' The qualifier 'one range' hints at a single-clip operation, but with a sibling literally named 'cut' the description never explicitly differentiates itself, leaving ambiguity an agent must resolve elsewhere.

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 explicit when-to-use or when-not-to-use guidance, and it does not name alternatives like 'cut', 'concat', or 'render'. Usage is only implied by 'one range' and the keyframe note, which is minimal inference-heavy guidance.

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