WeftCut

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

Annotations only declare openWorldHint=false and destructiveHint=false, so the description must supply the rest. It does add real behavioral context, such as catalog defaults, the audio params STATIC ONLY restriction, and the denoise profile_in_us/profile_out_us requirement with a 250000 µs minimum. It omits ordering or chaining side effects for the existing chain and does not say whether the append is atomic or reversible.

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?

It is front-loaded with the action and the return shape, and nearly every clause carries operational information. The long parentheticals and backtick-heavy sentences make it dense to parse, but 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?

There is no output schema, and the description compensates by naming the returned record fields and the failure mode EffectKindNotApplicable. Combined with the catalog reference for ranges and defaults, it is complete enough to call correctly, though it does not cover whether appended effects can be reordered afterwards.

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

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

Schema coverage is already 100%, yet the description adds meaning the schema lacks: unset params fall back to catalog defaults, values are plain numbers, chromakey keyR/keyG/keyB are 0..1 rather than 0..255, and audio params cannot be keyframed. The keyframing path effects[<effect_id>].params[<key>] is described nowhere in the schema.

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

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

The description opens with a specific verb, resource, and placement: "Append an effect to a layer's chain (applied last)", and then names the returned record fields. An agent can distinguish this from update_effect, move_effect, and delete_effect because the append/applied-last semantics are stated 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?

It gives strong applicability rules: visual kinds go on visual layers, audio.* kinds go on Audio layers ONLY, and a mismatch raises EffectKindNotApplicable. It does not explicitly route to update_effect or set_keyframe as alternatives for later changes, so it stops short of full when-to-use/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?

Goes well beyond the supplied annotations by disclosing preservation of external placement, refusal conditions, and the return value. These details materially help an agent predict behavior 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?

Front-loads the action, then preconditions, refusal cases, and return value in a compact sequence. Every sentence contributes useful information with no 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?

Complete enough for a two-parameter mutation tool: it explains the action, prerequisites, failure modes, and return value despite no output schema. The unexplained 'compatible selection' and 'Group rate 1' keep it just short of fully self-contained.

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

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

Schema coverage is 100%, so the schema already documents both parameters. The description still adds operational meaning with the Group rate 1 requirement and compatible-selection constraint, though those constraints remain somewhat vague.

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: moving selected clips into an existing Group. It clearly distinguishes this from create_group and ungroup_layer by emphasizing an existing Group and preserved external placement.

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

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

Gives clear operating conditions: Group rate 1, compatible selection, and refusal cases for partial links, locked members, and cycles. It does not explicitly name sibling alternatives such as create_group, but the when-to-use context is strong.

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 openWorldHint=false and destructiveHint=false, so the description carries the real burden and does: transactionality ('any refusal commits none'), lane-overlap refusal, auto-placement of a Video's dialogue audio as a linked layer, refusal of an occupied audio lane 'naming the blocker', and implicit track creation in the same edit. It also spells out the exact return shape including `adjusted` and `linked`, which no output schema supplies.

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 atomicity guarantee and the batch limit, then walks through kind selection, track behavior, audio linking, and return shape in a logical order with zero filler. It is a single dense paragraph that leans on semicolons, and a few clauses echo the schema's enum descriptions, so it is tight but not maximally efficient.

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 batch-mutation tool with nested discriminated content, it covers atomicity, refusal semantics, track auto-creation, linking side effects, ordering of results, and the return payload — everything an agent needs to call it without follow-up. With no output schema present, the inline return description closes the last gap.

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

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

Schema coverage is 100%, so the baseline would be 3; the description earns above that by adding cross-parameter constraints the schema does not encode — that layers on one lane cannot overlap, that a missing `track_id` creates a fresh track within the same edit, and that the audio lane is shared between linked picture-and-dialogue pairs. Some of it (kind → layer type) merely restates the discriminated union, keeping it below 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 a specific verb and resource with a distinguishing property: 'Place 1–50 layers in ONE recorded edit, all or nothing'. The batching-plus-atomicity framing separates it from single-layer siblings like update_layer_params or paste_layers without the agent needing to inspect 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?

Gives concrete routing rules: 'Audio-only media is kind `audio`, a still kind `image`; a subtitle document is `apply_subtitles`' — the last one explicitly hands the agent to a sibling tool. It does not, however, say when to prefer this over paste_layers or create_group for the same outcome, so the alternative-selection guidance is incomplete rather than absent.

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 openWorldHint=false and destructiveHint=false, so the description carries the real behavioral load and does so: it discloses the return record (marker_id, t_us) and, importantly, that t_us is returned 'as snapped' — a non-obvious side effect an agent would otherwise miss. It also notes that an invalid anchor is refused with no marker created, though it says nothing about permissions or duplicate-marker behavior.

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

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

Front-loaded with the action and target, then each subsequent sentence handles exactly one decision (region, anchor, color). No filler, no repetition of the name, and the most consequential fact (the return record) appears early.

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

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

For a 7-parameter mutation with a nested color object and no output schema, the description covers the return shape, the snapping behavior, and both optional modes, which is most of what an agent needs. Gaps are minor but real: nothing on permissions, on whether markers may overlap or duplicate, or on ordering relative to other timeline edits.

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 3 is the baseline, but the prose adds genuine framing: it recasts t_end_us and anchor_layer_id as selecting between point/region and fixed/following modes rather than merely documenting types. It also states the color default, which the schema only gestures at with 'omit for the default.'

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

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

The description opens with a specific verb and resource ('Add a marker (point or region)') plus the exact target ('a composition's timeline — the root, or the Group named by composition_id'). It also enumerates the two marker variants, which lets an agent distinguish this from update_marker, delete_marker, and set_marker_anchor 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?

It gives clear conditional guidance for the optional modes: set t_end_us for a region, set anchor_layer_id to make the mark follow a clip, omit it for an ordinary marker, and color falls back to the timeline default. It stops short of stating when to use this versus modifying an existing marker with update_marker or tying an anchor later with set_marker_anchor.

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 non-destructive and closed-world; the description adds the substantive lifecycle rule that a track vanishes when its last layer leaves it, and that a track created empty survives until filled and then emptied. That is genuine behavioral context an agent could not get from the annotations or schema. The final clause is a little dense but still discloses real state semantics.

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

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

Front-loads the action and return fields, then follows with behavioral caveats, so an agent gets the essentials in the first clause. The final sentence ("survives until it has been filled and emptied") is somewhat convoluted and partially restates the prior sentence, costing a point.

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

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

With no output schema, the description usefully names the return fields, and with no required parameters and only two optional ones, little else is needed. The lifecycle note covers the main non-obvious risk (empty tracks disappearing), leaving only minor gaps like ordering or error behavior.

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

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

Schema description coverage is 100%, and both `label` and `composition_id` are already documented in the schema with their defaults and lookup path. The description adds no additional meaning about these parameters, so the baseline 3 applies.

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

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

States a specific verb and resource ("Add a track") and even enumerates the returned record fields (`track_id`, `index`, `composition_id`), which makes the operation unambiguous. It does not explicitly distinguish itself from creation-adjacent siblings such as `create_tacks` or `add_layers`, so sibling differentiation is left implicit.

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 guidance on the right workflow: "place a layer rather than reserving a track," which steers the agent away from pre-creating empty tracks. It stops short of naming an explicit alternative tool or stating when to use `create_tacks` instead, so no exclusions are spelled out.

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

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

Annotations only declare openWorldHint=false and destructiveHint=false, so the description carries the burden and does it well: 'overlap' moves the incoming layer with no ripple, linked siblings follow and bounce to a free lane; 'extend' borrows outgoing tail media and returns extended_us; failures surface as TransitionInsufficientHandle and TransitionUnsupportedLayerKind; one undo restores every moved layer.

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?

Purpose and participants are front-loaded, and nearly every clause conveys a distinct constraint or side effect. It is still a dense wall of em-dashed, bolded fragments that takes effort to parse, and the placement explanation could be tightened without losing content.

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

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

For a mutating timeline tool with no output schema, the description covers return value ('its record'), both placement behaviors, the exact-overlap no-op case, four refusal classes, and undo granularity. An agent has everything needed to call it correctly on the first attempt.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters and the baseline is 3. The description does add genuine meaning beyond it — 'direction' is the MOTION direction with a concrete worked reading of 'left', and the placement modes describe what each does to positions and trimmed ranges — but much of this overlaps the enum 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?

Opens with a specific verb and resource plus the exact precondition: a transition at the cut between two adjacent layers on the same track, with from_layer_id ending where to_layer_id starts. This distinguishes it cleanly from the sibling update_transition and delete_transition without needing to open any schema.

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

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

Gives clear in-context routing for the three variants ('kind' default Crossfade, 'direction' required for Wipe/Slide and rejected for Crossfade) and enumerates refusal conditions. It does not explicitly name a sibling alternative (e.g. use update_transition to modify an existing one), so it stops short of full when-to-use/when-not-to-use guidance.

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

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

Goes well beyond readOnlyHint/openWorldHint by disclosing that it is local, model-free, cache-derived, and explicitly not true-peak or LUFS, and that max_points affects only the summary. The formula for landing src_us at timeline T and the 60 s cap are real operational constraints an agent cannot infer elsewhere. No output schema exists, however, so the return-shape disclosure (peak/RMS bins, onset candidates, dB deltas, counts) is present but terse.

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: capability, scope, return shape, then caveats, then the coordinate note. Dense and largely waste-free, though the trailing parenthetical formula is telegraphic and harder to parse than the rest.

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

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

With no output schema, the description does the work of naming the returned fields and units, and it flags the cache dependency and per-call duration ceiling. It omits what happens on a cache miss or for uncached media, a gap for an analysis tool an agent may call repeatedly.

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

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

Schema coverage is already 100%, so the baseline is 3; the description earns extra by clarifying that max_points changes only summary bins and not event detection resolution, and that src_* values are source-absolute microseconds. The rate/t_start_us mapping formula adds cross-tool meaning the schema does not carry.

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 ('Analyze original source audio from cached waveform peaks') plus scope ('original audio before mix/effects'), and explicitly rules out what it is not ('amplitude measurements, not beats, bars or melody recognition'), which separates it from siblings like detect_pauses and transcribe_clip. It never names a sibling directly, so differentiation is by category rather than by tool.

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?

'Choose music edit/alignment points, including outside a clip's trim' gives a concrete when-to-use context, and 'At most 60 s per call' plus the src_us mapping formula imply the chunking workflow. It stops short of explicit when-not guidance or naming the alternative tool for beat/key/tempo needs.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuine behavioral context: determinism, the 3-frames-per-shot sampling basis, that 'spans' requires 'one sampled decode of the source' (a cost signal), and exact numeric thresholds behind every flag and span kind. It omits error behavior and any runtime/performance expectation for the default passes.

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?

Everything present is substantive — return shape, stat formulas, flag and span thresholds — and the purpose is front-loaded. However, it is delivered as one dense semicolon-chained paragraph in heavy backtick notation, making it hard to scan for the one or two facts an agent needs at call time. No sentence is wasted, but structure is not doing the reader any favors.

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

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

With no output schema, the description correctly carries the full return-value burden: it enumerates the response fields, defines every stat (brightness midpoint mean, motion as 1 - SSIM, sharpness as relative Laplacian variance), and specifies each flag and span kind with thresholds. An agent can interpret results without any external documentation.

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

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

Schema coverage is 100%, so the baseline is 3; the description exceeds it by supplying the mapping formula (t = t_start_us + (src - src_in_us) / rate) and by tying media_id/layer_id to their scoping difference (whole source vs clipped-to-played-range). It largely restates the schema's own parameter descriptions, so it is additive rather than transformative.

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 resource and output: 'Shots and defect spans of a video's source, deterministic.' It is a noun phrase rather than a verb+resource statement, but it is unambiguous about what is produced and clearly distinct from siblings like describe_clip or analyze_audio. It also names auto_split_by_shot as the action counterpart, further anchoring its role.

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

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

Gives explicit routing to an alternative ('To split: `auto_split_by_shot`') and, more importantly, precise guidance on the passes parameter: default shots/stats/events, `["shots"]` for timing only with no frame sampling, and `"spans"` as an opt-in cost-bearing pass. It does not state preconditions (must the media be imported? must the layer exist?) or contrast with compare_frames/describe_clip, so it stops short of full when/when-not coverage.

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 openWorldHint=false and destructiveHint=false; the description adds what those annotations cannot: the whole apply is a single recorded edit (undo unit), the packing policy (first unlocked caption track with room, new track only on collision with all), and that advanced ASS styling is simplified rather than preserved.

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 one-write semantics, then placement, then side effects, then return shape — efficient. A few phrases ('opening a new one only where it collides with all of them') are dense but each sentence carries information.

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

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

For a three-parameter mutation with no output schema, the description covers prerequisites, undo granularity, track-allocation behavior, fidelity loss (ASS simplification), and the return payload `{ caption_track_id, cues, simplified }`. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so both optional parameters and media_id are already documented; the description adds only the framing that the document's time 0 maps to `t_start_us`, and does not expand on `composition_id` beyond the schema's Group-id guidance. Baseline 3 for full-coverage schema is appropriate.

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

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

States a specific verb and resource ('lay an imported Subtitle item onto the caption tracks as one editable Text layer per cue') and names the source producer (`import_media`), so it is distinguishable from import_media, apply_transcripts, and merge_captions 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?

Prerequisite is implied by tying the input to a `Subtitle` item from `import_media`, which tells the agent what must happen first. However, there is no explicit statement of when to prefer this over sibling tools like apply_transcripts, merge_captions, or export_captions, nor any 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 only declare openWorldHint=false and destructiveHint=false, so the description carries most of the burden and does so well: it discloses that cues are rebuilt to the style's caption limits (lines broken, long segments split), that stale sources are refused, that cues pack into existing tracks and open a lane only on collision, that cues snap to frames, that at most 1000 transcripts are accepted, and that the call counts as 'one recorded edit'. It even states the return shape and ordering.

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

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

The description is dense and front-loaded with the core action, and every sentence carries operational information. Some clauses are crammed together ('...`word_timing: 'none'`, unsplit: cues are built to the style's caption limits'), which slightly hurts scannability, but 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?

There is no output schema, yet the description states the return value (`{ caption_track_id, cue_layer_ids }`, cues in time order) and the cardinality limit, plus failure behavior for stale sources. For a two-parameter write tool with full schema coverage, nothing an agent needs in order to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description still adds value by clarifying that `composition_id` defaults to root and that supplied cues need not be pre-split — they are split to the style's limits. That meaning goes beyond the field-level schema text, though the `word_timing` enum values themselves are only restated from the schema.

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

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

The description opens with a specific verb and resource: 'Lay transcripts on the caption tracks of `composition_id`', and immediately scopes it with 'keeping per-word timing'. This distinguishes it clearly from `transcribe_clip` (which produces transcripts) and from `merge_captions`/`apply_subtitles`, so an agent can route without opening the schema.

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

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

It gives explicit input paths: pass `transcribe_clip`'s `transcripts` as is, or supply your own cues with `word_timing: 'none'`. It also states a concrete when-not condition — a transcript whose `source` clip changed is refused and must be re-transcribed. It stops short of naming sibling alternatives such as `apply_subtitles` or `merge_captions`, leaving that comparison implicit.

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 destructiveHint=true; the description goes well beyond by specifying exactly what is destroyed (short shots and the overlapping members of their link), that link partners are cut alongside the target, and that a no-cut clip returns the original id unchanged. That is precisely the mutation and side-effect detail an agent needs before calling a destructive tool.

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

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

Three dense sentences, front-loaded with the action, then parameter behavior, then return shape. Nothing is padded and no sentence is redundant with the others.

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

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

With no output schema, the description carries the return contract and does so well: layer_ids in timeline order, the single-id no-cut case, and the siblings structure with segments. The remaining gap is failure/prerequisite behavior when shot analysis is not cached, which is left unstated for a destructively annotated tool.

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

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

Schema coverage is 100%, so all three parameters are already documented, and the description largely restates the schema's defaults (min_shot_us 500000, drop_short false, link-member deletion). It adds no formats, ranges, or constraints beyond what the schema provides, so the baseline 3 applies.

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

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

Names a specific verb (split), a specific resource (VideoClip), and the exact mechanism (cached analyze_clip shot cuts) applied 'as one edit'. That mechanism implicitly distinguishes it from the generic split_layer sibling, which cuts at a caller-supplied point rather than at detected shot boundaries.

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 'cached analyze_clip shot cuts' implies the prerequisite that analyze_clip must have run first, and the drop_short sentence explains a conditional mode. However, there is no explicit statement of when to prefer this over split_layer, nor any exclusion such as what happens if no cached shot data exists.

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?

Despite annotations already covering idempotency and non-destructiveness, the description adds substantial behavior: the user's undo is locked and `reason` is displayed instead of it, while the agent's own undo/redo/jump_to/restore_checkpoint keep working. It also discloses the repeat-call semantics (lock only changes when explicitly passed), the cross-connection conflict and the `AgentSessionBusy` error name, and that the call is unrecorded. That is far beyond what the annotations 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?

Roughly six sentences, each carrying distinct information (what is created, lock semantics, repeat behavior, conflict/force behavior, termination, return fields), with the core purpose front-loaded. Backticked identifiers keep it scannable 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?

There is no output schema, but the description still names the returned fields (`locked`, and `taken_over` after a force). Combined with the lifecycle and conflict behavior, an agent has everything needed to call this correctly in a multi-connection setting.

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 a 3, but the prose genuinely extends meaning: `lock` is tied to a concrete consequence (the user's undo is frozen, and passing it on a repeat call is what changes the lock), `reason` is tied to where it is rendered, and `force` is tied to ending another connection's session. Only `force`'s destructive nuance versus `destructiveHint: false` is left implicit.

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

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

The description opens with a specific verb and resource ("Begin a work session for a batch") and immediately enumerates what the session creates: a Pre-agent checkpoint, a review baseline pinned to it, and a lightweight agent view. It also names its counterpart (`end_agent_session`), so the agent can separate the begin/end pair from the many other project-mutation 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?

Usage context is clear: call it to open a batch's work session, it is idempotent on the same connection, and an occupied session refuses with `AgentSessionBusy` unless `force: true` is supplied. It also states the lifecycle exits (`end_agent_session`, user action, connection close). It stops short of an explicit "use this before/after X" rule relative to siblings like `create_checkpoint`, but the when-to-use picture is essentially 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 declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds genuinely non-obvious behavior beyond that: cancellation drains active work before releasing the project edit lock, and the caller must poll get_export_status until a terminal state. It does not say whether partial output is deleted, which is the remaining gap.

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

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

Two short sentences with the action front-loaded and zero filler; the second sentence carries the behavioral payload. 'From either entry point' is the only phrase that costs clarity without adding actionable meaning.

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

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

For a one-parameter mutation with no output schema and annotations covering destructiveness and idempotency, the description supplies the key lifecycle facts: in-flight work is drained, the project edit lock is released, and the caller must wait for a terminal status. Only the fate of already-produced output is unaddressed.

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

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

Schema coverage is 100% and the single job_id parameter is documented in the schema as an application-session export job id. The description adds nothing about job_id format or where to obtain it, so the schema carries the full burden and baseline 3 applies.

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

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

States a specific verb plus resource (cancel/discard an export) and names the follow-up tool, get_export_status, so it is distinguishable from start_export, retry_export and get_export_status. The phrase 'from either entry point' is vague about which entry points, slightly blurring the scope.

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

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

Usage is implied rather than stated: it tells the agent what to do after cancelling (poll get_export_status until terminal), but never says when to cancel versus retry_export or leave the export running. The alternative tool is named, but the selection condition between them is not.

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 say readOnly/openWorld=false; the description goes well beyond that by disclosing that 'the whole composition is checked and remembered' and that the time range only narrows returned findings. It also scopes what is validated ('Project data only — text extents are estimated'), which is exactly the kind of caveat an agent could otherwise misread as a bug.

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 action and rule source, then severity semantics, then caveats, then timing advice — a sensible order. The inline return-shape snippet is dense but earns its place since there is no output schema; a slightly lighter rendering would read better.

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

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

With no output schema, the description supplies the return shape, severity taxonomy with required agent behavior, scope limitations, and invocation timing. Nothing an agent needs to call and act on this tool correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: t_start_us/t_end_us do not scope the check itself, only which findings are returned. That stateful nuance is not in the schema wording ('Only findings overlapping from here').

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

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

States a specific verb and resource — checking a composition against craft rules and project taste — and names the concrete source of truth (skill craft/rules.md). No sibling tool does validation, so the role is unambiguous against the surrounding edit/restyle/motif tools.

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

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

Gives explicit timing: 'Run it after your edits and after fixing,' and the severity definitions tell the agent what to do with each outcome (hard = fix before handoff, warning = fix or leave a tack, review = confirm). No explicit when-not-to-use or named alternative, which keeps it short of a 5.

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

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

Annotations already declare readOnlyHint and closed-world, so "Read-only" is redundant; the description earns credit instead by disclosing scope limits (video only), error behavior (errors naming the offending side), and precise interpretation thresholds (0..64 hamming, 20+ = different scene, similar = hamming<=10 && ssim>=0.5).

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

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

One dense but well-ordered sentence: purpose first, then input shape, then return values, then caveats — no filler, and each clause carries distinct information.

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

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

With no output schema and a nested two-object input, the description fully specifies the return triple and how to interpret it, the accepted side shapes, and failure behavior — nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so baseline would be 3, but the description adds real meaning beyond the schema: it clarifies the `{ media_id | layer_id, src_us }` shape is an XOR of one media reference plus a source-absolute time, and anchors src_us to analyze_clip's src_keyframe_us and the media://{id}/frame/{src_us} space.

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 ("Compare two video frames for perceptual similarity") and immediately names two concrete jobs — dedup shots and match a cutaway — which sets it apart from analyze_clip/describe_clip 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?

Gives clear usage context via the dedup/match-a-cutaway examples and notes the two sides may come from one source or two, but never states when not to use it or names an explicit alternative tool for a different need.

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: it discloses the refusal threshold (under half of caption words aligning), atomicity ('refuses whole, before any write, if a target or its track is locked'), that exactly one recorded edit results, and that a no-op records nothing. This tells the agent the failure modes and side effects that openWorldHint/destructiveHint do not.

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 constraint, and every clause carries a distinct fact (scope, refusals, return shape, listing cap, locking). It is dense to the point of being terse—several backticked clauses are jammed into one paragraph—but almost nothing is redundant.

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

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

With no output schema, the description still defines the return payload including the 20-item listing cap and the meaning of `changed` versus `changes`. Combined with the refusal and atomicity notes, an agent has everything needed to call it correctly and interpret the result.

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

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

Schema coverage is already 100%, but the description still adds real meaning: `script` is clarified as verbatim speech spelling rather than a glossary, `layer_ids` is clarified as caption-only (non-caption refuses), and `composition_id` defaults to root. Only the returned-field list duplicates what a schema would otherwise carry.

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 ('Correct caption TEXT against `script`') and immediately bounds the operation ('Cue segmentation and timing never change'), which separates it from caption-merging or transcript-application siblings. An agent knows exactly what is mutated and what is preserved.

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 essential precondition for use (script must be the full verbatim transcript, not notes or a glossary) and the fallback targets (root composition by default, `layer_ids` to narrow, non-caption ids refused). It does not name sibling alternatives such as merge_captions or apply_transcripts to route between them, which keeps it short of a 5.

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

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

Annotations only declare non-destructive and closed-world; the description adds the crucial lifetime rule (dropped on opening another project or quitting) and that it survives later commits unlike the redo tail. "Unrecorded" signals it is not part of undo history, though the term is left unexplained.

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 action and return value, then lifetime, then interactions, with no filler. A few clauses are terse to the point of ambiguity ("the redo tail", "Unrecorded"), costing a little clarity.

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

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

There is no output schema, and the description compensates by stating the returned object's shape. Lifetime, discoverability via `project://history`, and overlap with begin_agent_session are all covered; only the meaning of "Unrecorded" is left for the agent to infer.

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

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

With a single parameter at 100% schema coverage, the schema already defines `label`. The description adds only the modifier "named", which restates rather than enriches the parameter's meaning.

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

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

"Create a named checkpoint of the current state" gives a specific verb plus resource, and the return shape `{ checkpoint_id, label }` is stated inline. It is clearly distinguishable from restore_checkpoint and begin_agent_session by what it produces.

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

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

It tells the agent when a checkpoint is not needed ("begin_agent_session already makes one") and implies the restore path via the agent panel's Restore button. It never names restore_checkpoint as the explicit alternative, so routing is only implied rather than spelled out.

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

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

Annotations already declare non-read-only, non-destructive, non-idempotent, local-only behavior. The description adds genuinely non-obvious context beyond that: the copy-from-base semantics, the default base of builtin:match, the quirk that built-in base bitrate is copied as a fixed standard-frame-rate value, and the explicit scope limit that default/project settings are untouched. It omits what happens on a duplicate name, which the schema handles only indirectly.

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 core action and default, then the bitrate caveat and the scope limit. No sentence is redundant and the ordering matches the order an agent needs the information.

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

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

For a create tool with a deep nested settings object but no output schema, the description covers origin of values, defaults, and side-effect scope well. The one gap is interaction with existing presets and the fact that the uniqueness constraint on name implies a possible failure mode that is never mentioned.

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?

With 100% schema coverage the baseline is 3, but the description adds real meaning the schema does not carry: base_preset_id defaults to builtin:match, settings are layered over a copied base, and inspecting the source preset requires get_export_options rather than assuming parity. That directly improves how an agent populates the two optional parameters.

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

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

The first sentence gives a specific verb and resource ("Create a reusable personal export preset") and the qualifier "personal" distinguishes it from the built-in presets handled by list_export_presets. It stops short of explicitly naming update_export_preset as the tool for modifying existing presets, leaving that inference to the 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?

It provides a clear exclusion ("Does not change the default or project settings") and routes the agent to get_export_options with preset_id when project-adapted values are needed. What's missing is explicit guidance on create-vs-update, i.e. pointing at update_export_preset when a preset already exists.

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 openWorldHint=false and destructiveHint=false, so the description carries most of the load and does add real context: three explicit refusal conditions and the fact that members keep their own timing and effects. It also discloses the return payload ('the Group clip and composition') despite having no output schema. What is missing is whether the operation is undoable or what state the source layers are left in after pre-composition.

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 scope, then refusals, then return value. Every clause carries distinct information: placement/links preservation, failure modes, and member timing behavior. Nothing is repeated from the schema or annotations.

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

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

For a two-parameter mutation with no output schema, the description covers purpose, failure conditions, and return shape, which is most of what an agent needs. The remaining gap is post-state: whether the group replaces the source layers in the timeline and whether the call can be reverted.

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 both parameters are already documented, including the UI-derivation behavior when label is omitted. The description adds only a loose restatement ('selected clips', 'preserving their placement and links') rather than new meaning for layer_ids ordering or composition-scope constraints. Baseline 3 is appropriate.

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

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

States a specific verb and resource: 'Pre-compose selected clips into a new Group, preserving their placement and links.' An agent can distinguish it from the inverse sibling ungroup_layer without opening the schema. It stops short of naming adjacent siblings such as add_group_members or create_link, so it is clear but not maximally differentiated.

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 through preconditions rather than stated routing: 'Refuses partial links, locked members and incompatible selections' tells the agent when the call will fail, but never says when to choose this over add_group_members or move_layers_to_composition. The reader must infer the workflow position of grouping from 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?

Beyond the annotations, the description discloses the failure path, the side effects of reassign (members are pulled from prior links and any link dropping below 2 members is auto-dissolved), and the return payload ('link_id', 'members'). That side-effect disclosure is especially valuable given destructiveHint=false, since it tells the agent that an opt-in parameter can still dissolve links.

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 with no filler: creation rule first, the failure/reassign behavior second, return shape last. Every clause carries information an agent needs before invoking.

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 two-parameter mutation with no output schema, the description covers prerequisites, failure handling, cascading side effects, and the shape of the result. Nothing material is left for the agent to guess.

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

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

Schema coverage is 100%, so both parameters are already documented, but the description still adds meaning: members must be 'distinct' and belong to 'one composition', and it frames reassign as the remedy for a failing call rather than just a boolean. That is a modest improvement over the schema alone.

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

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

The description gives a specific verb and resource ('Create a new link') plus a concrete precondition ('from >=2 distinct layer ids'), so the operation is unambiguous. It stops short of distinguishing itself from nearby siblings like create_group or update_link, which would have earned a 5.

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

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

It clearly states the condition under which the call fails (a layer already belongs to another link) and the exact switch that unblocks it ('reassign=true'). It does not name alternative tools such as create_group, so guidance is contextual rather than comparative.

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 destructiveHint=true annotation is meaningfully qualified: the description states the previously open project is saved, and that the frame rate locks once a layer is placed — traits an agent could not infer from annotations. It also names the return shape `{ name, dir, replaced }`, though what `replaced` means (existing target folder/file overwritten?) is left unexplained, which is the main gap for a destructive tool.

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

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

Two dense sentences, front-loaded with what is created and conditioned by the user-intent gate, with defaults and return value packed efficiently. The telegraphic style and the 'as New Project does' UI reference cost a little immediate clarity.

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

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

For a 5-parameter, nested-schema creation tool with no output schema, the definition covers creation target, defaults, destructive side effect, fps lock, and the returned fields. Missing only failure behavior, e.g. what happens if the folder or project name already 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 is 3; the description earns above that by supplying defaults not in the schema — parent folder taken from the session view's `default_parent_folder`, and 1920x1080 at 60 fps — plus the constraint that fps is fixed after the first layer is placed.

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 plus the exact path semantics (`<parent_folder>/<name>`) and the UI analogue ('as New Project does'), which differentiates it cleanly from the sibling open_project.

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?

'only when the user asked' gives an explicit gating condition for invoking the tool, which is stronger than most definitions. It stops short of naming open_project/read_project as the alternatives when no creation is wanted, so routing is partly implied.

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

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

Goes well past the annotations: it discloses scoping (agent panel, this project opening only), lifecycle (user resolves/dismisses/clears; tacks go outdated when the range plays different content), transactional validation (one refusal creates none), the 1000 limit with the `TackLimit` error, and that it is unrecorded and works while history is locked. That is exactly the mutation-behavior context destructiveHint=false alone cannot 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 purpose and dense with information — nearly every clause carries a rule or a constraint, and nothing reads as filler. The trade-off is telegraphic syntax such as "`TackLimit` past 1000" and em-dash chaining that costs a re-read in places.

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

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

With no output schema, the description still names the return shape (`{ tacks, hints? }`) and the follow-up signal (`affected_tacks`), and covers limits, persistence, validation, and lifecycle. Minor gaps remain, e.g. what a returned tack object contains and how `hints` is populated, but nothing essential to calling it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, and the description adds real guidance beyond it: "Describe content, never times: the panel shows the live place" tells the agent how to write `label`, and "One place, one tack" constrains the array contents. It does not add anything about `kind` or `composition_id`, which remain schema-only.

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 action and resource — pointing the user at time ranges to review — and defines what a tack functionally is (a comment anchored to a range that travels with the content). It explicitly separates itself from markers ("Not a marker"), so an agent can distinguish it from add_marker without opening either 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 an explicit routing rule: "use it unless the user asked for markers," plus timing guidance ("Create after your edits") and a boundary that the user, not the agent, resolves or clears tacks. It does not name the close siblings update_tack or delete_tacks as follow-up paths, which leaves a small inference gap.

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

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

Annotations already declare destructiveHint=true and openWorldHint=false, so the risk profile is known; the description goes further by documenting the exact refusal conditions and error identifiers (CompositionInUse with ref_count, RootComposition), which the agent can handle programmatically. 'Recorded' hints the operation is journaled, but it does not say whether an undo or checkpoint restore is available, leaving that ambiguity.

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

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

Three sentences, front-loaded with the core constraint, then the refusal contract, then the audit note. No filler, and the error tokens are inlined rather than buried at the end.

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

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

For a one-parameter destructive tool with no output schema, the definition covers the precondition, the failure modes, and how to check eligibility beforehand. Nothing an agent needs in order to avoid a failed or wrong deletion is missing.

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

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

There is a single parameter with 100% schema description coverage, so the schema already carries the burden. The description adds no format or sourcing detail for composition_id beyond implying it must be an orphaned, non-root composition; per the baseline rule for full schema coverage this is a 3.

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

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

States a specific verb (delete) and resource (composition) and immediately narrows the scope: only an orphan left behind when its Group layers were deleted. That scoping distinguishes it from delete_layers and the other deletion siblings without the agent needing to open any schema.

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

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

It spells out the precondition (nothing references it) and both failure cases — CompositionInUse while a Group layer points at it, and RootComposition for the root — and points at project://compositions to inspect the reference count first. It stops short of naming the sibling to use for the other cases (e.g. delete_layers for the group layers themselves), so it is context-rich but not fully comparative.

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

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

Annotations already declare destructiveHint=true and openWorldHint=false, so the agent knows this is a destructive local mutation. The description adds nothing beyond that — it does not say whether the removal is undoable, whether it cascades to keyframes or links, or whether confirmation/permissions are needed, which is the main thing left for a destructive tool to disclose.

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

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

A single front-loaded sentence with zero filler. It is efficient, though on the terse side given the destructive nature of the operation.

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 is simple (2 required params, no output schema), but it is a destructive mutation and the description leaves reversibility, validation behavior, and error conditions unspecified. An agent can call it, but cannot predict the consequences of doing so.

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% (both effect_id and layer_id are documented in the schema), so the baseline of 3 applies. "By id" only restates that the parameters identify the effect and layer; no additional format or constraint detail is added.

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?

"Remove an effect from a layer by id" names a specific verb (remove) and resource (effect scoped to a layer), which is unambiguous. It does not differentiate from siblings such as add_effect, update_effect, or delete_transition, but the core action is 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?

No when-to-use guidance is given. There is no mention of when to prefer update_effect (modify parameters) over delete_effect, nor any prerequisite such as needing the effect to exist or requiring the layer to be otherwise unlocked.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the description's job is to say what damage occurs — and it does: deleting the default restores builtin:match, and existing projects are left unchanged. That consequence disclosure is genuinely useful context beyond the annotations. It stops short of stating irreversibility or recovery options for a non-default preset.

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, then consequences, then the read-only guard. No filler and nothing restated from the tool name.

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

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

For a single-parameter destructive tool with no output schema, the description covers the scope, the fallback behavior, and the built-in restriction — enough to call it correctly. The remaining gap is what happens to a non-default preset's settings (recoverable or not).

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

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

Schema coverage is 100% and the preset_id description already points at list_export_presets and explains the builtin: prefix. The description reinforces the built-in constraint but adds no format or source detail beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb+resource ("Delete a personal export preset") and implicitly scopes it against the create/update/list_export_presets siblings by qualifying the preset as personal. No sibling is named explicitly, so it lands at 4 rather than 5, but an agent can still tell what this does and what it does not touch.

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?

"Built-ins are read-only" is an explicit when-not-to-use condition, which is exactly the kind of exclusion most delete tools omit. It does not name an alternative for modifying rather than removing a preset (update_export_preset), so it misses the top tier.

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

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

Annotations already declare destructiveHint=true and openWorldHint=false, so the description gets a lower bar, and it clears that bar by disclosing a non-obvious side effect: deleting the last key collapses the track to Static holding that key's value. It also states the shape of the response ('the track's mode and keyframe_ids, or the static value'), which annotations cannot convey. It does not mention whether the deletion is recoverable or undoable via the 'undo' sibling, so it stops short of 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 tight sentences: the action comes first, the side effect second, and the return value last. No restated name or filler, and every sentence carries distinct information.

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

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

For a three-required-parameter destructive mutation with no output schema, the description covers the action, the resulting state transition, and the return shape, which is enough to call it correctly. It omits error behavior (e.g., unknown keyframe id) and recoverability, which keeps it one step from complete.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds cross-tool meaning by tying keyframe_id to the keyframe_ids field returned by get_param_track. That sourcing hint is genuine information beyond the schema; layer_id and param_key semantics are left 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?

The description opens with a specific verb+resource ('Remove a keyframe by id from a layer param'), and it points at the sibling that supplies the id ('keyframe_ids' in get_param_track). It never explicitly contrasts itself with set_keyframe/update_keyframe, so an agent must infer the difference from the verb alone, which holds it below a 5.

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

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

Usage is implied rather than stated: the reference to get_param_track tells the agent where to obtain keyframe ids before calling, which is genuinely useful context. But there is no explicit when-to-use vs. when-not guidance, and no routing away from set_keyframe/update_keyframe for modification cases.

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

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

Beyond the destructiveHint annotation, the description discloses atomicity (whole-batch refusal before any write), ripple mechanics, hole merging, track pruning, and named ripple refusal errors. This is unusually rich behavioral context for a destructive tool.

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

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

The description is dense but front-loaded with the core action and the ripple default. It is long for two parameters, yet most sentences carry distinct behavioral information; a few clauses could be simplified without losing meaning.

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

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

Given the destructive batch operation, no output schema, and the need to understand ripple side effects and refusals, the description is complete enough for an agent to call the tool correctly or anticipate failure conditions.

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?

Although the schema already documents both parameters at 100% coverage, the description adds substantial meaning: it explains what 'ripple' does to every track, anchored markers, the playhead, and free markers, and it explains why link partners may need to be added to layer_ids.

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: 'Delete a set of layers as one recorded edit.' It also distinguishes the operation's scope (one composition) and batch nature, making it clearly different from sibling tools like delete_track or delete_transition.

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

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

The description provides clear contextual guidance: link partners must be included explicitly, ripple defaults to false, and locked layers/tracks block the whole batch. It lacks explicit comparison to alternative tools, but the operational conditions are sufficiently clear for correct use.

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

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

Annotations already declare destructiveHint=true, so the safety profile is given. The description adds valuable scope information: the member layers survive the operation. It does not mention reversibility, auth, or response format, but the added context 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?

Two short sentences, front-loaded with the action and immediately followed by the key non-effect. Every sentence earns its place.

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

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

For a simple one-parameter destructive tool with no output schema, the definition is nearly complete: annotations cover destructiveness and the description clarifies blast radius. Only minor details like undoability are absent.

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

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

Schema coverage is 100% for the single link_id parameter, and the schema itself describes it as 'Link id.' The description does not add syntax or format details beyond that, 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?

The description gives a specific verb ('Dissolve (delete)') and resource ('a link'), and the clarification that member layers are not deleted distinguishes it from sibling tools like delete_layers. An agent can immediately tell what this tool does.

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

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

Usage is implied by the contrasting statement about layers, but there is no explicit when-to-use/when-not guidance or named alternative. The agent must infer that this is for removing links while preserving layers.

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

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

Annotations already declare destructiveHint=true and openWorldHint=false, so the safety profile is covered structurally and the description is not required to restate it. However, the description adds no behavioral context beyond the annotations: it does not say whether deletion is reversible, whether attached keyframes or anchors are also removed, or what happens if marker_id is invalid. For a destructive operation this leaves meaningful gaps.

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

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

The single sentence is front-loaded and free of waste, but its brevity reflects under-specification rather than disciplined editing. There is no structure to speak of because there is only one short clause.

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

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

For a destructive single-target tool with no output schema, the description should at minimum cover reversibility and side effects, and it covers neither. The annotations and 100% schema coverage carry the structural burden, but an agent still cannot tell what it loses by calling this.

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% for the single marker_id parameter, so the schema already carries parameter meaning and the baseline of 3 applies. The description contributes only the indefinite "a marker", adding no format, id-namespace, or lookup guidance 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 verb plus resource ("Remove a marker"), which is marginally more than the name delete_marker already conveys and does not tell the agent anything about scope or which marker domain (timeline markers vs. other markers) is affected. It is clear enough to avoid confusion with update_marker or add_marker, but it borders on restating the name rather than adding distinguishing detail.

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 when-to-use guidance at all: nothing says when deleting is preferable to update_marker or set_marker_anchor, and no prerequisites or confirmation conditions are given. The only implied usage comes from the verb itself, which the sibling name already exposes.

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 destructiveHint=true: it discloses atomic commit semantics, that links dissolve below two members, that emptied transient lanes are pruned, that a locked lane raises TrackLocked, and how undo recording differs between the no-op and forced paths. These are exactly the failure and side-effect details an agent must anticipate; only the return payload is unaddressed.

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, then escalating detail on refusal, cascade, and recording. Dense but nearly every clause adds a distinct behavioral fact; the final 'Unrecorded when nothing used it; the forced cascade records' is terse to the point of being cryptic.

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 two-parameter destructive tool with no output schema, the description covers the refusal path, the destructive path, error conditions, and undo recording — enough to call it safely. What is missing is any indication of what the call returns on success or on the cascade.

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

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

Schema coverage is 100%, so the baseline is 3, and the description earns above it by spelling out what force actually triggers (cascade plus the same rules as delete_layers) rather than just restating 'default false'. media_id gets no extra meaning, but it needs none.

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 ('Remove a media item'), which is unambiguous. It also implicitly separates itself from delete_layers by explaining that removing media may cascade into layer deletion, though it never states the reverse case (deleting layers without touching media).

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

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

Clearly states the default refusal condition and the alternative (force=true), plus the consequence of taking that alternative. It stops short of an explicit 'use delete_layers instead when you only want layers gone', but the cascade paragraph makes the boundary between the two siblings legible.

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

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

Beyond the `destructiveHint`, the description provides critical behavioral context, such as stating that referencing layers become 'missing-content placeholders' and that source directories are never deleted, defining the exact mutation consequences.

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 highly concise and perfectly structured, layering the core purpose first, followed by necessary behavioral constraints and side effects without any wasted language.

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 its destructive nature and specific resource types, the description is extremely complete. It covers the object being deleted, what stays, what is refused, and the resulting placeholder status of dependent layers.

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

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

The schema description coverage is 100%, providing maximum baseline information. The description does not add semantic value beyond confirming that the ID targets the Motif or draft being deleted.

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 action (Delete) and the resource type (user Motif or draft). It distinguishes this tool from creation or listing tools available in the sibling 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?

It provides important contextual guidelines regarding safety and scope by stating which linked resources (directories) are safe from deletion and which types (built-ins) are refused.

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

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

Annotations already flag `destructiveHint: true` and `openWorldHint: false`, and the description adds real value beyond them: all-or-nothing semantics ("every one must exist, or none is removed"), the return shape `{ deleted_tack_ids }`, and the terse flag "Unrecorded." The last item is important but cryptic — it presumably means the deletion is not captured in undo/checkpoint history, but the description never says so plainly.

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?

Extremely compact and front-loaded: verb, modes, constraint, return, caveat. No filler sentences. The telegraphic fragments ("Exactly one of the two.", "Unrecorded.") trade a little readability for density, and the final fragment borders on ambiguous note-taking.

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 2-parameter destructive tool with no output schema, the description covers everything needed to call it correctly: which argument selects which mode, that exactly one is used, atomicity on failure, and what comes back. Nothing essential is missing, though expanding "Unrecorded" would remove the only interpretive burden.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns above that by adding semantics the schema does not express — mutual exclusivity of `tack_ids` and `session_id`, and that a session deletion expands to every tack created in that session. The `tack_ids` and `session_id` schema descriptions corroborate but do not duplicate this.

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 ("Remove tacks") and immediately distinguishes the two supported scopes: an explicit `tack_ids` list versus all tacks from a work session. An agent can tell exactly what this does and how it differs from `create_tacks` or `update_tack` 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?

"Exactly one of the two" is an explicit, unambiguous selection rule between the two deletion modes, which is the key usage decision here. It stops short of naming alternatives (e.g., using `update_tack` for less destructive edits) or prerequisites, so it is clear context but not a full when-to-use/when-not map.

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 destructiveHint=true and openWorldHint=false; the description supplies the specifics those hints cannot: the exact refusal error, the cascade behavior under force, that layer links are cleaned up, and that the whole cascade lands in a single undo entry. It also discloses the subtle side effect that a Group layer's composition survives with ref_count 0 rather than being deleted.

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 action, then the refusal condition, then the cascade and edge case. It is dense and every clause carries information, though the em-dash aside about project://compositions is slightly awkward to parse.

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

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

For a destructive two-parameter tool with no output schema, it covers the failure modes, the cascade semantics, the undo grouping, and the follow-up tool for leftover compositions. An agent has everything needed to call it safely and handle the result.

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

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

Schema coverage is 100%, so both parameters are already documented, and the description largely restates force's semantics (cascade delete of layers) rather than adding syntax or format detail. It does add the consequence of force beyond the schema's wording, but the baseline of 3 for a fully-covered two-parameter schema 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?

"Remove a track" is a specific verb+resource, and the description immediately scopes it against siblings: delete_composition handles orphaned compositions, delete_layers is implied for individual layers. It also names which track types are deletable, so an agent can tell this apart from layer- or composition-level deletion tools without opening the schema.

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

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

It states the precondition for force (non-empty track raises TrackNotEmpty), the protected track types (A roll / B roll raise TrackNotRemovable), and routes orphaned compositions to delete_composition. What it does not say is when to prefer deleting individual layers via delete_layers instead of force-deleting the whole track, which is the one remaining routing decision left to inference.

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

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

Annotations only declare destructiveHint=true; the description goes far beyond by explaining exactly what mutates (outgoing layer end shrinks by `extended_us`, incoming layer shifts right by `duration_us − extended_us`, link siblings follow), that only borrowed tail is discarded and never real content, that the operation is "Recorded" (undoable), and the two named error conditions.

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 action and its restoral semantics are front-loaded and every clause carries information, but the middle sentence is dense jargon with several backticked field names used without definition, which slows comprehension for an agent that has never seen `extended_us`.

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

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

For a one-parameter destructive mutation with no output schema, this covers the important ground: mutation mechanics, error names, remediation, and recording/undo. It stops short of stating permission or checkpoint prerequisites and does not say what is returned on success.

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% for the single `transition_id` parameter, so the baseline is 3. The description adds only indirect meaning — `TransitionNotFound` for an unknown id implies the id must reference an existing transition — while `extended_us`/`duration_us` are recorded transition properties, not inputs, and are left unexplained.

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

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

The description names a specific verb and resource ("Remove a transition") and immediately clarifies the resulting state ("restore the hard cut"), so an agent can distinguish it from add_transition/update_transition 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?

It gives concrete when-it-fails guidance — on `TransitionRestoreCollision` the agent must "move or delete the blocker first" because "the system never makes room" — but it never names the sibling tools (e.g. move_effect, delete_effect) that would perform that remediation, leaving the routing one inference away.

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 `readOnlyHint`/`openWorldHint` annotations: caching per source range means a retry after a client timeout resumes, `refresh` replaces the earlier run, sampling is capped at ≤3600 frames per call, local engines run on this machine while `byo_endpoint` uploads frames, and `backend` never silently substitutes. These are exactly the operational facts an agent needs before calling.

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

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

Front-loaded with the verb and target, then window, return shape, caching, and engine policy in descending order of importance; nearly every clause carries information. It is a dense wall of backticked tokens in one paragraph, which costs it a point on readability rather than on 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?

With 9 optional parameters, no output schema, and a non-trivial engine/caching model, the description supplies the return shape (`backend, model, summary?, media_id, mapping?, segments[...]`), the source-microsecond convention, cache/resume behavior, and consent requirements. Nothing essential to a correct call is missing.

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

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

Schema coverage is already 100%, so the baseline is 3; the description still adds cross-cutting meaning the schema cannot express — which parameters are cache keys, that `focus` steers only `tags`, that `language` defaults to the UI language, and the backend resolution order (selected engine, then availability, local first).

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: 'Describe a video's visual content as timestamped segments with a video-understanding model'. It also names the concrete alternatives (media_id pooled item vs. layer_id VideoClip) and ties itself to the sibling `analyze_clip` by sharing its `mapping` semantics, so an agent can place it precisely.

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

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

Gives clear selection rules: pooled item by `media_id` (placed or not), VideoClip by `layer_id`, window narrowed by `src_start_us`/`src_end_us`, `refresh` to re-describe, and a consent condition for `byo_endpoint`. It lacks an explicit when-not (e.g. use `analyze_clip` for shot structure vs. this for visual prose), so 4 rather than 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?

Beyond the readOnlyHint/openWorldHint annotations, the description discloses the internal detection semantics (peak below threshold for min_pause_us; a sub-80 ms louder run like a click does not end a pause), the layer_id resolution rule and refusal when a linked Audio member plays no sound, and the DerivativeNotReady refusal with state/retry_after_s/failed reason. This is unusually rich behavioral context that annotations alone would never supply.

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 purpose and the read/write split before the technical detail. It is dense and somewhat crammed with parentheticals (dBFS defaults, click exception, refusal states), but nearly every clause earns its place and the ordering is logical.

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

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

There is no output schema, and the description fully specifies the return shape (pauses[{t_start_us,t_end_us}], noise_floor_db, peaks_source with 'raw'/'fx'), timeline units, sort order, and the DerivativeNotReady failure path. For a read-only detection tool with three params, nothing an agent needs to call and interpret it is missing.

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

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

Schema coverage is 100%, so the schema already documents all three parameters; the description nonetheless adds meaning by explaining how threshold_db and min_pause_us interact to define a pause, and by noting the 6 dB-above-noise-floor heuristic. It adds real value beyond the schema, though it largely restates the defaults already present in the schema.

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

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

States a specific verb and resource ('Find the pauses in the audio a clip plays... from the pre-computed waveform') and immediately disambiguates from the write-side siblings (remove_pauses, create_tacks). An agent can tell exactly what this does versus the mutation tools without opening any schema.

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

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

Explicitly frames the tool as read-only and names the alternatives for the write path: 'the writes are remove_pauses (cut them, or a reviewed subset via its pauses) and create_tacks (point the user at them).' It also states the prerequisite (waveform must be ready) and the refusal/retry behavior, so when-to-use and when-it-fails are both covered.

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 say openWorldHint=false and destructiveHint=false; the description goes well beyond by disclosing the ownership rule, the audit gate, and exactly what is retained versus released. The failure mode is given concretely (`ended: false, held: "audit"`). Minor gap: 'Unrecorded' is asserted without clarifying which history/undo log it refers to.

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 primary effect, then preconditions, failure semantics, and return shape in a logical order with no filler sentences. It is densely packed with shorthand ('Unrecorded.', `tacks_to_review`) that assumes domain familiarity and slightly compresses readability.

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

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

There is no output schema, but the description hand-specifies the response (`{ ended, audit }`, null `ended`, optional `tacks_to_review`). Combined with the ownership and audit-gate behavior, an agent has everything needed to call and interpret this correctly.

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

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

The tool takes zero parameters, so the schema baseline is 4 and there is nothing parameter-specific for the description to add. It does correctly avoid inventing inputs, though the caller has no handle to force or skip the audit here.

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

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

States a specific verb and resource (end the agent session) plus the precise effect: releases the history lock while the view, activity, running tasks and connection persist. It is immediately distinguishable from the sibling begin_agent_session, which is named as the takeover alternative.

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

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

Explicitly says who may call it (only the owning connection) and names the alternative for the stale case (`begin_agent_session { force: true }`). It also states the precondition (a current `check_composition`) and what to do when the call is refused (settle findings and end again).

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 annotations already establish readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds useful behavior beyond that: it discloses the return shape `{ format, cues, body }` plus the snapped `range`, states that the range is snapped to the frame grid like start_export, and notes 'Records nothing' and that no file is written. It does not cover error behavior or lane-ordering edge cases, so it sits at a solid but not exceptional level given annotation coverage.

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 action, then the range semantics, return shape, and the 'write body yourself' caveat. It is dense and telegraphic (heavy em-dash use), but essentially every clause carries information; minor tightening is possible but nothing is filler.

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

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

With no output schema, the description compensates by specifying the returned object keys and the snapped range, and it covers all four parameters at 100% schema coverage. For a read-only export tool with nested range parameters, an agent has everything needed to call it and handle the result.

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

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

Schema coverage is 100%, so the schema baseline is 3; the description nonetheless adds real meaning by explaining that `range` clips cues and shifts them to 0 in step with a range export, and that `track_id` restricts to one lane while omission means all lanes. That is more than restating field names.

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

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

The description opens with a specific verb and resource ('The captions of a composition as a subtitle document'), states the supported formats, and defines scope ('every caption lane (or one track_id) in time order'). That level of specificity clearly separates it from siblings such as merge_captions, apply_subtitles, and correct_caption_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?

It gives clear context for when to use it: when you want cue text as it stands, aligned with a range export ('range (start_export's) ... in step with a range export'), and it tells the agent to write `body` to a file itself. It stops short of explicitly naming alternatives or stating exclusion conditions (for example, that this does not merge, apply, or correct captions).

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

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

Adds real behavior beyond the annotations: no-overwrite semantics ('an existing file is refused, never overwritten') and validation failure on invalid linked content. This is meaningful for a tool flagged destructiveHint=true, since it tells the agent the blast radius is limited to a new file. It stops short of covering revision-mismatch behavior or whether the write is synchronous.

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 the path contract, with every clause carrying a constraint an agent needs. No filler or restatement of the tool name.

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 write path contract is well covered, and with no output schema there is no obligation to describe return values. However, for a three-parameter export with a revision guard, the description leaves the caller without any model of what success looks like or how expected_revision participates in the write.

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

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

Schema coverage is 100%, so baseline is 3. The description adds genuine constraint on 'path' (must be absolute, on the app machine, inside an existing folder, and must not already exist) that the schema text does not, but says nothing about expected_revision, which is the parameter most likely to cause a failed call.

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 artifact: writes a complete ZIP snapshot to a given path. It is clear what the tool produces, but never says the word 'motif' and never contrasts itself with nearby export siblings (start_export, render_frames, export_captions), so the agent must infer the boundary from the name alone.

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

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

Gives preconditions rather than use guidance: path must be absolute on the app machine, the folder must already exist, and an existing file causes a refusal. There is no statement of when this is the right export tool versus the other export-related siblings, so usage is only implied by the constraints.

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 readOnlyHint and openWorldHint; the description adds substantially more: nothing is uploaded, no API key is needed, output is normalized to mono 16 kHz 16-bit WAV starting at zero, ~2.6 MB base64 per 60 s, and it refuses layers that play no sound or windows outside the layer. That is exactly the behavioral context the annotations cannot carry, and it is consistent with readOnlyHint=true.

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 before the mechanics, and nearly every clause carries information (format, size, limits, refusal cases, offset mapping). It is a single dense block with embedded field lists and formulas, which is efficient but slightly harder to scan than a broken-out structure would be.

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

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

There is no output schema, yet the description fully enumerates the returned metadata keys and the MCP audio block format, so an agent knows exactly what comes back. Combined with limits, defaults, and failure modes, nothing needed to call this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: it clarifies the 60 s cap is on SOURCE audio (timeline windows ≤ 60 s / rate), whereas the schema only mentions a 60 s window, and it supplies the offset mapping formula 't_start_us + w / rate'. That rate-dependent nuance is not derivable from the schema alone.

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

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

States a specific verb and resource — 'Extract the ORIGINAL source audio that plays on a VideoClip or Audio layer' — and pins down the exact point in the signal chain ('before gain, mute, effects or mixing'). The parenthetical 'a VideoClip through its linked Audio member' disambiguates the linked-audio case, which no sibling tool covers.

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

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

Gives a clear usage context ('for an agent running its own speech model; no engine or API key is involved') and a concrete follow-up path ('then apply_transcripts'), plus chunking guidance ('at most 60 s ... so a long clip is several calls') and refusal conditions. It stops short of explicitly naming the alternative tool to use when the agent does NOT have its own speech model (e.g. transcribe_clip), so the routing 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 readOnlyHint=true and openWorldHint=false, so the non-mutating nature is known. The description still earns credit for adding the precedence chain (preset preview → project settings → global default) and for explicitly stating the preview does not change project settings, which is the behavior an agent would otherwise worry about. It does not clarify what 'composition limits' actually contain or whether results can be stale.

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 followed immediately by the branching behavior. No filler, no restatement of the tool name.

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

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

For a zero-required-parameter read tool with a fully documented schema and safety annotations, this covers what an agent needs to call it correctly. The only gap is the absence of an output schema combined with no description of the returned shape beyond the phrase 'effective export settings and composition limits'.

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 preset_id format (including the 'builtin:' prefix and the reference to list_export_presets) is already fully documented. The description adds the meaningful semantic that supplying it is a non-persistent preview rather than a mode switch, but that is the only increment over structured data. Baseline 3 fits.

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: reads 'effective export settings and composition limits'. This is clearly distinct from the sibling create/update/delete_export_preset tools and from list_export_presets, though it never names the closest alternative explicitly. The purpose is unambiguous 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 real situational guidance: pass preset_id to preview a preset without touching project settings, omit it to read saved project settings falling back to the global default. That answers the main 'when do I pass the parameter' question. It stops short of naming an alternative tool or stating exclusions (e.g. when to use list_export_presets 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety profile is covered; the description adds real behavior beyond that: blocking semantics of wait_s, the meaning of the queued state and that job.queued names the resource holders, and the persistence caveat that records survive MCP reconnects only until the app exits. It stops short of enumerating the possible state values or the full return structure, so it is strong but not exhaustive.

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

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

Four short sentences, each carrying a distinct fact, with the return shape and default resolution front-loaded. A few phrases are compressed to the edge of cryptic ('as { job }', 'job is null only when none has run'), which costs a little readability but no sentence is wasted.

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

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

There is no output schema, so the description carries the return-value burden and does address the key parts an agent needs: the job object, its null case, and job.queued. What is missing is the set of possible export states and which ones are terminal, which matters for deciding whether to call again with wait_s.

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

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

Schema coverage is 100%, so the baseline is 3, and the description earns above that by explaining the two behaviors the schema cannot: what omitting job_id resolves to (active job, else most recent, else null) and that wait_s blocks until a state change rather than simply sleeping for the duration. The 0-60 cap and id format are left to the schema, which is appropriate.

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

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

States a specific verb and resource ('Read an export job') and immediately defines the returned shape as { job }, with the default-resolution rule (active job, else most recent, null when none has run). No sibling tool in the list reads export job state, so the boundary against start_export/cancel_export/retry_export/get_export_options is unambiguous without naming 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 guidance: omit job_id to get the active job or the most recent one, and use wait_s to block for a state change. It does not state when *not* to use it (e.g., poll repeatedly instead of using wait_s, or use cancel_export/retry_export once a state warrants action), so no explicit exclusion or alternative routing is provided.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, and the description goes well beyond that: it discloses that unset effect params read as their catalog default, that position params are mode-specific, and that tangents are only meaningful for Spline segments. These are non-obvious semantics an agent could not infer from the structured fields.

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

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

The core action is front-loaded and every clause carries real information, but the middle is a dense run of parallel-field explanations (keyframe_ids, local_t_us, preset_ids, in/out, segment) packed into one paragraph. Splitting the return-shape discussion from the mode-specific notes would make it 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?

There is no output schema, so the description takes on the burden of describing the return shape and does so thoroughly, including the parallel key arrays and tangent/segment objects. For a two-parameter read tool, nothing an agent needs to interpret the response is missing.

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

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

Schema coverage is 100% and the schema already enumerates `param_key` values, so the baseline is 3. The description earns above that by adding meaning the schema cannot express: position params differ by mode (x/y in XY, path_progress as a fraction in Path), which clarifies how to interpret the returned value for a given key.

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

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

The opening sentence states a specific verb and resource: 'Read a layer param's animation.' It immediately distinguishes itself from the write-side sibling by noting that `track` is exactly `set_param_track`'s shape, so an agent knows this is the read counterpart without inspecting either schema.

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

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

The description makes the round-trip workflow explicit ('to edit and send back as is') and names the downstream tools that consume the returned `keyframe_ids` (update_keyframe / delete_keyframe), which tells the agent why it would call this. It lacks an explicit 'do not use this to write' exclusion, but the read/edit pairing is unambiguous.

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

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

The description goes well beyond the annotations by disclosing pre-flight validation and atomic refusal ('nothing imported'), hashing and probing, copy location, return shape, the meaning of existing/relinked/copying flags, and pooling behavior. This matches the idempotent and non-destructive hints while adding substantial operational detail.

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

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

The purpose is front-loaded, but the body is one dense run-on sentence packed with semicolons and parentheticals, making it harder to scan. The trailing fragment 'Unrecorded.' is cryptic and would benefit from explicit phrasing about undo behavior.

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

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

There is no output schema, but the description supplies the return envelope `{ media: [record] }` with field-level explanations for path, path_rel, derivatives, existing, relinked, and same_content_as. It also covers failure modes, making the definition complete enough to call correctly.

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

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

The single parameter is already fully documented in the schema (absolute or project-relative paths, 1-50 files). The description adds behavioral context about paths being checked first but does not extend parameter semantics beyond what the schema covers, so the baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Import media files', then immediately states the full pipeline (check, hash, probe, copy into Media/). This clearly distinguishes import_media from siblings like delete_media, apply_subtitles, and extract_clip_audio.

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

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

It gives clear workflow context: subtitle extensions pool for apply_subtitles and .svg rasterises to PNG, which tells the agent how this tool relates to downstream operations. It does not explicitly state when not to use it, but the context is strong for a tool with no direct import alternative.

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

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

Annotations only declare openWorldHint=false and destructiveHint=false; the description supplies the real behavior: nothing is committed until user approval, the call returns {state: awaiting_approval, proposal_id, target}, a later proposal from the same draft supersedes the earlier one, and a taken name fails with MotifIdTaken. That is meaningful context an agent cannot infer from the annotations.

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

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

The commit-safety caveat and the return shape are front-loaded, and nearly every sentence carries a distinct fact (return contract, no-poll instruction, supersession, name collision, replacement path). The telegraphic phrasing ('A new id is the name's') is slightly compressed at the cost of a quick first read.

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

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

With no output schema, the description takes on the return contract and does so well, including the state field, proposal_id, both target shapes, and the error case. What is left implicit is broad (e.g. what invalidates a proposal or how approval surfaces), but nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description still adds real meaning by tying target_id and expected_version together as the replacement path and explaining that a new id comes from the name while a collision is refused. It does not restate the expected_revision format beyond the schema's own wording.

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

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

Opens with a precise verb+resource+manner: 'Propose publishing a draft's expected_revision', and immediately distinguishes the actual effect ('the library is untouched until the user approves it'). This separates it cleanly from open_motif_draft, preview_motif and list_motifs.

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

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

Explicit about the approval flow and the correct follow-up ('tell the user to review it, do not poll', 'list_motifs shows the outcome'), and gives the exact rule for the replace case ('To replace an installed Motif pass target_id and expected_version'). It names the sibling that reports the outcome, which is the alternative an agent would otherwise guess at.

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

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

Beyond the destructiveHint annotation, the description discloses key behavior: it records nothing, a later edit drops the history ahead, it is refused if the op is no longer on the stack, and another session's history lock blocks it. It also describes the return value as the op the cursor now sits on.

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

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

The description is compact and front-loaded with the core action. Every clause adds relevant behavior or context, with no filler.

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

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

For a one-parameter history-navigation tool with no output schema, the description covers purpose, failure conditions, locking, side effects, and the response value. No essential invocation detail appears to be missing.

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

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

Schema description coverage is 100%, so the single parameter is already documented. The description adds some nuance by clarifying that the cursor moves to the state right after the op, but it does not add substantial new parameter-level meaning beyond the schema.

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

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

The description states a specific verb and resource: moving the history cursor to the state right after a given op. It distinguishes this from undo and checkpoint restoration by explaining that it reaches a state that is neither one undo away nor a checkpoint.

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 when to use this tool: to land after an op that is still held by the history stack. It also states failure conditions, names undo and checkpoints as related alternatives, and notes that a session history lock can block the 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?

Beyond the annotations (idempotentHint=true, destructiveHint=false, openWorldHint=false) it discloses real side effects: a GUI window is opened on the user's machine, the call blocks until the endpoint is reachable, and the tool list changes for the session. It does not say what happens on launch failure or how long it waits before giving up, which is the main remaining behavioral gap.

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

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

Three tight sentences, front-loaded with the primary action and effect, then the idempotent-behavior caveat, then the prerequisite. No filler or restated field names.

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

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

For a zero-parameter lifecycle tool with no output schema and annotations already declaring safety, the description covers purpose, blocking behavior, side effects, idempotency, and prerequisite. An agent has everything needed to decide to call it and to interpret a "already running" response.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; schema coverage is 100% and additionalProperties=false is self-documenting. Baseline for a no-parameter tool applies.

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

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

States a specific verb and resource ("Launch the WeftCut desktop app") plus the concrete effect (GUI window opens, MCP endpoint becomes reachable, tool catalog appears via tools/list_changed). Among siblings it is clearly the process-lifecycle tool, distinguishable from weftcut_status and from the project/motif loading tools.

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

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

Gives both the when-to-use condition ("Use after weftcut_status says the app is not running") and the when-it-is-unnecessary case ("Safe to call when already running — reports that instead of launching twice"). It names the sibling that gates it explicitly, so no inference is required.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds the useful constraint that no project context is required, but the phrase 'complete portable settings, default ID and name limit' is too compressed to convey clearly what each preset entry contains.

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

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

A single front-loaded sentence with the verb first and no filler. The trailing clause about 'default ID and name limit' is dense to the point of ambiguity, which slightly hurts comprehension even though brevity is good.

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

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

With no output schema, the description carries the burden of explaining what is returned, and while it gestures at preset contents and a name limit, it does not make the return shape or ordering clear. For a trivial parameterless list tool this is close to adequate, but an agent cannot predict the response structure from it.

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

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

The tool takes zero parameters and the schema is an empty object, so there is nothing for the description to disambiguate. Baseline for a parameterless tool applies and nothing misleads.

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 ('List') and resource ('export presets') with a scope qualifier ('built-in and personal'), which distinguishes it from the sibling write tools create_export_preset, update_export_preset and delete_export_preset. It stops short of distinguishing it from get_export_options, which an agent might reasonably confuse it with.

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?

'Available without a project' gives one concrete precondition, implying it can be called before a project is opened. There is no explicit guidance on when to pick this over get_export_options or how it pairs with start_export, so alternatives are only weakly implied.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavioral context by stating that returned entries carry props schemas, revisions and diagnostics, and by sketching the publication object on draft proposals with its state enum. It stops short of describing pagination or ordering.

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

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

Two compact sentences with the enumeration scope front-loaded and no filler. The second sentence is dense, using shorthand like 'rebound?' without explanation, but it is information-bearing rather than wasted.

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

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

With no output schema, the description carries the burden of characterizing return values and partially does so via props schemas, revisions, diagnostics and the publication shape. For a single-optional-parameter read-only list tool this is close to sufficient, missing only ordering or volume expectations.

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

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

Schema coverage is 100% and the single status parameter has an enum with its own description, so the schema does the work. The description's phrase 'built-in, installed and draft' loosely mirrors the enum values but adds no format or filtering semantics beyond them. Baseline 3 applies.

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

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

States a specific verb plus resource with explicit scope: 'List built-in, installed and draft Motifs'. The scope wording distinguishes it from the singular siblings such as read_motif and open_motif_draft, though those siblings are not named 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?

Usage is only implied: the enumeration scope suggests 'use this to see all motifs', which contrasts implicitly with read_motif for one motif. There is no explicit when-to-use versus alternatives, no mention of when to prefer read_motif or open_motif_draft 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?

Annotations already flag destructiveHint=true, and the description genuinely earns its keep on top of that: it discloses exactly what is destroyed (the other captions are deleted), what is preserved (style stays, span becomes the union), that a gap is spanned, and the `LayerOverlap` failure mode. It's one step short of a 5 because it doesn't say whether the merge is a single undoable edit beyond implying 'one recorded edit'.

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 action and scope, then effects, then refusal conditions. Dense but every clause carries information; nothing is filler.

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

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

With no output schema, the description compensates by stating the return value (the merged caption's record plus `removed`) and the error case. For a destructive one-parameter tool this is nearly complete; only undo/reversibility 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 100% and the single parameter is already described as 'Two or more captions on one caption track,' so the baseline would be 3. The description adds real meaning: the array is ordered by time, the earliest becomes the merge target, and all entries must share one lane — semantics an agent could not infer from the schema alone.

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

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

States a specific verb and resource (merge captions) and pins the scope precisely: two or more captions of ONE caption lane, collapsed into the earliest as a single recorded edit. That level of specificity separates it cleanly from siblings like split_layer, correct_caption_text, and trim_layer without needing to name them.

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

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

The description gives explicit when-not conditions: refuses non-caption layers, captions on different lanes, and unions that would overlap another cue. It stops short of naming the sibling tools to use instead (e.g., correct_caption_text for text-only edits or split_layer for the inverse), so the alternative routing is left implicit.

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 and destructiveHint=false, so safety is covered. The description adds real behavioral context beyond that: the index is 0-based, 0 means first applied, and the value must be strictly less than the effect count, which tells the agent the valid range and implicitly that other effects shift rather than being removed.

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 clauses, front-loaded with the action, then the indexing convention and its bound. No filler or redundant restatement of the tool name.

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

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

For a simple three-parameter reorder with full schema coverage and annotations that cover safety, nothing essential is missing. It stops just short of describing what happens to the displaced effects' indices or how an out-of-range index is reported.

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

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

Schema coverage is 100%, so the baseline is 3. The description does add one piece of meaning the schema lacks — the upper bound 'Must be < effect count' — but it largely restates the schema's 'new_index' wording about 0 being applied first.

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: 'Reorder an effect within its layer's chain.' This cleanly separates it from add_effect, update_effect, and delete_effect, all of which operate on the same entity without changing position.

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

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

The description makes the usage context clear (repositioning an existing effect within its chain) but never names alternatives or exclusions, e.g. that it is not for adding effects or for moving effects between layers. The distinction from update_effect is left to inference.

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

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

Annotations only assert openWorldHint=false and destructiveHint=false; the description goes well beyond that by disclosing ripple semantics ("the set's span closes behind it and opens at its landing on every track"), atomic refusal ("a start before 0, an occupied landing (LayerOverlap) or a lock refuses whole"), and the ripple-with-gap refusal analogous to delete_layers { ripple: true }. It even names the return shape, which is valuable since no output schema exists.

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

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

The core action and seed concept are front-loaded and no sentence is filler — grid snapping, atomicity, and return shape each add distinct information. The dense semicolon-and-em-dash packing makes it slower to parse than it needs to be for a caller skimming before invocation.

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

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

For a 6-parameter mutation with no output schema, the description covers the essentials: what moves, what anchors the move, how links and tracks behave, error/refusal conditions, and the return tuple. Nothing an agent needs in order to call this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine semantics the schema lacks: layer_ids[0] being the seed, every member keeping its offset on its own track including link partners, escaped via escape_link, and track_id relocating only the seed rather than the whole set. That relationship-level meaning is not derivable from the per-field 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 opening sentence gives a specific verb and resource ("Move a set of layers") plus the transactional framing ("as one recorded edit"). It is far from tautological, but it never names or contrasts the closely related siblings (shift_layers, retime_layers, move_layers_to_composition, restack_layer), so an agent must infer the boundary itself.

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

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

Usage conditions within the tool are stated precisely: the seed lands via t_start_us OR delta_us OR neither for a lane change alone, and insert:true selects the ripple behavior. However, there is no guidance on when to prefer this over shift_layers or retime_layers, which occupy adjacent semantic space in the sibling list, so the when-to-use-vs-alternative question is left implied.

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

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

Rich disclosure beyond the annotations: offsets are preserved relative to the anchor, internal links/transitions travel with the layers, straddling ones are cut, markers stay, and Group windows stay fixed. Annotations only say non-destructive and closed-world, so this adds real value; note the mild tension with destructiveHint=false, since cutting straddling transitions is a lossy side effect, though it is transparently disclosed.

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, then behaviours, then refusals in roughly priority order, with no filler sentences. The telegraphic phrasing ('compositions autofit; Group windows stay fixed') is dense but each clause carries information.

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

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

Covers refusal cases, link/transition handling, marker and Group behaviour for a complex multi-parameter mutation, which is what an agent needs before committing. Without an output schema, it could still say what a successful call returns or how partial failures are reported.

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%, yet the description still adds relational meaning the schema alone doesn't: the anchor is positioned at t_start_us while other members keep their offsets, and lane assignment is scoped per source track. It also clarifies that omitting to_track_id is a valid bounce-to-free-lane strategy rather than an error.

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

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

States a specific verb and resource with scope: 'Move selected layers into another composition,' which implies the cross-composition variant versus in-composition moves. It never names the neighbouring move_layers or paste_layers siblings, so the agent must infer the boundary itself.

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

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

Gives explicit when-not conditions ('refuses mixed source compositions, locks, cycles, negative starts and membership changes involving retimed Groups') and lays out the three lane strategies for to_track_id. What's missing is a direct statement of when to pick this over move_layers or paste_layers.

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 and destructiveHint=false, so the safety profile is largely covered. The description still adds real value by naming the domain error codes (TrackPositionOutOfRange, TrackReserved, TrackLocked, LayerLocked) and calling the operation "one recorded edit," which hints at undo/checkpoint integration. It stops short of describing how intervening tracks shift or what the response contains.

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 sentence that front-loads the action and scope before the error conditions. Every clause (index origin, range limit, three refusal cases) carries needed information, though the semicolon-chained error list makes it harder to scan than a short bulleted structure would.

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

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

With no output schema, the description carries the return/error burden and does so by enumerating the exact failure modes and the position validity rule. For a two-parameter mutation with reassuring annotations, this is nearly complete; only the effect on tracks between source and destination is left unstated.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds genuine meaning: the position is a z-order index with 0 at the bottom of the stack, and the valid range must be strictly below the current track count. That range constraint is not captured in the schema's integer type.

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

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

The description opens with a specific verb+resource ("Move a track to a different z-order position") and scopes it as "one recorded edit." The resource (track) distinguishes it from layer-level siblings like move_layers and restack_layer, but it never explicitly names an alternative or contrasts behavior with them.

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

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

Usage context is clear through the enumerated refusal conditions: reserved A/B roll tracks, locked tracks, and tracks holding a locked layer cannot be moved, which implicitly tells the agent to unlock first. There is no explicit when-to-use-vs-sibling routing, such as preferring move_layers for layer restacking.

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 openWorldHint=false and destructiveHint=false, so the description carries real weight here and delivers: the return shape {motif_id, revision}, idempotent reopening of a directory draft, resume-vs-copy behavior for motif ids, and the fact that copies report their source {id, version}. It stops short of stating persistence/locking behavior (e.g., what happens if a draft is already open 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-loaded with the action and return shape, then one compact line per source variant with no filler. The telegraphic register ("Copies answer source {id, version}") is dense enough that an agent may need a second read, but nothing is redundant.

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

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

For a single nested oneOf parameter with no output schema, the description covers four of five variants plus the returned {motif_id, revision}, which is a lot of the needed surface. The omission of the 'zip' source kind is the notable gap, since that path format and its consequences are documented nowhere else.

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 genuinely adds meaning the schema lacks: the schema labels both 'motif' and 'copy' entries identically as "Motif id (list_motifs)", and only the description distinguishes resume from duplicate. The 'empty' defaults (960×540, 5 s, no props) are also absent from the schema. The 'zip' variant is left entirely unexplained, which keeps this 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?

"Open a draft" gives a specific verb plus resource, and the per-variant lines make clear this tool materializes a draft from one of several sources. It never names a sibling (read_motif, preview_motif, install_motif, open_project), so the agent must infer the boundary with those tools from names alone.

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

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

The description effectively routes the agent across variants: directory = live linked folder, motif = resume if draft id else copy, copy = independent duplicate, empty = blank 960×540 5 s project. It gives clear usage context for each mode but no explicit exclusions relative to sibling motif tools or guidance on which tool to pick when a Motif merely needs inspection.

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

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

Annotations only say destructiveHint=true; the description turns that into concrete consequences (the currently open project is saved, its undo history is dropped) and discloses the no-op case (the already-open folder is not reloaded and answers already_open: true). That is exactly the extra context annotations cannot carry.

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 action, then the safety consequences, then the edge case and return shape, with no filler sentences. It is telegraphic in places ("only one the user asked for", the inline read_project snippet), which is efficient but slightly terse to parse on first read.

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

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

There is no output schema, and the description compensates by listing the return fields (`name, dir, replaced, already_open`). Combined with the destructive side effects, the already-open no-op, and the parameter constraint, an agent has everything it needs to call this correctly.

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

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

Schema coverage is 100% and the path param is already documented as an absolute path, so the baseline is met by the schema. The description still adds meaning by telling the agent what the path must point at – a folder containing project.json – which prevents pointing it at an arbitrary directory.

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

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

States a specific verb and resource ("Open a project folder ... in the editor") and pins down exactly which folder qualifies ("the one holding project.json") plus an anchoring reference to the start screen's Open. That is enough to separate it from siblings like create_project and read_project 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?

"only one the user asked for" gives an explicit usage constraint against speculative opening, and it routes the agent to `read_project { view: "session" }` for recent projects. It stops short of naming the boundaries against create_project or explicitly saying when NOT to call it, so it lands just under full marks.

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