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

With no annotations, the description carries the burden, and it usefully discloses the auto-normalization of resolution/fps/audio rate plus that clips need not match — meaningful behavior not visible in the schema. It does not mention that a new file is written to disk, how existing outputs interact with `overwrite`, or any failure modes for mismatched/unreadable clips.

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 operation first and the normalization caveat second; nothing is 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?

For an eight-parameter, no-annotation, no-output-schema tool, the description plus fully documented schema covers what an agent needs to invoke it. The gap is selection guidance against `concat`/`xfade_transition` and the on-disk side effect, both minor given the schema's `output` and `overwrite` docs.

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 eight parameters (fps, width, height, output, duration, overwrite, transition, clips) are already documented inline. The description only restates normalization and transition semantics already present in the schema, adding no syntax, format, or constraint detail beyond 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?

States a concrete verb and resource ("stitch two or more clips into a single video") plus the available transition modes, so an agent can tell what it produces. However, it never distinguishes itself from the closely overlapping siblings `concat` and `xfade_transition`, which is the main ambiguity for selection.

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 requirement of two or more clips and the cut-vs-xfade choice imply when the tool applies, but there is no explicit statement about when to prefer it over `concat` or `xfade_transition`, nor any preconditions. Usage must be inferred from the tool name and sibling 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; it does disclose the two genuinely important traits — the burn is permanent and the result is a path under SCREENCAST_HOME/edits. It says nothing about processing time, required tooling, failure modes on bad SRT timing, or whether the source video is untouched.

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 purpose, accepted inputs, styling, and return value; no filler and no repetition.

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?

Everything needed to invoke it — input, subtitle file, style enum, output default, overwrite semantics, and return value — is covered between the description and the fully documented schema. Only operational edge cases (encoding cost, corrupted subtitles) are 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?

Schema description coverage is 100%, so every parameter is already documented, and the enum for style is exhaustively explained in-schema (including the default). The description only echoes the style choice and font bundling, adding little 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 ("Burn subtitles ... permanently into a video") and names the upstream producer ("an SRT from transcribe"), which implicitly separates it from transcribe and from other video-mutation siblings. It is clear, but it does not explicitly contrast itself with any alternative like overlay or convert.

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 prerequisite (an existing SRT/ASS file, e.g. from transcribe) but never states when to choose this over other compositing tools such as overlay, or what happens if the input has no matching subtitle timing. Usage is inferable 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?

No annotations are provided, so the description carries the full behavioral burden. It states that annotations are shown between timestamps and that the output path is returned, but it omits side effects such as whether the source is modified, default overwrite behavior, maximum item count, and ordering semantics.

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

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

The description is concise and front-loaded: it names the action, gives examples, explains timed visibility, and notes the return value. 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?

The schema is rich and fully documented, and the description states the return value. However, for a write/create operation with no annotations, it could do more to clarify side effects and distinguish this tool from nearby video-editing 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?

Schema description coverage is 100%, so the schema already documents all parameters and item types in detail. The description reinforces the high-level annotation types and timestamp visibility, but adds little parameter-level meaning beyond the schema.

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

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

The description states a specific verb and resource: annotate a video with timed boxes, text labels, and arrows. The examples make the behavior concrete, but it does not distinguish this tool from related siblings such as 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?

It gives examples of what can be annotated but does not explain when to use callout versus alternatives like overlay, title_card, or burn_subtitles. There are no explicit inclusion or 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?

With no annotations, the description carries the behavioral burden and usefully discloses that clip re-encodes rather than stream-copies, and that it produces separate output files. It could add more about the performance cost of re-encoding, but the core behavioral distinction is clearly stated.

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 no wasted language. The purpose is front-loaded and the sibling comparison follows immediately, making it easy to scan.

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 a fully described schema and no output schema, the description provides enough context to select and call the tool correctly. It omits some file-output details such as where multi-segment output lands, but those are 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 input, output, segments, start/end times, and overwrite semantics. The description reinforces the notion of one or more segments and exact times, but adds no parameter details 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: extracting frame-accurate sub-segments into separate files. It also explicitly distinguishes itself from trim, making the tool's role clear without needing to inspect 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?

Directly names the relevant alternative, trim, and explains the selection condition: trim is a fast stream copy that snaps to a keyframe, while clip re-encodes for exact cuts. This gives an agent clear guidance on when to choose clip over trim.

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 burden. It discloses the key traits: this transcodes (hence lossy, quality-affecting) via a CRF ladder and returns the output path, but it says nothing about overwrite/destructive behavior, failure modes (e.g., existing file at output when overwrite=false), or that the operation is potentially long-running.

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 filler: the transformation and its knobs come first, and the return value is stated last. Every clause earns its place.

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

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

There is no output schema, and the description correctly states what is returned (the output path). Parameter docs are complete in the schema. The remaining gap is operational context — whether re-encoding loses quality irrecoverably and what happens on path collisions — which would be valuable for a write-producing media 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 five parameters are already documented with defaults, enum values, and constraints. The description only echoes this at a high level ('CRF quality ladder', 'optional width cap') without adding new syntax, ranges, or interaction rules 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 ('Re-encode a video to a smaller file') plus the mechanism (CRF quality ladder, width cap). It is clearly distinguishable in intent from siblings like convert, scale, or export_preset, though it never names them 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?

There is no guidance on when to pick this over convert, export_preset, or scale, despite a dense sibling set that overlaps heavily. The user must infer from the name and 'smaller file' phrasing that this is the size-reduction tool rather than a generic format conversion.

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 and does so well: it discloses stream-copy versus re-encode behavior, names the exact incompatibility triggers, mentions edit-list hidden frames, guarantees a valid output file, and says the result exposes the mode used.

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 dense, front-loaded sentences with no filler. The main action comes first, followed by the important behavioral caveat about matching versus differing inputs.

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 there are no annotations and no output schema, the description supplies the behavioral context an agent needs: join order, stream-copy vs re-encode behavior, hard-cut fallback, guaranteed validity, and a result indicator. Missing details like default output path are already covered by 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 coverage is 100%, so the baseline is 3 even without description-level parameter exposition. The description adds meaningful semantics beyond the schema by explaining how input compatibility affects processing and that `mode` in the result reports which path was taken.

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: concatenate two or more videos into a single file. The purpose is immediately clear, but the description does not explicitly distinguish this tool from sibling video-editing tools such as xfade_transition or clip, so it stops 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?

The description implies when concatenation applies and explains the matching-vs-mismatched input behavior, which helps an agent understand consequences. However, it gives no explicit when-to-use/when-not guidance or named alternatives for joining clips with transitions or extracting segments.

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 does disclose the return behavior ('Returns the image path and the sheet inline') plus the poster variant. It omits the write-to-disk/destructive nature (overwriting a file) and any permission assumptions, which matter for an unannotated tool that writes 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?

Three tight sentences with the core action front-loaded, followed by the return and poster details. No wasted filler, though the poster clause is slightly compressed against the main description.

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

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

For an 11-parameter media tool with no output schema, the description covers the primary action, both modes, the poster variant, and the return format. Remaining parameter detail is fully handled by the 100%-covered schema, so an agent has enough 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 coverage is 100%, so all 11 parameters including modes, count caps, and thresholds are already documented in the schema. The description reinforces mode and poster semantics but adds little beyond what the schema provides; baseline 3 applies 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?

Specific verb+resource: 'Tile timestamped frames of a video into ONE image', with the even/scenes modes and poster alternative spelled out. The 'whole recording in a single look' framing clarifies intent, but it never names the nearest sibling (sample_frames) to draw the boundary.

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 'evenly spaced, or at the scene changes' and 'poster: true writes a single representative frame instead' phrases imply when each mode is appropriate. However, there is no explicit when-to-use versus alternatives like sample_frames, zoom, or screenshot, leaving the selection to inference.

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

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

No annotations are provided, so the description carries the full burden; it does disclose codec choices (H.264, VP9, palette filter) and that the return value is an output path, which is real added value. It omits the mutation profile — no mention of file overwrite semantics (only in schema), whether a new file is always created, whether SCREENCAST_HOME/edits is created, or how long a transcode might take.

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 front-loaded with the actionable information: what it does and what it returns. Nothing is wasted and no filler adjectives are present.

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 and an explicit return-value sentence, an agent has what it needs to call this correctly. The gap is routing context — given seven-plus sibling tools that also produce output files, the description should have stated the selection rule, but that is a usage gap rather than a missing operational fact.

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 already carry documentation, including defaults, ranges, and the gif-only constraint on fps/width. The description adds only codec background that the format enum description also restates, so 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 and resource ('Convert a video') plus the exact format set (mp4, gif, webm), which is concrete enough to act on. It does not differentiate itself from overlapping siblings such as export_gif or export_preset, which also produce gif/formatted output, so an agent must infer the boundary.

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 never says when to choose this over export_gif, export_preset, or compress, all of which sit in the same sibling list. No prerequisites, no exclusions, no mention that gif-only parameters (fps, width) are ignored for mp4/webm in this text.

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 two meaningful behaviors: the operation re-encodes (so it is a write, with quality/cost implications) and invalid rectangles fail fast instead of being clamped. It does not say whether the source file is preserved, where the result lands, or whether re-encode alters quality settings, leaving gaps for a mutation 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, front-loaded with the action and its parameterization, then the one failure mode that matters. 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?

For a 7-parameter write tool with no annotations and no output schema, the description covers the core operation and one error case but is silent on the return value (e.g., resulting file path) and on non-destructive behavior toward the input. Adequate, not 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 schema already explains every parameter including output path and overwrite semantics. The description's restatement of (x, y, width, height) as a pixel rectangle adds essentially nothing 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?

Specific verb ("Crop") plus resource ("a video") and an explicit geometric model (x, y, width, height) with the extra detail that the result is re-encoded. It is clearly distinguishable from transform siblings like scale or reframe, though it never names those siblings to reinforce the boundary.

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: you crop when you want a sub-rectangle of the frame. The second sentence gives a validity constraint (out-of-bounds rectangles are rejected) but no guidance on when to pick this over reframe, scale, redact_region, or clip, nor any stated prerequisites.

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

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

With no annotations the description carries the full burden and does well: it discloses the edge-padding behavior, the audio-silence condition, that dryRun writes nothing, and the return payload (output path and time saved). It does not mention overwrite protection or re-encoding cost, which for a media-mutating tool would be valuable.

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?

Four tight sentences with the operation and detection criteria front-loaded, then the dryRun hint, then the return values. The line 'Agent recordings are full of these pauses' is mildly promotional but earns some place by explaining why the tool exists.

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

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

Covers the operation, the dry-run path, and the return values, which is the key gap for a tool with no output schema. With seven parameters and no annotations, a note on whether the source is ever modified and on overwrite defaults would complete 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%, so keepSec, useAudio, dryRun, minIdleSec and overwrite are all already documented in the schema. The description reinforces the pad concept ('keeping a short pad at each edge') and the dryRun semantics but adds no new format or default information 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 concrete verb and resource ('Remove dead air: cut stretches where the screen is frozen...') plus the precise detection criteria (frozen video, optionally silent audio). It implicitly separates itself from range-based trimming, but never names a sibling like trim, so the differentiation is left to inference.

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 suggests a usage pattern through 'Agent recordings are full of these pauses,' and correctly frames dryRun as the preview step. However, there is no explicit 'use this instead of trim when...' guidance, no preconditions, and no statement of when not to use it.

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

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

With no annotations, the description carries the burden and does disclose two useful traits: video is copied untouched and the return is an output path. However, it says nothing about whether the source is modified, permission or environment prerequisites, failure modes, or how aggressive processing affects speech.

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 with zero filler: what it does first, then the video-passthrough caveat, then the return value. Every sentence earns its place.

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

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

For a simple transformation tool with full schema coverage, the description covers behavior, side effects on video, and return value. Only the interaction with related tools (normalize_audio, compress) is unaddressed.

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 strength enum with dB values and the overwrite default, so the schema already does the heavy lifting. The description adds no parameter-level detail beyond what is in 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?

Names a specific verb ('reduce') and resource ('steady background noise: fan, hum, hiss') plus the technique (adaptive FFT denoiser). It is clearly different from sibling normalize_audio in substance, but never names that sibling explicitly, so the distinction relies on the agent inferring it.

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

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

The targeted noise types ('steady background noise') imply when to reach for it, but there is no explicit when-not guidance and no mention of the closest alternatives (normalize_audio, compress, extract_audio). 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 does well: it discloses the adaptive strategy (steps fps, width and palette/quality down until the file fits) and that it reports the settings used, which tells the agent output is degraded rather than failing. It does not say what happens if the budget cannot be met or that overwrite is off by default, leaving some mutation/side-effect behavior undocumented.

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 front-loaded with the essential purpose before the mechanical detail. Nothing is redundant with the title and every clause adds 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?

There is no output schema, and the description partially compensates by saying it reports the settings used. For a 9-parameter export tool with no annotations, the remaining gap is the failure mode when the size budget cannot be met.

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 already 100%, so the baseline is 3; the description still adds meaning by explaining that fps and width are starting values that get reduced, and by restating the 10 MB default budget as a GitHub-derived limit. It doesn't clarify start/duration or overwrite semantics 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 (export a video as an animated GIF/WebP) plus the distinguishing constraint: it fits a file-size budget. That budget-driven framing separates it from convert, compress and export_preset without the agent 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?

Names the intended destinations (PRs, issues, READMEs) and the default 10 MB GitHub limit, which is a clear usage context. It never names an alternative tool or states when not to use this, so the routing guidance is implied rather than explicit.

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

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

No annotations are provided, so the description carries the full burden, and it does substantial work: it discloses the transform pipeline and that the tool returns the output path. It omits the failure mode when an existing output file is present (the overwrite default) and any note about encode duration, which a writing tool with zero annotation coverage would ideally state.

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, no filler. The deliverable and its platform targets come first, with the encoding details and return value following in a compact clause.

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 and a stated return value, an agent has what it needs to invoke this correctly. The remaining gap is behavioral rather than structural: no guidance on overwrite collisions or runtime expectations for a mutation that writes a new file.

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 the platform presets and the fit/overwrite defaults. The description adds no parameter meaning beyond restating the platform names the schema enum already lists, 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 ('Encode a platform-ready file') and enumerates the exact platform targets, plus the transformations applied (reframe, fps cap, H.264, faststart). This clearly separates it from siblings like reframe, convert, and compress, which modify video without producing a platform-targeted deliverable.

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 enumerated platform list makes the intended use case obvious: this is the tool to pick when a deliverable must match a named platform's spec. It gives no explicit exclusions, though — nothing says to use convert or scale instead for non-platform aspect ratios, or how this differs from reframe plus convert chained.

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 exist, so the description carries the full burden. It does disclose the return value ('Returns the output path') and the available codecs, which is useful, but it says nothing about whether files are written to disk, overwrite semantics, or failure behavior when the source 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?

Two short sentences, both front-loaded with the core action and the return value; nothing is 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?

For a 4-parameter file operation with full schema coverage and no output schema, the description covers the action, format choices, and the returned path. Only edge-case behavior (missing audio stream, overwrite conflicts) is left unstated, which 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?

Schema description coverage is 100% and every parameter (input, format, output, overwrite) is documented in the schema, including the copy-codec nuance. The description only restates the format options, adding no meaning 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?

Uses a specific verb ('Extract') on a specific resource ('the audio track of a media file') and states the output artifact. An agent can distinguish it from generic 'convert' or 'normalize_audio', though the description never explicitly contrasts 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 purpose implies when to use it (pulling an audio-only file out of a video), but there is no explicit when-to-use/when-not guidance and no mention of alternatives such as convert, normalize_audio, or transcribe, which an agent could easily confuse it with.

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 it well: 'no install', best-effort detection with an explicit 'always review' warning, boxes reported in the source image's pixels with coordinate-frame guidance, per-frame cost ('each takes about a second'), and the backend trade-off where gdigrab reads what is visible while wgc reads a window's own surface even when occluded. The `keep` note about screenshots being deleted by default because they may show the very secrets being searched for is exactly the kind of consequence an agent needs before calling.

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

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

The core purpose is front-loaded in the opening clause, and nearly every clause carries distinct information (engine provenance, use cases, redaction hand-off, coordinate frames, review caveat). The single dense paragraph with stacked semicolons and em-dashes is heavier than needed and would scan better as two or three sentences.

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 no annotations and no output schema, the description covers the return shape (per-line and per-match bounding boxes), the defaults that matter, and the security-sensitive deletion behavior. The remaining gap is that zero parameters are required, so the description never says what happens when neither `target` nor `input` is supplied, and the phantom `origin` reference needs reconciliation with 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 coverage is 100%, so the baseline is 3, but the description adds genuinely non-schema meaning: the coordinate frame of returned boxes (image pixels vs desktop coordinates) and the fact that scanEverySec covers the whole clip rather than one moment, with the interval auto-widening. It loses a point for referencing an `origin` parameter in the parenthetical that has no counterpart in the schema, which could send an agent looking for a field that isn't there.

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 ('Read text on screen or in an image/video frame with the OCR engine built into Windows') and immediately names the concrete jobs it serves: locating a label or button, checking what the screen says, and hunting for secrets. It also distinguishes itself from the adjacent redact_region tool by declaring that it produces rectangles for it, so an agent can tell the two apart without opening a 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?

Gives clear situational routing: use scanEverySec 'for a video' to check a whole clip for secrets before sharing, and add `origin` for a live target to get desktop coordinates. There is no explicit when-not or named alternative among siblings such as screenshot or sample_frames, and the mention of an `origin` parameter that does not exist in the schema leaves a small inference gap.

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 disclosure burden. 'Probe ... and return' implies a read-only operation, and the enumerated return fields partly substitute for the missing output schema. However, nothing is said about error behavior on unreadable/unsupported files, whether paths are local or remote, or whether the whole file is read (cost/latency).

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 mechanism (ffprobe), followed by the exact return fields. Nothing is 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?

For a one-parameter, no-annotation inspection tool this is nearly sufficient: the return values are listed even without an output schema. The remaining gap is failure/cost behavior, which matters for an ffprobe call on arbitrary 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% — the single 'input' parameter is documented as 'Path to the media file to probe'. The description adds no additional constraint (path format, accessibility, URL support) beyond that, 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?

The description states a specific verb ('Probe') on a specific resource ('a media file') and enumerates the concrete outputs (duration, resolution, frame rate, codecs, container, size). This clearly separates it from the transformation siblings (convert, trim, scale, extract_audio), though no sibling is named 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?

There is no explicit when-to-use statement or named alternative, but the inspection use case is strongly implied by 'probe' and by the return fields. An agent must infer that this is the pre-flight/read tool rather than a producer of new media.

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. 'Inspect' implies a read-only operation and the description usefully discloses that live status and output-file existence are included, but it does not address error behavior for invalid ids, permissions, or other operational traits.

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. It identifies the action, the resource, and the notable returned information without wasting 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 simple one-parameter read tool with no output schema, the description is largely complete: it identifies the lookup key, the scope, and key returned attributes. Minor gaps remain around error cases and whether the read has any side effects, but nothing essential to calling the tool is missing.

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

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

Schema description coverage is 100%; the only parameter is documented as 'Session id returned by start_recording.' The description does not add format or validation detail beyond what the schema already 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?

States a specific verb ('Inspect') and resource ('a single recording session by id'), and adds the retrieved fields (live status, output file existence). It does not explicitly distinguish itself from the sibling 'list_sessions', but the singular/by-id framing makes the distinction inferable.

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 'single recording session by id' implies this is the lookup tool for one known session, while 'list_sessions' would be the alternative, but no explicit when-to-use or exclusion guidance is given. 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 delivers: it discloses the platform backend (DirectShow), that results are machine-local, that one entry is flagged as a probable loopback, and that microphone devices are out of scope. It stops short of describing the returned structure (field names, how the flag appears), which is the only notable 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, front-loaded with the action, then the usage handoff, then the constraint. No redundant restatement of the name or title.

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 output schema and no annotations, the description must supply all context, and it covers purpose, consumer, platform, and limitations. The return value shape — how the loopback flag is surfaced — is the one thing an agent must discover by calling, keeping this short of a 5.

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 the baseline of 4 applies; there is nothing for the description to disambiguate beyond noting that no filters or selectors are accepted.

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

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

States a specific verb and resource ('List the DirectShow audio devices ffmpeg can see on this machine') plus an extra behavior (flagging a likely loopback device). It is clearly distinguishable from siblings like start_recording, which consume rather than enumerate devices.

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 instructs to 'Use the returned name as the `audio` device for start_recording', tying this enumeration tool to its consumer. It also states the exclusion — system audio requires Stereo Mix or a virtual-audio driver, and microphone capture is not supported — so the agent knows when this tool is applicable.

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 behavioral burden. It establishes a read-only listing operation and adds useful context such as whether the process is still alive, but it omits permissions, ordering, pagination, and failure behavior.

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 no filler. Every clause contributes directly to scope or returned 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 an empty-schema, output-schema-free listing tool, the description is largely complete: it covers scope and visible return fields. A minor gap remains around ordering or pagination behavior, but complexity is low.

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 no parameter semantics to explain. The baseline score for a zero-parameter tool is appropriate.

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

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

The description names a specific verb and resource: list recording sessions. It also defines scope as all sessions, active and finished, and lists the returned attributes; the word all helps distinguish it from the single-session sibling get_session.

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 this is the tool for viewing all sessions, but it does not explicitly state when to use it instead of get_session or when to use start_recording/stop_recording. No exclusions or prerequisites 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 full burden and does well: it discloses loop/trim, fades, leveling, mixing/ducking, and that video is copied while audio is re-encoded. It omits overwrite/output-file semantics and return behavior, so not exhaustive.

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 tightly packed sentences, front-loaded with the core action and mechanics, with no filler.

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

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

For an 8-parameter media-editing tool with no annotations or output schema, the description gives enough behavioral context to call it correctly. It could say more about output/return behavior, but the schema covers parameters.

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 defaults and meanings are already documented. The description reinforces concepts like ducking, fades, and leveling but adds little 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?

The description names a specific operation (laying a music bed under a video) and details its mechanics, so the agent knows exactly what it does. It does not explicitly contrast with sibling audio/video tools, so it stops short of 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 implies the use case (adding music to a video) but offers no explicit when-to-use/when-not or alternative tools such as normalize_audio or assemble_highlights. The condition of existing audio is behavioral, 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?

With no annotations the description carries the full burden. It usefully discloses the two-pass method, that video streams are copied untouched, and that before/after loudness is reported, but it does not say whether the source file is modified in place, whether audio is re-encoded, or how costly a two-pass run is.

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, each earning its place: capability first, then the non-destructive guarantee, then the reported result. Nothing is padded or 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 single-step media mutation with four well-documented parameters and no output schema, the description covers purpose, side effects on video, and the return signal. Only format/support limits and source-file mutation semantics remain unstated.

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%, including an explicit LUFS mapping for each target value and the overwrite default, so the schema already does the heavy lifting. The description adds no syntax or default detail beyond calling out the delivery-target concept, 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 specific verb and resource ('Normalize a recording's loudness') plus the exact method (EBU R128, two-pass loudnorm) and target concept. 'Video is copied untouched' separates it cleanly from transcoding siblings like convert or compress, and from denoise which addresses noise rather than level.

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 stated goal ('narration and system audio are neither too quiet nor clipping') implies the situation it is for, but no sibling alternative or exclusion is named and no prerequisites (e.g. audio track must exist, run before or after denoise/music_bed) 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 full burden. It usefully discloses that a video overlay starts at 'start' and holds its last frame if it ends early, and that the output keeps the base video's audio and length. However, it does not mention overwrite behavior, error conditions, or file replacement semantics.

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

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

Two tightly written sentences with the core purpose front-loaded. The second sentence adds behavioral detail that earns its place, and there is no redundant or filler content.

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

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

For a 10-parameter tool with 100% schema coverage and no output schema, the description covers the core operation and important playback behavior. It stops short of explaining overwrite semantics or output path handling, but the schema fills those gaps adequately.

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 ten parameters clearly. The description adds minimal parameter meaning beyond the schema, only restating that the overlay is placed at a pixel position and can be scaled and time-limited, which maps to x/y, width/height, and start/end.

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 ('Composite') and resource ('image or video onto a base video at a pixel position'), with examples of use cases (logo, watermark, picture-in-picture). It distinguishes the operation from most siblings by focusing on compositing, though it does not explicitly name alternatives like title_card or 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?

The description implies usage through examples (logo, watermark, picture-in-picture) and mentions scaling and time-limiting, but it does not state when to use this tool versus alternatives such as burn_subtitles or title_card, nor does it provide explicit exclusions.

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

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

With no annotations, the description still discloses important behavior: one re-encode, no intermediate files, reusable saved steps, and dryRun returning the plan without execution. It does not cover permissions, error handling, or normal return values in detail, but it adds substantial behavioral context beyond 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?

The description is four sentences, front-loaded with the core purpose and performance benefit. Every sentence contributes useful information about supported steps, reuse, and dryRun, with no filler.

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

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

For a complex nested pipeline tool, the description covers the central concept, supported operations, export endings, reuse, and dryRun. It leaves normal return values and the exact save/re-run mechanism implicit, but the detailed schema fills most structural gaps.

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 meaning is already largely documented in the schema. The description adds useful context by saying steps use the same options as the standalone tools and may end with export_preset or export_gif, but most parameter-level semantics remain in the schema.

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

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

The description gives a specific verb and resource: run several edits as one ffmpeg process. It distinguishes itself from the standalone edit tools by explaining that it avoids a tool call and re-encode per edit. The listed supported operations and final export steps make its 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?

It clearly implies when to use this tool: for multiple edits that should share one re-encode instead of separate standalone tool calls. It also names the standalone tools as the alternative behavior, though it does not explicitly say when a single edit should use those tools instead.

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 disclose the essential behavior: output is JPEGs sampled evenly across the video with timestamps, produced for the inline player UI. What it omits is whether frames are written to disk or returned in-memory, and any cost/latency implications of up to 300 frames.

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 identity of the tool front-loaded and the routing instruction immediately after. Every clause adds 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?

A simple three-parameter tool with fully documented schema, no output schema, and clear instruction not to use it from agents. The description supplies everything an agent needs to either call it correctly or choose a sibling instead.

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 descriptions and defaults already documented for input, width, and maxFrames (including min/max bounds). The description adds no format or semantic detail beyond the schema's own wording, 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 specific verb (preview), resource (frames), and output shape (JPEGs spread evenly over the video, with their times). It also explicitly distinguishes itself from the sibling tools sample_frames and 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?

Explicitly routes agents away from this tool: 'agents should use sample_frames or contact_sheet instead,' naming two concrete alternatives. The intended consumer (the inline player) is named, making the use/avoid split 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?

With no annotations, the description carries the load and does well: it discloses the returned fields (time in seconds, position in video pixels), that typing bursts expose only start and length, and that 'gap' means events may be missing — a genuine data-quality caveat. It doesn't state what happens when the recording was not started with events: true or how the two input forms (sessionId vs path) interact, which keeps it below 5.

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 the resource first and no filler; every clause carries information (content list, units, filter example, next step). It is dense and colon-heavy, which makes it slightly harder to scan than it could be, but 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?

For a 7-parameter, no-required, no-output-schema tool it covers the essentials: what is read, both input forms, filtering axes, the default limit via schema, and the follow-up tool. Remaining gaps are edge behavior — empty/absent event logs, and sessionId vs path precedence — which are minor but not trivial for a data-ingestion 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 coverage is 100%, so the schema already defines from/to/limit/types/input/inFrameOnly; the description still adds value by giving a worked example of the types filter ('down' for clicks) and by tying the returned times to sample_frames, clarifying the unit/coordinate alignment the schema leaves implicit.

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 ('Read the input event log of a recording') and enumerates exactly what is returned: mouse clicks, scroll, cursor positions, shortcuts, typing bursts, each with video time and pixel position. It anchors the source to 'start_recording events: true', which separates it from sibling readers like player_frames or sample_frames.

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 usage context ('Filter by time range and type, e.g. types: ['down'] for the clicks') and routes the agent forward to sample_frames at those times, establishing the read-events-then-look workflow. It stops short of stating when not to use it (e.g. no event log exists), but the intended context is unambiguous.

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

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

No annotations are provided, so the description carries the full burden: it discloses that the default box style is irreversible, that blur/mosaic are partially recoverable, and that out-of-frame regions are rejected rather than silently no-ops. That is exactly the safety-relevant context an agent needs for a destructive edit. It omits what happens to concurrent defaults and what the call returns, costing it a point.

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?

Four short sentences, front-loaded with the scope, then the caveat, then the destructive-default warning, then the failure behavior. Nothing is repeated and every sentence carries decision-relevant 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 7-parameter mutation tool with no annotations and no output schema, the description covers scope, destructiveness, and error behavior well. The remaining gap is the return value — with default output landing under SCREENCAST_HOME/edits, the agent cannot tell from the description whether the resulting path is returned or must be inferred.

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 meaning is already established; the description still adds value by explaining why the style choice matters (recoverability), which the schema only asserts briefly. It also reinforces the failure mode for bad region values. Minor added value over the schema, hence short of 5.

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 ("Redact declared rectangles in a video") and immediately scopes it against the adjacent capability it is not: "it is NOT automatic secret detection." An agent can distinguish this from OCR-driven siblings like find_text 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?

Gives a clear when-to-use condition (you already know the rectangles) and an explicit when-not (not automatic secret detection), which steers the agent away from using it as a detector. It stops short of naming the alternative route (e.g. find_text to locate secrets first), so the guidance is clear but not fully routed.

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 the destructive-ish implication of 'crop' ('trims the overflow') and that pad loses nothing, plus that an output path is returned. It omits whether the source is modified, re-encoding/quality effects, and audio handling, leaving meaningful behavioral gaps for a mutation 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?

Three short sentences, front-loaded with purpose, then the mode semantics, then the return value. 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 5-parameter tool with no output schema, the description covers purpose, mode behavior, and the returned output path, which is enough to call it correctly. It could say more about overwrite/replace semantics and source preservation, but the essentials are 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?

Schema coverage is 100% and each parameter already carries a rich description, so the baseline is 3. The description's explanation of pad/crop largely restates the 'fit' enum description and says nothing about 'output' or 'overwrite' beyond the schema.

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

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

The description opens with a specific verb-plus-resource ('Re-aspect a video to a target ratio') and enumerates the supported ratios, so the operation is unambiguous. It does not distinguish itself from sibling tools like 'crop' or 'scale', which could plausibly be reached for the same goal.

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 explains the pad-vs-crop trade-off ('nothing is lost' vs 'fills the frame and trims the overflow'), which is useful decision guidance for the 'fit' choice. However, it gives no guidance on when to use this tool versus siblings such as 'crop' or 'scale', and states no prerequisites beyond a required input.

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 well disclosing client-dependent behavior and that the user's choices "run as a pipeline call" (i.e. a side effect is triggered). However, it never states whether the call blocks until the human finishes, what happens on cancel/close, or whether an export file is created without further confirmation — the most important behavioral facts about a human-in-the-loop 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?

Three tight sentences, front-loaded with the action, then the two execution modes. The parenthetical about the pipeline call is compact and earns its place. Slight density loss from cramming player interactions and fallback guidance into one block.

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 output schema and no annotations mean the description must cover return behavior and side effects. It covers the return shape in the fallback case ("returns the video's details") but is silent on what the interactive mode returns to the agent and on the lifecycle of the exported trimmed/redacted copy.

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

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

Schema coverage is 100%, so both parameters (video path and stopped-session id) are already documented in the schema. The description says nothing about the path-vs-sessionId selection, so it adds no meaning beyond structured data — 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 ("Open a recording for a person to review") and immediately clarifies the two modes it operates in, including the inline player with trim/redaction editing. An agent can distinguish this from list_sessions, get_media_info, or clip without opening a 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 routes the agent: in MCP Apps clients you get the interactive player; elsewhere it only returns video details and you should use contact_sheet or sample_frames instead. That names both the condition and the alternatives. It stops short of saying when to prefer this over get_media_info or clip for non-interactive inspection.

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: it discloses the write side effect (PNG frames written to a folder), the return shape (paths plus inline image frames), and the returnImages toggle. It stops short of stating limits, permissions, or error behavior, which keeps it from a 5.

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 before the output/return detail. Every clause earns its place, and the parenthetical toggle hint is compact.

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

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

For an 11-param tool with no output schema, the description adequately explains what is produced (paths on disk plus inline frames) and the key control. It does not cover the 'scenes' mode or maxFrames semantics, but the schema fills those gaps, so the combination 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?

Schema description coverage is 100%, so every parameter already carries an inline description; the schema explains modes, dedupe, maxFrames, thresholds, and inline caps thoroughly. The description reinforces only fps, timestamps, and returnImages, 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 specific verb (Sample) and resource (frames from a video) and names two selection strategies (fixed fps or explicit timestamps). It is clear what the tool produces, though it never distinguishes itself from likely-functional siblings like contact_sheet or screen_diff, so the agent must infer the boundary.

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 'so the agent can actually view what happened' implies the review use case, and 'disable with returnImages: false' is a small usage hint. But there is no explicit when/when-not guidance and no routing to alternatives such as contact_sheet, screen_diff, or screenshot, leaving selection to inference.

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

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

With no annotations, the description carries the full burden; it does disclose that the video is re-encoded, which hints at quality loss and processing cost, and the schema covers output path defaults and overwrite. It does not say whether the source file is left untouched, what the output format is, or whether dimensions must be even for video codecs.

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 action and followed by the one decision rule that matters. Nothing is wasted and nothing needs re-reading.

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 five-parameter transformation with no output schema and no annotations, the description plus the fully-described schema covers the essentials of choosing and calling it. The only real gap is that it does not establish where this sits relative to the other video-transformation 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?

Schema coverage is 100%, so every parameter is already documented, and the schema descriptions themselves state the aspect-ratio derivation rule. The description restates that rule at the tool level but adds no new semantics such as rounding, minimum size, or interaction with output/overwrite.

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 ('Resize a video') plus the mechanism ('re-encode'), which is enough to distinguish it from a pure metadata edit. However it never contrasts itself with nearby siblings like crop, reframe, or zoom, so the agent must 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?

'Provide one side to keep the aspect ratio, or both to set an exact size' explains how to drive the parameters, which implies usage but does not state when this tool is the right choice over crop/reframe/compress. No exclusions or preconditions 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 disclose the full return payload, including the coordinate frame of bounding boxes (b's pixel coordinates) and the inline outlined overlay image. It never states that the tool is side-effect-free/read-only, which is the remaining 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?

Two dense sentences, front-loaded with the operation and its returns, followed by the single usage cue. 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?

No output schema exists, and the description compensates well by enumerating every returned value. Minor omission: the exact shape/format of the bounding boxes and behavior on dimension mismatch is left to 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 all four parameters are already documented in the schema, including defaults and the scaling rule. The description adds no parameter-level meaning beyond that, 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 specific verb (compare) and resource (two screenshots/frames) and enumerates the exact outputs: SSIM score, changed share, and bounding boxes. It is clearly distinguishable from siblings like wait_for_change or review_recording.

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 an explicit use case: verify that a UI change happened and only where expected. It does not name an alternative tool (e.g., wait_for_change for polling, review_recording for session replay) or state when not to use it.

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

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

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses the return behavior (image path plus inline image, with returnImage: false to disable), but it does not mention that the tool writes a PNG file to disk by default, how overwrite behavior works, or any permission/failure considerations. The schema covers those details, but the description alone gives only partial behavioral context.

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

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

Two tightly written sentences with zero waste. The core purpose is front-loaded, followed by the important return behavior and the key opt-out parameter.

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

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

Given the rich input schema and no output schema, the description is largely complete for correct invocation: it states the capture target categories and explains what is returned, including inline image behavior. It is slightly thin on side effects and sibling selection guidance, but the schema fills most structured gaps.

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 seven parameters thoroughly. The description adds only a small amount beyond the schema by noting that returnImage: false disables inline image return. Baseline 3 is appropriate because the schema does the heavy lifting.

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

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

The description states a specific verb and resource: 'Capture a single still frame (PNG) of a target', and enumerates the target types (full screen, monitor, window, region). It distinguishes itself from recording siblings by emphasizing 'single still frame', but it does not explicitly name or contrast with alternatives such as sample_frames or start_recording.

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 purpose: use this when a one-off screenshot is needed. However, there is no explicit when-to-use/when-not-to-use guidance and no mention of alternatives like sample_frames, zoom, or recording tools. The target options describe input format, not when this tool should be selected over siblings.

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

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

With no annotations, the description carries full burden. It usefully discloses that it re-encodes and that audio is retempo'd when a source audio track exists, but says nothing about quality loss from re-encoding, reversibility, or overwrite behavior beyond 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?

Two tight sentences, front-loaded with the core action and factor convention, with the audio behavior as a secondary note. Every sentence earns its place.

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

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

For a 4-param re-encode tool with no output schema and full schema coverage, the description is adequate: it covers factor direction and audio handling. It could note re-encode quality/permissions, but nothing critical to calling it correctly is missing.

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

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

Schema coverage is 100%, so all four parameters are already documented. The description restates the factor semantics (>1 faster, <1 slower) already present in the schema and adds the audio-retempo behavioral nuance, but doesn't elaborate on output/overwrite 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 (change) and resource (playback speed by a factor) plus what it does (re-encode). It's clearly distinct from siblings like trim/concat/scale, though it doesn't explicitly name any alternative.

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 purpose statement — there's no explicit when-to-use, when-not, or named alternative (e.g. 'use scale/convert for X'). An agent can infer intent but gets no 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?

With no annotations, the description carries the behavioral burden and does disclose key traits: it runs a background ffmpeg process, returns a session id and output path, never auto-starts, and requires stop_recording to finalize. It is less complete on failure modes, permissions, and auto-stop behavior, but the core lifecycle is transparent.

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

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

The description is compact and front-loaded: it opens with the action and implementation, then covers return values, lifecycle, finalization, and audio limitations. Every sentence adds useful information with no filler.

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

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

Given the rich input schema, the description is complete enough for an agent to understand the core operation, return contract, lifecycle, and audio constraint. It relies on the schema for parameter details and does not cover failure modes or permissions, but no critical invocation detail is missing.

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

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

Schema description coverage is 100%, so the schema already documents all 11 parameters in detail. The description reiterates the audio default and microphone limitation but adds little parameter 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: start a screen recording using Windows gdigrab as a background ffmpeg process. It also distinguishes the tool from its natural sibling by naming stop_recording as the finalization step, so an agent can tell it apart from stop_recording or screenshot tools.

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

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

The description gives clear lifecycle guidance: recording is explicit, never auto-starts, and must be finalized with stop_recording using the returned id. It also states an important exclusion, that microphone capture is not supported, though it does not explicitly compare start_recording with alternatives like screenshot for static capture.

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 behavioral burden and does well: it discloses the graceful ffmpeg quit that finalizes the file, the pid-based fallback, the returned path and duration, and the MCP Apps review player. It does not cover error behavior for invalid sessions or whether the operation is idempotent, so it stops short of fully transparent.

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 tightly written sentences with zero filler. The core operation is front-loaded, followed by the meaningful behavioral details and client-facing side effect.

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 no-annotations, no-output-schema tool, the description supplies the essential behavioral context: finalization semantics, fallback behavior, and return values. It is nearly complete, with the main remaining gap being invalid-session or failure behavior.

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

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

Schema coverage is 100%, so the single parameter is fully documented in the schema as the session id returned by start_recording. The description adds little beyond saying it takes a session id, so the schema is doing the substantive 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 ('Stop a recording') and immediately narrows it to stopping by session id. It distinguishes itself from start_recording and other session-related siblings by describing the exact operation and its finalization behavior.

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?

Explains the primary use case (stop an active recording by session id) and gives a concrete condition for the fallback path (lost live handle after a server restart). It does not explicitly say when not to use it or name an alternative tool, but the usage 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?

With no annotations, the description carries the behavioral burden and does disclose two meaningful traits: the silent audio track (so it composes with audio-bearing clips) and bundled-font rendering (no system font dependency). It doesn't mention that the tool writes a file to disk, what happens with output path collisions beyond the schema's overwrite flag, or what it returns, leaving real gaps for a file-producing operation.

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

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

Two sentences, zero filler, front-loaded with the core action and output shape, followed by the two facts an agent most needs (silent audio for compositing, bundled font). Nothing repeats 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?

For an 11-parameter, 100%-documented schema with no output schema, the description covers the non-obvious behavioral facts (silent track, bundled font, pipeline integration). The main omission is the return value / output file location, which an agent must infer from the schema's output parameter and the overwrite flag.

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 11 parameters including defaults and constraints are already documented. The description adds only implicit semantics (text is centered, background is solid) and no format or behavior detail beyond the schema, 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?

The description names a specific verb and resource ('Generate a standalone title card') and immediately specifies what the output is: centered text on a solid background with a silent audio track. This differentiates it from generic compositing siblings like overlay or callout, and the assemble_highlights reference makes its role in the pipeline unambiguous.

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

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

It gives a clear integration path ('use assemble_highlights to stitch it in') and explains why the silent audio track exists, which is the main usage nuance. It does not state when not to use this tool (e.g. instead of overlay/callout for text on existing footage), so it falls short of full when/when-not guidance.

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

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

With no annotations, the description carries the burden, and it does disclose meaningful traits: processing is local, a model file is required, and it returns both the SRT path and the text. It does not mention runtime cost, failure modes when no model is configured, or that overwrite defaults to false and will error on an existing path — notable omissions for a mutation-adjacent 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?

Three tight sentences, front-loaded with the action and output type, then the dependency, then the return values and next step. Nothing is wasted and each sentence adds a distinct fact.

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

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

The description covers the prerequisite, the output shape, privacy-relevant behavior (local execution), and the follow-up tool, which is substantial for a 5-param tool with no annotations or output schema. It omits expected runtime and overwrite/error behavior, but the core call path is fully described.

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 input, model, output, language, and overwrite is already documented in the schema. The description reinforces the model-file requirement but adds no syntax or format detail beyond what the schema supplies; 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 (transcribe) and resource (a recording's speech) plus the concrete output artifact (an SRT subtitle file) and the underlying implementation (FFmpeg 8's whisper filter). This distinguishes it cleanly from siblings like extract_audio or find_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?

Explicitly says to pair it with burn_subtitles to caption the video, which routes the agent to the natural follow-up step, and flags the prerequisite of a whisper.cpp model file. It stops short of stating when NOT to use it (e.g., when subtitles already exist or for non-speech audio).

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 and does well: it discloses the default re-encoding behavior, frame-exact cuts, true content removal, and the hidden-frame risk of stream copying, including a warning against using exact:false for sensitive content. It stops short of mentioning permissions, overwrite behavior, or error conditions, which keeps it from a 5.

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 tight sentence with the core operation front-loaded and the most consequential behavioral nuance immediately following. Every clause earns its place by adding either purpose or the critical exact-flag tradeoff.

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 seven-parameter mutation tool with no annotations and no output schema, the description covers the essential behavioral risk and the end-versus-duration relationship. It omits output-path defaults and overwrite semantics, but those are fully covered in the schema, so the description is largely 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 schema already explains all seven parameters thoroughly. The description adds only a small amount of semantic value: it frames the start/end/duration relationship and reinforces the exact flag's meaning. Baseline 3 is appropriate because the schema does the heavy lifting.

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

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

The description states a specific verb and resource: 'Trim a video to a sub-clip,' and clarifies the required start plus end-or-duration inputs. It is clear what the tool does, but it does not distinguish itself from the sibling 'clip' tool, leaving ambiguity about when to prefer one over the other.

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

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

It gives explicit guidance on the key exact flag tradeoff: default re-encode for frame-exact removal versus exact:false for fast stream copy with hidden frames. However, it offers no guidance on when to use this tool versus siblings like clip or cut_idle, so routing between similar tools remains unclear.

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 well: it discloses the return payload (duration, changed location, inline final screenshot) and that watching is preferable to a blind sleep. It never explicitly states the call blocks/polls for up to timeoutSec or that it is a read-only, non-mutating operation, which are the remaining gaps.

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: purpose and mode distinction first, then what is returned, then coordinate conventions. No filler and nothing a caller needs is 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 9-parameter UI-observation tool with no annotations and no output schema, the description covers intent, mode selection, and return shape. Missing only blocking/timeout semantics at the description level, which the schema parameters partially cover.

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

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

Schema coverage is 100%, so baseline is 3; the description adds genuine meaning by specifying that `regions` use screenshot pixel coordinates (matching find_text/screen_diff) and that `origin` is needed for desktop coordinates. Note the description references an `origin` parameter that does not exist in the schema, which is a minor inconsistency.

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 (watch part of the screen, return on change or settle) and explicitly frames it against the naive alternative of 'guessing a sleep'. The two modes are named inline, so an agent can distinguish behavior 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?

Gives concrete situations per mode ('a dialog opened, a page responded' vs 'a build finished, a page finished loading'), which is real routing guidance. It does not say when to prefer screen_diff or find_text instead, only that those share the coordinate convention.

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 well: it discloses that both inputs are auto-normalized to a common resolution, fps, and audio rate, that offsets follow each clip's video length, and that missing audio is replaced with silence. It does not mention overwrite behavior or where output lands, though those are covered by 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 the core action followed by the two non-obvious behaviors. Nothing redundant, though the last sentence is dense enough that it reads slightly like a spec dump.

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 media-transformation tool with full schema description coverage, the description supplies exactly the non-obvious runtime facts an agent needs (auto-normalization, offset basis, audio fallback). Overwrite and output defaults are handled in the schema, so nothing material is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds real meaning beyond the schema by explaining that offsets are computed from each clip's video length and that normalization makes mismatched inputs acceptable, which clarifies how duration and the two input paths actually interact.

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 ('Crossfade two videos into one with an xfade transition') and the key distinguishing behavior from concat (a blended transition rather than a hard join). An agent can tell what this produces 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 description — you use it when you want a crossfade rather than a hard cut — but the description never names the alternative sibling (concat) or states when a crossfade is inappropriate (e.g., mismatched content, very short clips). No exclusions or prerequisites 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 full burden and does a decent job: it discloses that `dryRun` writes nothing and returns an adjustable plan, and that the tool returns the output path. It stops short of stating whether the source is re-encoded or overwritten, or the cost of processing a long recording.

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?

Four tight sentences, front-loaded with the effect and then the input modes. The parentheticals ('rectangles by time', 'Screen Studio style') earn their place, though the prose is dense enough that a bulleted split of keyframes vs auto-plan would read faster.

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 no annotations and no output schema, the description covers purpose, both input modes, the dry-run review loop, and the return value. Remaining gaps — encoding behavior and the requirement to pass the original unscaled recording — are partially handled by the schema itself.

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

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

Schema coverage is 100%, so baseline is 3. The description goes slightly beyond by explaining the interaction between `keyframes` and `follow` ('Omit to plan them automatically') and by summarizing `highlightClicks` as rings drawn at each click, which reinforces what the schema already says.

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 and resource — 'Smooth animated zoom-and-pan … zoom into where the action is and back out' — which is clearly an animated effect, not a static transform. That distinguishes it cleanly from siblings like crop, scale, reframe, and xfade_transition 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?

It gives the two routes to using the tool clearly: supply keyframes yourself, or let it plan them from the event log or screen changes, with `follow` disambiguating the auto path. It does not say when to prefer this over static crop/reframe siblings, so a 4 rather than a 5.

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