cuttingfloor

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

Annotations already declare idempotent=true, destructive=false, and readOnly=false. The description adds useful behavior beyond those annotations: the clip is empty, its effects reach every track below it while it runs, and the call returns the edit result.

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 compact sentence conveys what the clip is, how its effects work, an example use, and the return behavior. There is no redundant restatement, and the core definition is front-loaded.

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

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

With annotations covering safety and idempotency and an output schema covering the return, the description supplies the missing conceptual model: empty clip, effect scope, and the filter.add relationship. Nothing critical for correct invocation is missing, and return details are appropriately delegated.

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

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

Schema description coverage is 80%, so most parameter meaning is already provided structurally. The description reinforces that track_id is a video track whose effects reach lower tracks and links the returned clip_id to filter.add, but it does not elaborate on duration_frames or at_frame beyond the schema, fitting the baseline for high coverage.

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

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

The description defines an adjustment clip as an empty video-track clip whose effects change everything below it while it runs, with colour grade/blur as examples. It clearly identifies the resource and effect mechanism, though it does not open with an explicit action verb, so the title carries part of the action.

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 use case: a colour grade or blur over a stretch of the edit, and explains that effects are added via filter.add using the returned clip_id. It does not explicitly state when not to use it or compare it with alternatives, so it provides clear context without exclusions.

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

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

Annotations already declare idempotentHint=true, destructiveHint=false and readOnlyHint=false, so safety behavior is largely covered. The description usefully adds that null values remove a fade and that the edit result is returned, but says nothing about whether an existing fade is overwritten or what the fade curve looks like.

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, front-loaded sentences with no wasted lead-in. The parenthetical pointer to server instructions is the only mildly expendable element.

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

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

An output schema exists and return values are correctly deferred, so that is not a gap. However, for a 5-parameter mutation tool with only 40% schema coverage, the definition leaves units, defaults, and partial-fade behavior unexplained.

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 40%, so the description must compensate somewhat. It clarifies the null semantics for in_frames/out_frames and ties them to start/end of the clip, but never states that values are frame counts, their defaults, or what happens if only one side is given.

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 (fade) and resource (a clip's sound), and specifies the effect direction: in from start, out to end. It is distinguishable from siblings like audio.set_gain or transition.add, but it never explicitly contrasts itself with those neighbors.

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 sentence 'null removes a fade' gives one clear when-not case, which is genuinely useful. There is no guidance on when to fade instead of using audio.set_gain or a transition, and no prerequisites are stated.

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

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

Annotations already declare the safety profile (readOnly=false, destructive=false, idempotent=true, openWorld=false), so the bar is lower, and the description still adds context they don't carry: that inline previews include measured loudness while link previews do not, and that the call returns an edit result. It does not cover permissions or what an undo looks like, keeping it short of 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?

Three compact sentences, front-loaded with the core effect (dB on a clip) before preview and return details. Slightly fragmentary opening but nothing is padding.

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

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

An output schema exists, so the description only needs to gesture at the return value, which it does by pointing to the edit result and server instructions. For a 4-parameter mutation with full schema coverage and annotations, the remaining gap is minor.

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 meaning the schema lacks: that keyframes make the gain 'ride' over time, and that inline previews surface preview.loudness that link previews do not. That is genuine value beyond the field descriptions.

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

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

The description names the specific resource and property (gain in dB on an audio clip, or a video clip's linked audio) and distinguishes the two clip kinds it accepts, which separates it from audio.set_master and audio.set_pan. It is phrased as a noun fragment rather than a verb, but the operation is unambiguous to an agent.

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 scope statement (clip-level audio, not master or pan), but the description never says when to prefer this over audio.set_master, audio.set_pan, or audio.fade, all of which live in the same namespace. No exclusions or prerequisites are stated.

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

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

Beyond the annotations (idempotent, non-destructive, non-read-only), the description discloses real behavioral traits: the ceiling caps sample peaks in dBFS, true inter-sample peaks can exceed it on dense bright material, and qa.check measures that in dBTP. It also explains that inline previews carry measured loudness while link previews do not — useful context that is not derivable from structured fields.

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

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

The purpose is front-loaded in the first clause and every subsequent sentence carries distinct information (peak caveat, measurement pointer, preview caveat, return pointer). Some phrasing is terse to the point of being cryptic ("Audio edits with preview inline carry the measured loudness").

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

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

An output schema exists, so deferring return values to the server instructions is acceptable, and the peak/loudness caveats cover the non-obvious failure modes of mastering. Only the relationship to sibling gain tools is left 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 coverage is 75%, so the schema already documents limit_db and the preview enum. The description still adds meaning: it clarifies gain is in dB and that the ceiling applies to sample peaks rather than true peaks, and links preview mode to loudness reporting, which the enum description does not cover.

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?

"Gain (dB) and limiter ceiling on the whole mix" gives a specific resource and scope (the master mix), which implicitly distinguishes it from the per-clip audio.set_gain sibling. It never names that sibling, so the differentiation is inferred rather than stated.

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?

Scope ("whole mix") implies when to use this over clip-level gain tools, and the qa.check mention hints at a verification workflow, but there is no explicit when-to-use / when-not-to-use statement or named alternative. The agent must infer routing from the word "master".

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

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

Annotations already declare it is a non-read-only, idempotent, non-destructive edit, so the safety profile is covered. The description adds only that it returns the edit result and defers to server instructions, without saying what the edit result contains or any constraints (e.g., clip must have audio). Adequate but thin 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 core action and range. The trailing pointer to 'server instructions' is slightly deflective but does not bloat the text.

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

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

An output schema exists, so return values need not be explained, and annotations cover mutation safety. However, nothing explains the preview parameter's effect or whether panning applies only to clips with audio, leaving gaps for a 4-parameter edit 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 75% and the pan range is already documented in the schema; the description merely restates -1..1. The preview parameter and timeline_id handle semantics are not touched on in the description, so it adds little beyond structured fields.

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

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

States a concrete verb and resource ('Place a clip's sound left (-1) to right (1)'), which unambiguously identifies stereo panning and separates it from gain/fade siblings. It does not explicitly contrast with audio.set_gain or audio.set_master, but the word 'pan' plus the -1..1 range does the differentiation implicitly.

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 to use it (to position a clip's audio in the stereo field) but gives no explicit conditions, prerequisites, or alternatives such as audio.set_gain or audio.set_master. An agent must infer usage from the verb alone.

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

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

Goes well past the annotations: it discloses the exact default style when a style field is omitted, that captions are burned in at export, that lines wrap at max_width and balance in length, that max_lines shows a screenful at a time from each caption's first word, and that \n forces a break. It also notes clip_ids are returned. One soft caution: annotations claim idempotentHint=true while the text describes creating clips and returning new ids, which an agent may read as additive, but the description does not explicitly assert repeated calls duplicate, so this is not a hard contradiction.

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

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

Front-loads the input modes, which is the right ordering, and every clause carries information. It is, however, one dense paragraph with heavy parenthetical nesting, so style behavior (defaults, wrapping, spans) blurs into the input-mode explanation rather than being separated.

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

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

With an output schema present, the 'Returns the edit result (see the server instructions)' pointer is sufficient and the burn-in-on-export note covers the non-obvious side effect. Coverage of the style subsystem is thorough for a 9-parameter nested schema; only preview and offset_frames go unmentioned, and both are documented 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 coverage is 78%, so the baseline would be 3, but the description adds real semantics: what in_clip timing means ('placed where those moments play ... through speed changes; what doesn't play is left out'), how spans index words ('the timed words, or the text split at spaces'), and how max_width/max_lines interact with wrapping. It leaves offset_frames and preview entirely to 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 resource (captions) and the three input forms (segments with word timings, srt/vtt text, in_clip media-timed segments), plus the effect (one clip per caption, burned in on export). An agent can tell this is the captioning tool rather than a generic text operation, though it never names the nearest siblings (text.set, title.add) to draw the boundary explicitly.

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

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

The three input modes are each given a selecting condition: 'segments (with optional word timings for highlights)', 'from SRT/VTT text', and 'in_clip: segments timed in seconds of a clip's media, such as transcript word times'. It also points to timeline.get when the caller needs the full style. No explicit exclusions against text.set/title.add, which keeps it out of 5 territory.

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

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

Annotations only declare the safety profile (not read-only, idempotent, non-destructive); the description adds real behaviour: A/V media becomes a linked pair split across video and audio tracks, default placement is after the last clip, and the default mode overwrites. It also discloses the picture auto-fit side effect, which is otherwise invisible and surprising.

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 action and the default behaviour, then the picture-scaling caveat and the return pointer. Each sentence contributes: placement, link semantics, defaults, fit exception, return value.

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

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

With 13 parameters, 100% schema coverage, annotations and an output schema, the description covers the parts an agent most needs before calling (placement default, link behaviour, overwrite default) and defers return-value detail to the server instructions. It does not mention the preview or other_tracks semantics, but those are fully handled 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 description coverage is 100%, so all 13 parameters (including other_tracks, mode, av, source, preview) are already documented in the schema. The description only echoes a few defaults (whole media source, placement after last clip) and adds no syntax or interaction detail beyond what the schema provides — 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?

Opens with a specific verb+resource ("Place media on the timeline") and immediately specifies the two placement modes that distinguish it: linked A/V pair creation and default overwrite-after-last-clip. An agent can tell this apart from clip.replace, clip.move or clip.trim 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 defaults (whole media, after the last clip, overwriting) that tell an agent what happens when it omits arguments, plus one explicit redirect: use clip.set_transform {fit: "none"} if a picture should keep its pixel size. No exclusion against siblings like clip.replace for swapping existing clips, so not a full 5.

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

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

Annotations only declare it is a non-destructive, idempotent write; the description adds real behavior the agent cannot get elsewhere: the split point, downstream ripple on the clip's own tracks, and the silence under a trailing hold. It is still silent on permissions, undo, and what's returned beyond 'the edit result', which is punted to server instructions.

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 front-loaded sentences with nearly zero waste; the primary effect comes first and the edge case second. Minor nits: the doubled 'at at_frame' phrasing and the deferral '(see the server instructions)' push context off-tool.

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

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

With an output schema present, return values needn't be described, and the enumerated other_tracks/preview parameters are fully documented in the schema. The description covers the operation, its ripple effects, and the trailing-frame special case — everything needed to call it correctly.

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

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

Schema coverage is 67%, and the description supplies the key semantics the schema lacks: that at_frame is the held frame and duration_frames is how long, plus the edge-case meaning when at_frame is the clip's last frame. other_tracks, preview and timeline_id are left entirely to the (well-written) schema fields.

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

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

States a specific verb and resource ('hold the frame at at_frame for duration_frames') and spells out the composite effect: the clip splits, a freeze frame is inserted, and later clips ripple. That composite signature separates it from clip.split and create.still without the agent having to infer anything.

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 concrete usage context and an important special case ('freezing a clip's last frame holds it after the clip, with silence under the hold'), which tells the agent when the result differs from the common case. It does not name sibling alternatives such as clip.split for pure cuts, so it stops short of explicit when-not guidance.

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

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

Annotations already cover the safety profile (idempotentHint=true, destructiveHint=false, openWorldHint=false), and the description adds the real behavioral consequence that linked clips move/trim/split as a unit. However, it is silent on what happens when clips are already linked, what happens on partial failure, or why idempotency holds, and it punts the return details to "the server instructions."

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 the behavioral effect front-loaded, which is good. The second sentence is largely a deflection to external server instructions rather than information, so it only partly 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 mutating edit operation with three parameters and an output schema, the description is thin: it does not explain the clip_ids semantics, the effect on already-linked clips, or the new timeline handle returned by the edit. Deferring to "server instructions" leaves the definition incomplete on its own.

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 67%: timeline_id and preview are documented in-schema, but clip_ids — the core parameter — has only a minItems=2 constraint and no explanation in either place. The description says nothing about any parameter, so it fails to compensate for that gap.

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

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

"Make clips move, trim and split together" describes the effect of linking, which is more informative than the title alone, but it never states the action verb ("link") or names the sibling it inverts, clip.unlink. An agent can infer the purpose but must reason to it rather than read it directly.

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

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

There is no explicit when-to-use or when-not-to-use guidance and no mention of the obvious alternative, clip.unlink, which appears in the sibling list. Usage is only implied by the description of what linking does.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, so the safety profile is partly covered. The description adds useful side-effect context that linked clips move with the clip and that the edit result is returned, but it does not elaborate on overwrite/ripple behavior beyond what the schema provides.

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

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

The description is two sentences, front-loaded with the core action and destination, and ends with a useful pointer to the server instructions for return details. There is no wasted wording.

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

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

An output schema exists, so the description need not explain return values in depth, and the annotations carry key safety hints. However, for an 8-parameter timeline mutation with several behavioral options, the description leaves usage against sibling tools and the semantics of required parameters largely 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 63%, so the schema documents most optional parameters, including mode, ripple, preview, and other_tracks in detail. The description only adds destination semantics for the frame and optional track; it does not explain clip_id or add meaning beyond the schema for the required timeline handle.

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: move a clip to a frame, optionally to another track, with linked clips moving too. It is clear what the tool does, but it does not explicitly distinguish this from sibling tools like clip.slide, clip.slip, or clip.roll.

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 no explicit guidance on when to use this tool versus alternatives such as clip.slide, clip.slip, or range.extract. It implies repositioning, but leaves the agent to infer when a move is appropriate and when another timeline-editing tool should be used 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?

The description says 'Remove a clip', which is a destructive operation, while annotations declare destructiveHint: false. This direct contradiction misleads the agent about the tool's safety profile. Although annotations provide other hints (readOnlyHint: false, idempotentHint: true), the contradiction is severe.

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

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

Two sentences with zero waste: the first front-loads the action and scope, the second succinctly notes the return. No redundancy or fluff.

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

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

For a mutation tool with 5 parameters and an output schema, the description is minimal. The contradiction with destructiveHint undermines completeness, as an agent cannot reliably infer the tool's safety. The mention of 'Returns the edit result' is helpful but insufficient to compensate.

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

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

Schema description coverage is 80%, so the schema already documents most parameters (ripple, preview, timeline_id, other_tracks). The description only hints at 'ripple' without adding syntax or format details. Baseline 3 is appropriate given the high coverage.

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

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

The description states a specific verb ('Remove') and resource ('clip'), and clarifies scope by including 'the clips linked to it'. It also mentions the ripple effect, making the action unambiguous and distinguishable from siblings like clip.unlink or clip.trim.

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

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

No explicit guidance on when to use this tool versus alternatives (e.g., clip.unlink or range.extract). The description implies usage through behavior ('ripple closes the gap') but does not state conditions for selection or exclusion.

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

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

Annotations already declare the safety profile (idempotent, non-destructive, closed-world), and the description adds real behavioral context beyond them: the source_in anchor, the fact that linked clips are also swapped by default, that linked:false scopes it to this clip only, and that clip_ids enumerates every clip affected. The remaining gap is that it defers the actual return payload to 'the server instructions' rather than describing shape.

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 operation and its invariants, with the linked-clip caveat placed after. The parenthetical '(see the server instructions)' is a small punt but compact rather than wasteful.

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 idempotent, non-destructive mutation with 6 params, 83% schema coverage and an output schema, the description covers the essentials: what changes, what is preserved, side effects on linked clips, and the source_in anchor. The pointer to server instructions for the return payload is acceptable given an output schema exists, though it costs a bit of self-sufficiency.

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 83%, so the schema already documents most parameters well. The description largely restates schema content ('Starts at source_in (default 0)', 'linked: false for this clip only') rather than adding format or edge-case meaning; the one genuinely new semantic, clip_ids listing all swapped clips, is an output rather than an input.

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 verb ('swap the media') and resource ('in a clip') are specific, and the description pins down exactly what is preserved — place, length, speed, look — which separates it from remove-then-add or clip.add workflows. It does not name a sibling tool to route away to, but the operation itself is 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?

Usage is implied by the description: use it when you want a different media asset in an existing slot rather than a new clip. There is no explicit 'use X instead when…' guidance versus clip.add, clip.trim or clip.remove, and no stated prerequisites (e.g. that media_id must be imported first — that only appears in the schema).

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

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

Annotations already establish that this is a non-readonly, non-destructive, idempotent edit. The description adds useful behavioral context beyond that: exactly two adjacent clips are affected, one lengthens and the other shortens, and no other elements move. It does not discuss permissions or edge cases, but the added mutation footprint is meaningful.

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-loads the core operation. The closing note about returning the edit result and referring to server instructions is slightly redundant given the output schema, but overall there is little waste.

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 moderately complex edit tool with full schema coverage, rich annotations, and an output schema, the description gives enough core semantics to call it correctly. It could be stronger by stating prerequisites such as the need for a following clip on the same track, but the essential behavior is present.

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

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

Schema description coverage is 100%, so clip_id, to_frame, preview, and timeline_id are already documented. The description clarifies the relationship between clip_id and to_frame by describing the cut between two adjacent clips, but adds no syntax, bounds, or format details beyond the schema.

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

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

The description states a specific verb and resource: moving the cut between a clip and the clip immediately after it. The added detail that one clip gets longer, the other shorter, and nothing else moves distinguishes this roll edit from adjacent operations such as trim, slide, or move, even without naming 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 description implies when to use the tool by explaining that only the cut point shifts between two adjacent clips, while everything else stays fixed. However, it does not explicitly name alternatives like clip.trim or clip.slide, nor does it state exclusions or prerequisites for choosing this operation.

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

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

Annotations already declare non-destructive, idempotent, closed-world. The description adds real behavioral content beyond them: null clears a preset, a loop can be confined to a frame range, and the call returns an edit result. It does not restate that each edit yields a new timeline_id (left to the schema).

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

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

One front-loaded sentence carries the purpose, three inline examples, the removal rule and the return note — no wasted lines. It is dense to the point of being a run-on with stacked parentheticals, which slightly hurts scannability.

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

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

With an output schema present and the return value deferred to server instructions, the description need only cover intent and slot semantics, which it does. Minor gaps: no mention of preview behavior or how in/out interact with loop on the same clip.

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 83%, yet the description still earns credit by explaining loop scope semantics (whole clip vs from_frame–to_frame) with a concrete jolt example, and by naming null as the removal value for each slot. The only untouched parameter is clip_id, which is self-evident.

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 exactly what is set — entrance, exit and loop animation presets — and anchors them as layered over the clip transform, which separates this from clip.set_transform and transition.add. The catalog reference (video://catalog/animations) makes the resource concrete.

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?

Shows the calling patterns for each slot and, critically, states that passing null removes an animation — the only removal path given there is no clip.remove_animation sibling. It does not explicitly contrast with clip.set_transform or transition.add, so the routing guidance is implied rather than stated.

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

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

Annotations already declare readOnly=false, idempotent=true, destructive=false, and openWorld=false, so the core safety profile is covered. The description adds that it affects how a clip mixes with lower tracks and returns an edit result, but it does not explain what changes are made to existing state, required permissions, or how the returned edit result should be interpreted beyond pointing to server instructions.

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

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

The description is two tight sentences, front-loading the blend-mode concept and then mentioning the return result. There is little wasted text, though the first sentence is a concept fragment rather than a direct action statement.

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 an output schema and rich annotations, the description need not explain return values or safety in detail. It supplies the essential blend-mode context and a catalog reference, and the schema covers most parameter mechanics. The main omission is usage guidance, which is scored separately.

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 50%, with timeline_id and preview documented in the schema but clip_id and mode lacking schema descriptions. The description partially compensates for mode by listing example blend modes and linking to a catalog, but it says nothing about clip_id and does not clarify preview behavior 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 clearly identifies the resource and setting: a video clip's blend mode that controls how it mixes with tracks below. It enumerates representative modes and points to a catalog, making the tool distinguishable from sibling clip setters. It is slightly oblique by describing the setting conceptually rather than explicitly saying 'sets the blend mode of clip_id', but the purpose is still 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?

There is no explicit guidance on when to use this tool versus alternatives such as clip.set_transform, clip.set_enabled, or clip.set_mask. The blend-mode concept implies it is for visual compositing, but no conditions, prerequisites, or exclusions are stated.

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

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

Annotations already declare destructiveHint=false and idempotentHint=true; the description usefully confirms the non-destructive effect (clip remains in place, renders as a gap) and notes that an edit result is returned. It stops short of saying the edit produces a new timeline_id, which the schema mentions instead.

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 key behavioral consequence front-loaded; the second sentence delegates return-format detail to the server instructions rather than bloating the definition. No wasted words.

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

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

An output schema exists, so return values need no explanation, but for a mutation tool with two undocumented parameters and no usage guidance the definition leaves real gaps an agent must resolve from the schema alone.

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 only 50%: preview and timeline_id are documented in the schema, while clip_id and enabled are bare. The description only obliquely implies the meaning of enabled=false through 'a disabled clip'; it says nothing about what enabled=true does, what clip_id accepts, or format expectations, so the coverage gap is not compensated.

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 name and title carry the verb (enable/disable), and the description adds the crucial semantic distinction: a disabled clip is not removed but 'stays on the timeline but renders as a gap.' That implicitly separates it from clip.remove, 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?

Usage is only implied — the 'stays on the timeline' framing hints you should pick this over clip.remove when you want to preserve the clip, but there is no explicit when-to-use, no prerequisite, and no mention of the alternative by name.

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?

Goes well beyond the annotations (which only say idempotent/non-destructive): it discloses that the operation runs as its own asynchronous job, that job.list tracks progress, that dependent renders name the job, and that exports wait on it. It also warns about the fill smudge limitation — genuinely non-obvious behavior an agent could not infer elsewhere.

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

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

Front-loads the core action and shape list before the denser coordinate and job details. It is long and somewhat run-on in places, but nearly every sentence carries substantive information; trimming is possible but little is truly 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?

Given an output schema exists, return values need not be explained (it still references 'the edit result'), and the async job, coordinate, and fill behaviors are all covered. A brief note on required permissions or default-mode implications would round it out, but the definition is complete enough to invoke 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 75%, so the schema already documents most parameters; the description adds real value by explaining the fitted-frame coordinate model and the k = aspect-ratio mapping formula, which clarifies how 0–1 coordinates behave on non-matching aspect ratios. It does not cover every param (e.g. preview, timeline_id), but the hard-to-grok spatial semantics are covered.

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

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

Opens with a specific verb and resource ('Select part of a video clip, then show, hide or fill it') and enumerates the exact shape vocabulary, which lets an agent distinguish it from sibling tools like clip.set_transform or create.matte 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?

Clear about operational context: multiple shapes go through 'add', a fill vs show/hide distinction is explained, and 'null removes the mask' signals the removal path. It stops short of naming an alternative tool for related tasks (e.g. when to use create.matte vs a matte mask), so no explicit sibling routing.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=true, so the safety profile is covered. The description adds real behavior: the clip keeps its source, its length changes, ripple moves later clips, and pitch is preserved by default – none of which the annotations convey. It is silent on failure cases and how reverse interacts with rate.

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?

Five short sentences, front-loaded with the verbs then the mode distinction, then side effects, then the return note. Every sentence carries information an agent needs and there is no filler.

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

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

An output schema exists and the description correctly defers to server instructions for the returned edit result, so the return value need not be spelled out. It covers the mode choice and the ripple and pitch side effects, but leaves reverse semantics and the heavy interpolate job behavior entirely 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 coverage is 80%, so the schema already documents most parameters and the baseline is 3. The description still adds meaningful semantics by contrasting rate (constant) with curve (a ramp over the new length) and by stating that preserve_pitch defaults to true. That marginal lift over the schema earns a 4 rather than a 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 concrete verbs (speed up, slow down, ramp, reverse) against a named resource (a clip and its linked clips). That clearly separates it from clip.freeze, clip.trim, clip.slip, and clip.set_animation 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?

Explains the two mutually exclusive modes – constant rate versus a curve ramp – which is the main in-tool choice. It also tells the agent what ripple and other_tracks do by default, but never states when to prefer a sibling such as clip.freeze or clip.trim 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?

Beyond annotations, it discloses that omitted fields keep their value, null resets a field, keyframes are relative to clip start, and the result reports placements in sequence pixels including visible picture and source pixels. This is substantial behavioral context for a mutation tool with idempotentHint=true and destructiveHint=false.

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

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

The core transform purpose is front-loaded and the description is information-dense, but it is a long single paragraph mixing core parameters with advanced tracking and nested-timeline workflows. Those details are useful, though the structure could be easier 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?

For a complex 13-parameter edit tool with an output schema and annotations, the description covers the important non-schema behavior: keyframes, fit semantics, reset behavior, tracking workflow, and placement return information. The output schema handles return details, so no critical agent-facing context is missing.

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

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

The description adds useful meaning for the Animatable parameters, keyframe frame/ease semantics, and scale relative to fit. However, with 13 parameters and 69% schema description coverage, some parameters such as flip and clip_id are left to the schema, and several fit/crop explanations partly repeat schema text.

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 set and resource: position, scale, rotate, fade, flip, crop or fit a video clip over lower tracks. That makes the tool's transform scope clear and distinguishes it from adjacent clip tools such as clip.move, clip.trim, clip.set_mask, and clip.set_blend.

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

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

It gives explicit usage scenarios: fit none for graphics at native pixel size, contain as default, nested timelines for overlays that must follow zoom/pan, and media.analyze track boxes for pinning overlays to moving subjects. It also explains reset behavior and names complementary tools/approaches rather than leaving the agent to infer them.

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

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

Annotations already say readOnly=false, idempotent=true, destructive=false, so the safety profile is covered. The description adds the key side effect an agent would not guess: the preceding and following clips are shortened/lengthened. It does not address edge cases (first/last clip with no neighbour, insufficient adjacent media).

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

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

Two tight sentences, front-loaded with the operation and immediately followed by the mechanism. No filler. Only mild weakness is the somewhat loose 'between its neighbours' phrasing.

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

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

An output schema exists so return values need no explanation, and the pointer to server instructions helps. But for a 4-parameter edit tool with two undocumented parameters, the description leaves out boundary behaviour and the to_frame target semantics, which an agent needs 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 only 50%; clip_id and to_frame have no schema descriptions at all, and the description does not say what to_frame means (target frame of the clip's new start?) or how frames map to the slide. It also omits the fact that timeline_id becomes stale after the edit, even though the schema hints at 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+resource ('move a clip') and explains the distinctive slide semantics: neighbours change length so nothing else moves. This implicitly separates it from clip.move (which shifts others) and clip.roll (which moves a boundary without moving the clip), but no sibling is named.

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 'nothing else moves' phrase implies the right use case, but the description never says explicitly when to pick this over clip.roll, clip.slip, or clip.move, all of which sit adjacent in a large sibling set and sound very similar.

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

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

Annotations already disclose that this is a mutating, non-read-only, idempotent, non-destructive edit. The description adds important behavioral context not covered there: the edit changes source exposure while preserving the clip's timeline position and size, which is central to understanding the operation.

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

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

The description is two sentences, front-loads the core effect, and contains no redundant or filler language. The reference to server instructions for return details is compact and appropriately defers rather than bloating the definition.

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

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

With rich annotations, an output schema, and mostly described parameters, the description supplies enough core semantics to call the tool correctly. It does not explain the new timeline handle behavior, but that is already stated in the timeline_id schema description and output schema context.

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 75%, so most parameters are already documented in the schema, including the sign convention for by_frames and the preview enum. The description reinforces the earlier/later source direction but does not add meaningful semantics for clip_id, timeline_id, or the preview parameter beyond what the schema provides.

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

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

The description states a specific editing effect: showing earlier or later source in a clip without moving or resizing it. This clearly conveys the slip-edit concept and distinguishes it from clip.move and clip.trim, though it does not explicitly differentiate it from siblings such as clip.slide or clip.roll.

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 'without moving or resizing it' gives a useful condition for when this tool is appropriate. However, it does not name alternatives like clip.slide, clip.roll, or clip.trim, so an agent must infer when to choose this tool over those 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?

Adds one genuinely useful behavioral fact beyond annotations: linked clips are split as well, which an agent could not infer from the schema. However, the return behavior is deferred to 'see the server instructions', and it does not clarify what happens at clip boundaries or on a repeated identical split, where idempotentHint=true is questionable.

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 the side effect. No filler or 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?

An output schema exists, so return values need not be explained, but the description leans on 'see the server instructions' instead of stating the edit-result shape, and says nothing about handle invalidation or failure modes for a mutating 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 50%: preview and timeline_id are documented inline, but clip_id and at_frame are not. The description only restates that a frame is the split point without saying which side the frame lands on, and adds nothing about clip_id or the timeline handle.

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: cut a clip in two at a frame, and discloses that linked clips are cut too. It is distinguishable from siblings like clip.trim or clip.roll in spirit, but never names them, so differentiation is left partly 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?

Usage is implied by 'cut a clip in two at a frame', but there is no explicit when-to-use versus alternatives such as clip.trim, clip.slide, or clip.roll, and no preconditions (e.g. frame must lie inside the clip's range).

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=true, so safety is covered. The description adds that one side can be trimmed for J/L cuts and that the return value is the edit result, but it does not elaborate on ripple, other_tracks, or preview behavior beyond what the schema says. With annotations present, this is an adequate but not rich behavioral disclosure.

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

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

Two sentences, front-loaded with the core action and with no wasted words. The second sentence packs the J/L cut detail and return-value note efficiently, though it could be slightly clearer about what 'the edit result' entails.

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

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

The tool has 8 parameters (4 required), an output schema, and annotations, so some complexity is handled elsewhere. However, the description omits behavior of ripple, other_tracks, and preview, and gives no differentiation from closely related siblings, leaving meaningful gaps for an agent selecting and invoking this 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 75%, so the schema already documents most parameters, including intricate options like other_tracks and ripple. The description only restates the edge movement and briefly mentions the side parameter for J/L cuts; it adds little beyond the schema's own field descriptions. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb and resource: 'Move the start or end edge of a clip', which clearly identifies the trimming operation. However, it does not distinguish this from sibling tools like clip.roll, clip.slip, or clip.slide that also alter clip boundaries, leaving an agent to infer the difference.

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

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

No when-to-use or when-not-to-use guidance is provided, and no alternatives are named. The mention of 'side: video or audio trims one half of a link group (J/L cuts)' explains a parameter effect but does not help an agent choose between this tool and siblings such as clip.roll or range.extract.

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

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

Annotations already declare non-destructive, idempotent, closed-world mutation, so the safety profile is carried structurally. The description adds the key ambiguity it should resolve but doesn't: whether the whole group is dissolved or only this clip detaches, and what happens if the clip isn't linked. Pointing to 'the server instructions' for the return value is a deferral rather than disclosure.

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

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

Two short sentences with the action front-loaded and zero filler. The parenthetical pointer to server instructions is the only soft spot, trading brevity for a cross-reference the agent has to chase.

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

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

An output schema exists and annotations cover safety, so the remaining burden is small but real: the scope of the break (single clip vs. entire group) and the no-op/error case for an unlinked clip are unaddressed. For a state-mutating timeline tool, those are the questions an agent most needs answered.

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?

At 67% schema coverage, the schema documents preview (with enum meanings) and timeline_id (the new-handle semantics), while clip_id has no description at all. The description only implies clip_id via 'a clip belongs to' and says nothing about preview, so it neither compensates for the gap nor adds 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?

States a concrete verb and object ('Break the link group a clip belongs to'), which an agent can map cleanly against sibling clip.link as its inverse. It stops short of naming the sibling explicitly, so it is clear but not fully differentiated in 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?

No when-to-use or when-not-to-use guidance. Nothing tells the agent how this differs in practice from clip.remove (which likely also detaches a clip) or that it should be used only when the clip is actually part of a link group.

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

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

Annotations declare non-read-only, idempotent, non-destructive, but the description adds the key behavioral fact they do not: transactional semantics ('all apply or none do') and that each call yields one new timeline_id plus one preview. It also discloses the return envelope (results per op), going beyond the annotation set.

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

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

Three dense sentences, front-loaded with the core contract (atomic batch, one timeline_id, one preview) before the $ref mechanics and return shape. No filler or restatement of the name/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?

Covers atomicity, cross-op referencing, and return shape; an output schema exists so return value detail is not required. Minor gap: no mention of the 200-op cap or ordering-failure diagnostics, though the schema carries maxItems and minItems.

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, but the description earns extra credit by generalizing the $ref mechanism beyond the schema's single example: it shows forms for clip_id, track_id, and clip_ids[M], clarifying that any arg may reference an earlier op's created id.

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 ('Apply many edits as one change') and immediately names the distinguishing property: a single new timeline_id, a single preview, and all-or-nothing atomicity. An agent can tell this apart from the ~40 single-operation siblings 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?

The atomicity framing ('All apply or none do') implicitly tells the agent when to reach for this instead of chaining individual sibling tools, and the $ref note points to ordered multi-op workflows. It stops short of explicitly naming alternatives or stating when not to batch.

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

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

Beyond the annotations it discloses that this is best-effort with a warnings list naming what could not carry (masks, blend modes, effects, ramps, text styling), that reference media expires 7 days after last use, that the call is long-running via task or job_id, and that the result carries a signed download URL. The one gap is that destructiveHint=true is never explained — nothing says what gets destroyed or how overwrite relates to it.

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

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

Front-loaded with the purpose, then the lossless alternative, then caveats, then media modes, then the async mechanics — a sensible order with no filler sentences. The telegraphic, parenthetical style ("(masks, blend modes...)", "(the result warns)") is dense but occasionally reads as notes rather than prose.

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

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

For a long-running export with an output schema and a warnings channel, the description covers what an agent must decide before calling: format, media mode, and how to handle the async result. Return format is legitimately delegated to the output schema, and the lossless-vs-lossy fork is resolved.

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 67%, so the schema already documents the enums. The description restates format and media semantics rather than adding to them, though it does add the 7-day expiry rationale for reference media. It says nothing about filename, overwrite, or idempotency_key, which is the un-covered third.

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?

"Write the edit for another editor" states a specific verb and outcome, then enumerates the concrete artifacts (fcpxml, otio, edl, srt/vtt). It explicitly distinguishes itself from timeline.get ("the lossless copy") and implicitly from export.video by naming the interchange formats, so an agent can pick it out of a 60+ sibling list.

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 selection rule for every format by naming the target application (FCP/Resolve, Premiere/OTIO, CMX 3600, captions) and routes lossless copying to timeline.get. It also states when to choose media collect over the default reference, with the reason (handing the edit to another machine).

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?

Goes well beyond the annotations: discloses that the call is long-running and returns a task or {job_id}, that download/page URLs expire in 24 h, and that the server retains the file only 7 days. It also describes the return payload (resource_link, signed URL, page_url, sha256, fingerprint), which the destructive/idempotent hints alone would never convey.

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

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

Front-loaded with the core action and preset list, then lifecycle details. It is dense and a few sentences run long (the URL/retention sentence is overloaded), but nearly every clause carries operational 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?

For a 7-parameter, nested-object, long-running export tool, the description covers presets, overrides, async behavior, output shape, URL expiry and retention. Even with an output schema present, the extra lifecycle context makes the definition self-sufficient.

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

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

Adds meaning beyond the 71%-covered schema: each preset is described with container, resolution and use case (e.g. review_h264 as a small quick cut to watch), overrides are explained as a size box/fps/bitrate/quality change, and filename's default is stated. The idempotency_key and overwrite parameters are left unexplained, keeping it from a 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?

Opens with a specific verb+resource: 'Render the timeline to a file.' That is unambiguous about what the tool produces. It does not, however, distinguish itself from the sibling export.timeline, which an agent would reasonably confuse with this one.

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 real routing guidance: run qa.check to measure a render before exporting, use job.get for fresh URLs, and media.import to reuse a file after the 7-day window. It stops short of stating when to prefer export.timeline or render.frames instead, so no 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?

Adds a lot beyond the annotations: ordering semantics, that picture params accept keyframes except glitch/denoise/chroma_key tolerance, that sound params are constants, and that invalid names/params are rejected with the full list, ranges, units and defaults (also at video://catalog/effects). One soft tension with idempotentHint=true: 'effects run in the order added' implies calling twice stacks two effects, so repeated invocation is not state-neutral, and the description never reconciles this.

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 dense paragraph, front-loaded with what gets the effect and where; every clause carries information. It is long, but the length is earned by the number of distinct behavioral rules packed in, with few wasted words.

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

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

Covers targeting, ordering, keyframe limits, error recovery via the effects catalog, the returned id, and defers return-shape detail to the server instructions (an output schema exists). The only gap is the idempotency/stacking question an agent would face when re-applying an effect.

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 86%, so the schema already documents nearly all parameters; the description mostly reinforces it. It does add genuinely extra meaning (which effect families take keyframes vs. constant params, that params omitted take defaults, the refusal-with-details error contract), but it adds no format/syntax detail for the params object itself.

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 ('Apply an effect') plus the three possible targets (clip, all clips on a track, whole timeline) and enumerates the effect families (colour, LUT, blur, EQ, compressor...). The purpose is unambiguous, but it never names the adjacent filter.set / filter.remove siblings, so the agent must infer that this tool only creates effects and does not modify them.

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

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

Gives concrete selection rules for each targeting parameter ('Apply to one clip', 'or true for the whole picture or mix', 'or to every clip on a track'), plus an evaluation-order rule (a track's effects run before a clip's own). It does not say when to use filter.set or filter.remove instead, which is the main missing piece.

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

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

Annotations already declare the operation is a non-read-only but non-destructive, idempotent local mutation, so safety is covered. The description adds that an edit result is returned and defers its shape to the server instructions, which is useful. It does not say what happens if filter_id is unknown, whether the removal fails silently, or how the remaining effect stack is affected.

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 the action front-loaded and a pointer for return values; no filler. The brevity is efficient, though it shades into under-specification rather than verbosity.

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

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

An output schema exists so return values needn't be spelled out, but for a mutation tool this leaves real gaps: no source for filter_id, no behavior on missing/invalid ids, and no note that the timeline handle changes after the edit (only visible in the schema). Not enough for an agent to call it confidently.

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

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

Schema coverage is only 67% and filter_id has no description anywhere; the description contributes zero parameter meaning, notably not telling the agent where a filter_id comes from (filter.add / timeline.get). preview and timeline_id are already documented in the schema, so only the undocumented id remains, and it is unaddressed.

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?

"Take an effect off" names a verb and a resource, so the basic action is inferable, but it is close to a restatement of the title "Remove effect" and uses "effect" rather than the schema's "filter". Nothing distinguishes it from siblings like transition.remove, clip.remove or filter.set.

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

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

There is no statement of when to use this versus filter.set (modify) or transition.remove, and no prerequisites such as the filter existing on the timeline. The agent must infer the routing decision entirely from the tool name.

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

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

Annotations already declare mutation, idempotency, and non-destructiveness. The description adds useful detail that params are merged and that the effect can be enabled/disabled, plus a pointer to return behavior, but does not explain permission needs or full side effects.

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

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

The definition is two short sentences with no filler, and the main action is front-loaded before the return-value note. Every phrase contributes to understanding.

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

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

An output schema exists and annotations cover the safety profile, so the description need not explain return values or mutation risk. However, the description lacks context around preview behavior, required identifiers, and sibling differentiation, leaving gaps for a five-parameter mutation 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 60%, so some parameters are already documented. The description clarifies that params are merged and that the tool can turn the effect on/off, but it does not explain filter_id, preview modes, or the required timeline handle beyond what the schema provides.

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

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

The description states a specific action: change an effect's params or toggle it on/off. It clearly distinguishes mutation of an existing filter from creation or removal, though it does not explicitly name sibling tools like filter.add or filter.remove.

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 described operations, but there is no explicit guidance on when to use filter.set versus filter.add, filter.remove, or text.set. The agent must infer the appropriate context.

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?

Goes well past the destructiveHint/idempotentHint annotations by stating the actual mechanics: engines are killed, the slot is released to the next job, and terminal jobs are unaffected. That last clause effectively documents no-op semantics for already-finished jobs, which the annotations cannot express.

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

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

Two short sentences, zero filler, with the scope constraint and the effect front-loaded before the edge-case clause. Every clause carries information an agent would otherwise have to guess.

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

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

An output schema exists, so return values need not be explained, and the description covers scope, timing, and side effects. It leaves open whether cancellation is reversible and what error or result occurs when the job is already terminal.

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

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

Only one parameter and the schema already documents it fully at 100% coverage, including the pattern and the note that it doubles as the MCP task id. The description adds no additional meaning about job_id, 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?

Specific verb plus resource ("Stop a job") with an explicit scope qualifier ("queued or running") and a concrete timing claim ("within seconds"). An agent can immediately tell this apart from job.get or job.list, which read state rather than terminate work.

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?

"Finished jobs are left as they are" is an implicit when-not condition that prevents pointless calls on completed jobs. It does not name sibling alternatives (job.get/job.list for status checks), so it stops short of full routing guidance.

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

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

Beyond the read-only and idempotent annotations, the description discloses important behavior: wait_seconds can block until any requested job finishes, fails, or is cancelled; progress does not end the wait; stalled jobs eventually error out; and result summaries truncate lists. These details materially help an agent predict what a call will do.

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

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

The description is front-loaded with the core purpose, but it is a dense run-on paragraph with semicolon-separated clauses and some repetition of schema parameter details. It is informative but could be structured more cleanly for faster scanning.

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

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

Given the output schema, rich annotations, and full schema coverage, the description is complete enough for an agent to call the tool correctly. It covers waiting behavior, batch reads, result summarization, and stalled-job handling without needing to explain return values in detail.

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

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

Schema description coverage is 100%, and the schema already documents job_id, result defaults, job_ids batch behavior, and wait_seconds semantics. The description largely restates those parameter meanings rather than adding substantial new parameter-level guidance, so the baseline of 3 is appropriate.

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

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

The description states a specific verb and resource: it returns status, progress, and completed results for long-running jobs, with concrete examples like media.import and export.video. It is clear what the tool does, though it does not explicitly contrast itself with job.list or job.cancel.

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 main usage context: checking long-running calls, waiting instead of polling repeatedly, and reading many jobs at once via job_ids. It does not explicitly state when to use job.list or job.cancel instead, so the alternative-selection guidance is not complete.

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

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

Annotations already cover readOnly/idempotent/non-destructive, so the bar is lower, and the description still adds real behavior: results are omitted by default to keep the listing light, with opt-in 'summary' or 'full'. It doesn't mention the limit cap or what happens when more jobs exist than the limit, leaving a pagination 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?

One dense sentence that front-loads ordering and returned fields before the filters, with the default-exclusion rule and the sibling pointer at the end. Every clause carries information, though the phrase 'and for (the media or timeline it is for)' is awkward and slightly costly to parse.

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

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

An output schema exists, so return values needn't be described, and the description covers filtering, verbosity control, ordering and the alternative tool. The only meaningful omission is how limit interacts with result size and whether results are truncated.

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 60% and the description reinforces the filter semantics of tool, status and media_id ('importing, making or reading it') and the three result modes. However, 'limit'—the one undocumented parameter in the schema—is never addressed in the description, so the coverage gap remains unclosed.

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

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

States a specific verb (list) and resource (jobs) plus ordering ('newest first') and the per-job fields returned (status, progress, target), then names the sibling 'job.get' that reads a single job. An agent can distinguish this from job.get and job.cancel without opening any schema.

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

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

Explains the workflow split: this tool finds a job, and 'job.get reads one' once you know which. It also states results are excluded by default unless requested, which shapes how to call it. It stops short of explicit when-not-to-use guidance (e.g. preferring job.get for a known id).

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

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive, and the description adds context beyond them: statelessness ('Each call stands alone, so put everything a judgment needs into its state'), capacity limits (300 questions, 8 pictures, 200k characters), latency ('about a second'), and that the model is a preview.

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 and limits are front-loaded, but the body is a dense run-on of inline examples with no headings or lists despite the highly structured content. The filler-word example in particular requires re-reading, and the paired criteria example does not clearly map to the filler question.

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 nested two-parameter tool with an output schema, the description covers everything an agent needs: entry formats, question types and criteria shapes, per-call limits, statelessness, and links to fuller guides. Return values need not be described because the output schema exists.

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

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

Schema coverage is 100%, so the baseline would be 3, but the description adds real meaning: backtick entry references ('in `passage`'), the interpretation rule '0.5 or more reads as yes' for noul, 'score (0 is the first level)', and 'box {x, y, w, h} in fractions of that picture'.

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

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

The opening states a specific verb and resource ('Answer your questions about text and pictures you give'), enumerates the four answer shapes (yes/no, choice, score, box), and names the underlying model (TypeSafe Jev). It also distinguishes the tool from media.seek and media.analyze by describing what each does instead.

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 routes the agent explicitly: 'To find where something shows in a video or an edit, media.seek takes it in plain words; to measure every frame, media.analyze look asks your questions of frames it samples.' It also gives selection guidance for the question subtypes ('Choose the type by the answer you need') and a batching rule ('judge many items together').

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

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

Beyond the supplied annotations the description discloses persistence rules (results kept with the media via media.get include, except track, silence, scenes and loudness which return inline), truncation behavior (long transcripts return as summary plus a note), failure modes ("fails with no_audio, naming it"), execution model (returns a task or job_id for job.get), cost (speakers ~10-20 s per minute of media), and hard limits (600 frames, 32 questions, last 10 look runs). These are exactly the behavioral traits the annotations cannot express.

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 initial purpose sentence is well front-loaded, but the body is a single semicolon-chained run-on enumerating 14 kinds, followed by a very long "HOW LOOK WORKS" tutorial with external doc links. Given the 14-kind surface area most content earns its place, but the presentation is hard to scan and it repeats the enum descriptions verbatim from the schema instead of trusting them.

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

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

With an output schema present, 96% schema coverage and rich annotations, the description fills the remaining gaps an agent needs: which kinds persist vs return, which parameters are required per kind, timeline vs media semantics, and the sampling/limit constraints. Nothing material is missing for correct invocation.

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