WeftCut

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

With only destructiveHint:false in annotations, the description carries the real burden and delivers: the layer stands ALONE with no auto-pair and no link, it lands on the track's audio lane, timing snaps to the 48 kHz sample lattice, and role is a clip property rather than a track property. This is exactly the behavioral context annotations cannot provide.

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

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

Purpose and the key differentiator are front-loaded in the first sentence, and the remaining sentences each add distinct value (media constraints, standalone behavior, timing, role). It is dense and slightly long, 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?

For an 8-parameter mutation tool with no output schema, the description covers purpose, media eligibility, lane behavior, timing semantics, and the role default, and states that it returns the layer's record. 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 coverage is 100%, so the baseline is 3, but the description adds genuine meaning beyond the schema: src_* are source in/out versus t_* the timeline span, both snap to the 48 kHz sample lattice, and role selects the mixing bus (a clip property). That clarifies the semantics of overlapping-looking fields the schema labels tersely.

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 (add an Audio layer onto a track's audio lane), names the return value, and explicitly distinguishes itself from the sibling add_video_layer ('the only way audio-only media reaches the timeline'). An agent can select it correctly 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 condition versus the alternative: use this for audio-only media because add_video_layer refuses it. It also states which media types are accepted (Audio item or Video item with audio stream) and which are refused (Image, Subtitle), leaving nothing to inference.

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

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

With only destructiveHint=false in annotations, the description carries most of the burden and delivers: it discloses the return fields (layer_id, track_id, committed span, adjusted flag), warns that grid snap may alter the requested span, and states the non-overlap rule for the same track. It does not cover permissions or failure behavior on overlap, but it adds real behavioral context beyond annotations.

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

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

Two tight sentences, front-loaded with the action and return contract, followed by unit semantics and the key constraint. No filler or repetition.

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

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

For a 7-param tool with no output schema, the description usefully explains what the call returns and the one hard constraint. Remaining gaps (error behavior on overlap, whether snapping can be disabled, required permissions) are minor but real.

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

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

Schema description coverage is 100%, so the baseline is 3. The description clarifies the µs unit and the inclusive/exclusive boundary semantics, which largely restate what the schema already documents, and adds the 'adjusted for grid snap' meaning for the committed span. No new meaning is added for color, width, height, or composition_id.

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

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

States a specific verb and resource ('Add a solid-color layer to a track') and distinguishes itself from the many sibling add_*_layer tools by naming the exact layer type. The second clause clarifies the return behavior, so an agent knows both the action and the response shape.

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 tool's specialized purpose (color layer vs video/audio/text/group layers), and the non-overlap constraint tells the agent a precondition. However, it never explicitly says when to choose this over add_video_layer/add_text_layer, nor what happens if the precondition fails.

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=false, so the description carries the behavioral burden. It adds significant context: the effect is created with no params, audio params are static-only, audio.denoise does nothing until both profile bounds are set, and wrong layer kinds yield EffectKindNotApplicable. It also discloses the return record shape. This goes far beyond the structured annotation.

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 long but dense and purposeful: every clause adds operational detail—return shape, visual/audio rules, ranges, defaults, worklow, and catalog pointer. It is front-loaded with the core purpose and then organizes constraints and usage in a logical sequence. No filler sentences are present.

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

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

Given two required parameters, no output schema, and only a minimal annotation, the description is fully complete: it covers the return record, all kind-specific parameters, defaults, error behavior, and the required sequencing after creation. An agent has everything it needs to call add_effect correctly without external lookup.

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 dramatically expands the meaning of `kind`: catalog semantics, visual vs. audio layer compatibility, parameter ranges and defaults, and static-only restrictions. `layer_id` is simple enough that no further explanation is needed. This is a model of adding value beyond the input 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 ordering: 'Append an effect to a layer's chain (applied last) and return its record (`effect_id`, `kind`, `index`).' This clearly distinguishes add_effect from siblings like update_effect, move_effect, and delete_effect by defining exactly what this tool does and what it returns.

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 strong usage context: visual kinds go on visual layers, audio.* kinds are for Audio layers only, and a kind on the wrong layer fails with EffectKindNotApplicable. It also spells out the post-creation workflow (set static value via update_effect, then optionally set_keyframe for visual params). It does not explicitly contrast with move_effect/update_effect, but the guidance is sufficient for an agent to know when to use this tool.

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

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

With only `destructiveHint: false` in annotations, the description carries the burden well: it discloses default windowing (`src_in_us: 0`, `src_out_us: duration_us`), identity transform, independent instances sharing content, and the precise refusal cases with error names (RootComposition, CompositionCycle, InvalidArgument) guaranteed before any mutation. This is rich behavior beyond what annotations provide.

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

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

Front-loaded with the core action and the create_group contrast, and every sentence adds information (semantics, defaults, refusal cases). It is dense with parentheticals and could be marginally tighter, 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?

For a mutation tool with no output schema, the description covers placement semantics, defaults, and failure modes thoroughly. The only minor gap is that it never hints at what a successful call yields (e.g. a new layer id for follow-up operations), which an agent might want.

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: `source_composition_id` is the placed content, `track_id`/`t_start_us` are the location, and it notes the whole-composition windowing default. It does not discuss the optional `composition_id` check parameter, which the schema handles instead.

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 (place an EXISTING composition as a Group layer) and explicitly distinguishes itself from the sibling `create_group` ('makes a NEW one'). An agent can tell exactly what this does and how it differs from the create path.

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

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

Names the alternative (`create_group`) and the condition separating them (existing vs new composition), and gives follow-up guidance ('trim it afterwards for a slice'). It also points to `project://compositions` for valid ids, so the agent knows when and how to use it.

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

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

With only destructiveHint=false in the annotations, the description carries the disclosure burden and does so well: it names the refusal conditions (partial links, locked members, cycles) and the return value. It could say more about what 'preserving external placement' actually guarantees, but the failure-mode disclosure is strong context beyond the annotation.

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: action, preconditions/refusals, return. Zero filler and the core action is front-loaded.

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

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

With no output schema, 'Returns the resulting Group' is necessary and present, and refusal conditions are covered. Minor gap: no mention of atomicity/partial-failure behavior for a multi-layer move, but the description is otherwise complete for a 2-param 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 both layer_ids and group_layer_id are already documented as same-composition and singular/multiple respectively. The description adds no syntax or format detail beyond the schema, 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 precise verb+resource+scope: move clips into an *existing* Group, which implicitly distinguishes it from create_group and add_group_layer in the sibling list. An agent can tell what this does 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 prerequisites (Group rate 1, compatible selection) but never states when to choose this over create_group, add_group_layer, or ungroup_layer. Usage is implied by the preconditions rather than routed against alternatives.

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

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

With only destructiveHint=false in annotations, the description carries the burden and delivers: it discloses the return value ('Returns the marker record (marker_id, t_us as snapped)'), reveals time-snapping behavior, and states the failure mode for an invalid anchor ('refused for the same reasons (no marker is created)'). None of this is available from annotations, and it does not contradict destructiveHint=false.

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

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

Three sentences with zero filler. The first sentence front-loads the core action, target, and return value; the second and third each add exactly one variant dimension (region vs point, anchored vs fixed). Every clause earns its place.

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

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

Complete for a 6-parameter creation tool with no output schema: the description covers the return record shape (since there is no output schema), the key decision axis of root vs named composition, and both optional-behavior switches. Required params (color, label, t_us) are fully documented in the schema, and annotations cover the safety profile.

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 reveals that t_us is returned 'as snapped' (behavioral semantics the schema doesn't capture), and it frames end_t_us and anchor_layer_id as mutually exclusive marker-type selectors. The schema itself is already rich for anchor_layer_id, so the description complements rather than repeats.

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 ('Add'), resource ('marker'), and target ('composition's timeline — the root, or the Group named by composition_id'). It distinguishes point vs region markers and anchored vs fixed markers, which separates it from sibling tools like set_marker_anchor, update_marker, and delete_marker without needing to open their schemas.

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

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

The description gives clear selection context for the two major variants: set end_t_us for a region marker, set anchor_layer_id to follow a clip vs omit for an ordinary marker. It references set_marker_anchor as the analogous tie operation, implicitly distinguishing creation-time anchoring from post-hoc anchoring. However, it never explicitly says 'use update_marker to modify an existing marker' or 'use delete_marker to remove one' — those exclusions are left to inference from sibling names.

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

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

With only destructiveHint=false in annotations, the description carries real behavioral weight: it discloses that omitting track_id spawns a fresh track (a side effect), that omitted props fall back to defaults, and that unknown props are rejected (error behavior). It does not address undoability or permission requirements, 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 tight sentences with the core action front-loaded and no filler; each clause conveys a distinct fact (discovery, defaults, error behavior). Slightly dense but well structured and appropriately sized.

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 tool with a nested props object and no output schema, the description covers the prerequisite (list_motifs), default behavior, and rejection rules. It mentions returning a record but doesn't characterize that record, a minor gap given no output schema exists.

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

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

Schema description coverage is 100%, so the schema already documents every parameter in detail, including the same 'omit to use defaults' and 'unknown keys reject' notes. The description largely restates those facts rather than adding new parameter meaning, which is the baseline 3 for a fully documented schema.

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

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

The description gives a specific verb and resource ('Add a Motif layer') and states it returns the new record, so the core action is unambiguous. It does not, however, explicitly distinguish this tool from the many sibling layer-creators (add_text_layer, add_video_layer, add_audio_layer, add_group_layer), relying on 'Motif' alone to carry the distinction.

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 supplies a real prerequisite ('Read list_motifs for motif_id and props_schema'), which steers the agent to the discovery step before calling. There is no explicit when-to-use vs. when-not guidance and no named alternative among the sibling layer-add tools, so usage is only 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 only supply destructiveHint=false, so the description carries most of the burden and does well: it discloses the born-at defaults (font, 72 px, opaque white, centred), that x/y are an anchor not clamped to frame, and the hard constraint that the layer cannot overlap another visual layer on the track. It stops short of permissions or failure/auth behavior, keeping it out of the top band.

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, then defaults, then placement semantics, then the overlap rule, then the alternative sibling. Dense but every clause carries distinct information; the em-dash catalogue is stylistically heavy but not wasteful.

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

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

For a create tool with a thin annotation set and no output schema, the description covers defaults, placement anchor rules, the styling hand-off, the overlap constraint, and the sibling alternative. Nothing essential for a correct call is missing; only edge-case failure behavior 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%, so the baseline is 3 and the schema already documents each field. The description still adds real meaning beyond it: x/y must be given "both or neither," and they define the ANCHOR point, unclamped to the frame — semantics the schema only partially implies.

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 Text layer") with concrete examples (title, lower third, credit) and promises the returned record. It explicitly distinguishes itself from `apply_subtitles` (one-off vs. document-derived) and implicitly from `add_video_layer`/`add_color_layer`, so an agent can select it 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?

Names the alternative route explicitly — subtitles from a document go to `apply_subtitles`, "this is the one-off" — and points to `update_layer_params { kind: 'Text' }` for all further styling. When-to-use and when-not are both stated with no inference 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?

The description goes well beyond the single destructiveHint annotation, disclosing that tracks are kind-agnostic, auto-disappear when their last layer leaves, and that empty tracks survive until filled and emptied. This is valuable side-effect information an agent needs to predict tool 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?

Two sentences with no filler: the first states the action and return value, the second explains the critical lifecycle behavior. The most decision-relevant information is front-loaded.

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

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

Despite having no output schema, the description names the exact return fields, making the response shape predictable. Combined with the 100% schema coverage for parameters and the lifecycle disclosure, nothing essential is missing for an agent to invoke this tool correctly.

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

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

Schema coverage is 100%, so the schema already documents both parameters clearly. The description adds no parameter-specific meaning beyond the schema, but it does reinforce the optionality of label and composition_id through the lifecycle context. This matches the baseline for full schema coverage.

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

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

The description uses a specific verb and resource: 'Add a track and return its record,' clearly identifying the operation and its result. It also differentiates this tool from siblings like delete_track, rename_track, and move_track by focusing on creation and the returned fields.

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

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

The description gives clear behavioral guidance: tracks are not meant to be reserved, so users should place a layer rather than create an empty track for later use. It does not explicitly name alternative tools, but the lifecycle explanation effectively tells the agent when creation is appropriate.

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 provide destructiveHint=false, but the description discloses substantial side effects: overlap moves the incoming layer left, link siblings follow, nothing ripples, extend borrows media, and one undo restores every moved layer. It also documents error codes like TransitionInsufficientHandle and TransitionUnsupportedLayerKind.

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 long but dense, with every clause contributing operational value. It is front-loaded with purpose, then parameter semantics, then refusals, and contains no filler or redundant restatement of the schema.

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

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

The description covers prerequisites, side effects, placement behavior, refusal conditions, and error types. The only notable gap is that, with no output schema, it mentions returning 'its record' but does not specify the record's shape or fields; for a tool this complex, that is a minor omission.

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 description adds meaning well beyond the enum strings: direction is explained as MOTION direction with concrete left/right behavior, placement distinguishes movement vs. media borrowing, and from/to layer roles are defined. This materially helps an agent choose correct parameter values.

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

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

The description states a specific action: adding a transition at the cut between two adjacent layers on the same track, with from/to roles and a returned record. It clearly distinguishes from sibling tools like update_transition and delete_transition by focusing on creation and placement semantics.

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

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

The description gives clear context for when the tool is valid: prerequisites, placement modes, and refusal conditions. However, it does not explicitly name alternatives such as update_transition or delete_transition for cases where the agent should edit or remove an existing transition 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 only declare destructiveHint=false, so the description carries the real behavioral burden and does so richly: atomic commit of an auto-paired dialogue Audio layer onto the same track's audio lane, the default state of `auto_pair_audio_on_import`, and the failure mode ('an occupied lane rejects the whole call naming the blocker'). This is exactly the kind of context annotations cannot express.

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

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

Information-dense and front-loaded with the core action, then type-specific parameter rules, then the pairing/atomicity caveat. Every clause carries weight, though the long single paragraph and heavy backtick density make it slightly harder to scan than ideal.

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 explicitly documents the returned record's fields (`audio_layer_id`/`link_id`/`audio`, null when unpaired), plus the atomicity and error semantics. A 7-parameter mutation tool is fully covered with nothing an agent needs to call it correctly left out.

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 baseline is 3, but the description adds interpretable meaning: src_in_us/src_out_us are 'source in/out points' vs t_start_us/t_end_us as 'the timeline span', plus the Image-omit rule. It stops short of documenting media_id/track_id/composition_id beyond the schema.

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

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

States a specific verb+resource ('Add a visual layer from an imported Video or Image item onto a track and return its record') and explicitly distinguishes itself from siblings, naming `add_audio_layer` as the destination for audio-only items. An agent can tell it apart from add_color_layer/add_text_layer/add_audio_layer 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?

Gives explicit when-to-use (visual content from Video/Image) and when-not-use ('an audio-only item is refused and pointed at `add_audio_layer`'). It also differentiates the two accepted item types by parameter behavior (Video requires src_in/src_out; Image omits them).

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

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

Annotations already declare readOnlyHint=true, and the description adds substantial beyond-annotation context: the 60 s per-call cap, cache-limited peaks (not true-peak or LUFS), max_points affecting only the summary, and the explicit caveat that these are amplitude measurements rather than beats/bars/melody. That is exactly the behavioral disclosure a caller needs.

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?

Dense but front-loaded: what it does, what it returns, then scope and limits. Almost every sentence earns its place, though the description is longer than strictly necessary and packs several distinct caveats together.

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

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

No output schema exists, so the description must describe return values, and it does so concretely (microseconds, bins, onsets, dB, resolution, counts). Combined with the caveats and the source-to-timeline formula, an agent has everything needed to call it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces source-absolute microseconds and that max_points affects only the summary, but the schema already carries these meanings, so it adds little beyond structured data; the timeline-placement formula is usage guidance rather than parameter semantics.

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 (analyze original source audio from cached waveform peaks) and immediately scopes it as local, read-only, no model. It enumerates the return payload (source-absolute microseconds, peak/RMS bins, onsets, signed dB changes, resolution, event counts), which distinguishes it clearly from siblings like analyze_clip or 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?

Gives explicit when-to-use context: 'Choose music edit/alignment points, including outside a clip's trim', plus the operational prerequisite 'Wait for the waveform job if not ready.' It does not name an alternative tool or state when-not to use it, so it stops 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 mark readOnlyHint=true, so the description correctly aligns with that. It adds substantial behavioral detail beyond annotations: deterministic operation, source-absolute timestamps clipped to the layer's window, the merging behavior for min_shot_us, and the structure of the returned shot and cut_scores. This gives agents a full picture of what happens during execution and what to expect from the result.

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

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

The description is long but every sentence earns its place. It front-loads the core purpose, then the return structure, then parameter explanations, then usage alternatives. There is no redundancy or filler—each detail directly aids correct invocation. The structure is logical and scannable.

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 tool's complexity (4 parameters, detailed output, and no output schema), the description is fully self-sufficient. It explains the output format, parameter semantics, default values, usage constraints, and alternative tools. There is nothing an agent needs to know to call it correctly that 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?

Even though schema coverage is 100%, the description adds meaning beyond the schema. It explains the effect of sensitivity ('lower = more cuts'), the default for min_shot_us (500000), and the purpose of passes (dropping 'stats'/'events' for timing only). These clarifications help agents choose correct values and interpret the behavior.

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 starts with a precise action: 'Detect shot boundaries in a VideoClip layer.' It names the resource (VideoClip layer) and the output (shot boundaries) clearly. It also explicitly differentiates from the sibling auto_split_by_shot by noting the alternative for splitting, so an agent can distinguish it from other analysis tools like detect_pauses or compare_frames.

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

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

It provides explicit guidance: 'VideoClip layers only' restricts scope, and it names the alternative tool for splitting with 'To split at every cut in one edit use auto_split_by_shot.' It also gives a usage tip about the 720p proxy preference, helping agents choose the right input. This is clear when-to-use and 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?

Annotations only supply `destructiveHint: false`, so the description carries the real burden and delivers: it discloses the packing algorithm (first unlocked track with room, new track only on collision), the single-undo-edit granularity, the ASS-styling simplification caveat, and the return shape including a `simplified` flag. This is the kind of behavior an agent cannot infer from structured fields.

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

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

Densely packed into three sentences with the core action front-loaded and every clause carrying information (track packing, undo granularity, styling caveat, return value). The time-0 restatement slightly echoes the schema, so it is not perfectly waste-free, 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?

For a mutating, multi-part operation with no output schema, the description covers prerequisite, placement semantics, track-selection behavior, styling limitations, and the return payload. 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 description coverage is 100%, so the schema already documents all three parameters. The description restates `t_start_us` as the document's time 0 and `composition_id` as root-when-omitted, which largely duplicates the schema text rather than adding syntax or edge-case meaning. 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 (lay onto caption tracks) and resource (an imported Subtitle item's cues as editable Text layers), and distinguishes itself from the import step by naming `import_media` as the source and `Subtitle` as the artifact. An agent can tell it apart from `apply_transcripts` or `restyle_captions` from the description alone.

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

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

It establishes the prerequisite clearly — the item must already be imported via `import_media`. It gives context for placement via `t_start_us` and `composition_id`, but never states when NOT to use it or which sibling (e.g. `apply_transcripts`, `restyle_captions`) handles a related job. Clear context, no explicit alternatives.

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

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

With only a non-destructive annotation, the description carries the behavioral load well: cues pack into existing tracks, a lane opens only on total collision, cues snap to the frame grid, `source_layer_ids` tags cues by take, a 1000-transcript cap, and 'One recorded edit' discloses undo semantics. Rich context beyond the annotation.

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?

Dense but front-loaded, opening with the core action and return value before the input-shape guidance. Every sentence carries information, though the paragraph is packed and could be slightly more scannable.

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

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

No output schema is needed — the description already names the returned fields. For a three-parameter layout tool, it covers inputs, packing behavior, limits, and undo, leaving nothing an agent needs to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: `source_layer_ids` is parallel to `transcripts` and tags each cue with its source clip so corrections group by take. The `word_timing` enum is also explained in prose (where offsets came from, `none` stores no timing).

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 — laying transcripts onto caption tracks while preserving per-word timing — and declares the return shape `{ caption_track_id, cues }`. It is clearly distinguishable from `transcribe_clip` (which produces the envelope) and `correct_caption_text` (which consumes word offsets).

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: pass `transcribe_clip`'s envelope as-is, or supply your own cues with `word_timing: 'none'`, and notes that `correct_caption_text` needs word offsets. It does not, however, address when to prefer this over the sibling `apply_subtitles`, so an explicit alternative exclusion is missing.

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

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

With destructiveHint=true already declared, the description adds genuinely useful context beyond the annotation: 'as one edit' conveys single-undo semantics, and it specifies that drop_short also removes overlapping link members, which is a non-obvious destructive side effect. Return behavior is also disclosed. Missing only whether the original clip is consumed.

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, front-loaded sentences with the purpose first. Minor waste: the min_shot_us default and drop_short semantics duplicate the schema verbatim, but nothing is padded.

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

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

No output schema exists, and the description compensates by documenting the return contract (layer_ids in timeline order, or the original ID when no interior cut exists). Combined with the destructive annotation and 100% schema coverage, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100% and the schema already documents all three parameters including the 500000 default and drop_short's link-deletion behavior. The description largely restates the schema, adding no new format, units, or edge-case detail, so baseline 3 is appropriate.

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

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

States a specific verb (split), resource (VideoClip), and the distinguishing source of cut points (cached analyze_clip shot cuts), explicitly contrasted with a generic split by noting 'as one edit'. This lets an agent tell it apart from split_layer and analyze_clip without opening schemas.

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

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

The phrase 'at cached analyze_clip shot cuts' implies the prerequisite that analyze_clip must have run, but the description never states when to choose this over split_layer or trim_layer, nor any exclusions. Usage is inferable but not 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?

Beyond the single destructiveHint=false annotation, the description discloses idempotency on repeat calls, connection-based exclusion semantics, takeover behavior, auto-cleanup when the stream drops, and that the view may be switched without ending the session. It even notes 'Unrecorded,' which is a meaningful behavioral trait. No contradiction with 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 description is dense but every sentence adds value: purpose, checkpoint creation, connection semantics, takeover path, cleanup behavior, view flexibility, and recording state. It is front-loaded with the primary purpose and avoids redundant or filler 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?

For a session-management tool with one parameter and no output schema, the description covers the essential behavioral contexts: what happens on first call, repeat call, competing connection, and connection loss. It also names the exact takeover mechanism and the cleanup condition, making it fully usable by an agent without needing to infer 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 the only parameter, 'reason,' is already documented in the schema as 'What this work session is for.' The description repeats this by saying it is shown beside the busy badge but adds no new semantic meaning beyond the schema. 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 clearly states the action ('Begin a work session'), the resource (the agent session), and what it does visually ('show the lightweight agent view'). It also mentions creating a Pre-agent checkpoint, distinguishing this from ordinary session tools and from sibling checkpoint tools.

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

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

The description provides explicit lifecycle guidance: reusing the same connection returns the existing session, a different connection is refused, and takeover requires end_agent_session { force: true }. It also directs the user to finish with end_agent_session and explains when the app auto-closes the session, leaving no ambiguity about when and how to use it.

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

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

Annotations declare destructiveHint=true, and the description usefully adds that the call is a no-op on an already-Static track, so the agent knows the destructive scope is limited to animated tracks. It also documents the default when `value` is omitted. It does not mention undo/reversibility, so it stops short of full disclosure.

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

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

Three dense sentences, front-loaded with the core action, then typing details, then the no-op caveat. No filler and nothing that restates 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 3-param mutation tool with no output schema and a destructiveHint annotation, the description covers behavior, typing, and idempotency adequately. Scoping (only the named param on the named layer is affected) is inferable but not stated, and reversibility 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 already 100%, so baseline is 3, but the description adds real meaning beyond the schema: the color object shape ({r,g,b,a}, integers 0..255) and the omission default of holding the first keyframe's value. That is the one piece of type information the schema description leaves implicit.

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

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

States a precise verb+resource: "Collapse a param's animation back to a single Static value." An agent can readily distinguish this from siblings like delete_keyframe, update_keyframe, or smooth_keyframes because the outcome (a single held value) is named explicitly.

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

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

Usage is implied by the semantics plus the "No-op on an already-Static track" condition, which tells the agent the operation is safe to call idempotently. However, no alternatives are named — e.g. it never says to use delete_keyframe/update_keyframe instead when the caller wants to edit rather than flatten a track.

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 mark readOnlyHint=true, and the description reinforces this with 'Read-only', which is consistent. It goes beyond annotations by disclosing the return format (phash_hamming, ssim, similar) with explicit thresholds and ranges, the fact that the two sides can be the same or different clips, and that errors name the offending side. This is rich, actionable behavioral context.

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

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

The description is a single dense paragraph with zero filler. It front-loads purpose, then covers parameter semantics, return semantics, and constraints in a logical flow. Every sentence carries necessary information, and it avoids restating the tool name or generic phrasing.

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

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

For a tool with nested objects, no output schema, and a specific timestamp convention, the description covers all bases: use cases, parameter interpretation, return fields with thresholds, the read-only nature, and error behavior. An agent can invoke it correctly without needing to inspect other 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% with clear per-property descriptions, so baseline is 3. The description adds value by clarifying the timestamp space ('SOURCE-ABSOLUTE µs' and cross-referencing analyze_clip's keyframe_t_us and media:// URLs) and by noting the sides may be same or different clips. This goes beyond the schema's basic 'Target VideoClip layer id' and 'microseconds' phrasing.

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 clear verb+resource ('Compare two video frames for perceptual similarity') and adds concrete use cases (dedup shots, match a cutaway). It is the only tool in the sibling set that performs frame comparison, so it is naturally distinguished; it also clarifies that it works on VideoClip layers, removing ambiguity.

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

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

It explicitly gives usage contexts (dedup shots, match a cutaway) and states a hard constraint ('VideoClip layers only'), which helps the agent decide when to call it. However, it does not name an alternative tool to prefer in other cases, nor does it say when NOT to use it beyond the layer-type restriction. Still, the intended scenarios are clear.

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

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

With only `destructiveHint: false` in annotations, the description carries the behavioral burden and does so thoroughly. It discloses blank-script refusal, pre-write whole-call refusal on locked targets, split/merge behavior based on word timing, return shape, and the fact that the operation records exactly one 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?

The description is front-loaded with the core action and includes only valuable details, but the middle section packs many clauses into a dense, em-dash-heavy sentence. It is still efficient, but slightly harder to parse than necessary.

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 mutation tool, the description covers defaults, scoping, invalid input behavior, lock handling, word-timing effects, return value semantics, and side-effect granularity. No output schema exists, so the explicit `Returns { changed }` note is essential and present.

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

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

Although schema description coverage is 100%, the description adds meaningful semantics: omitting `layer_ids` means all captions, a non-caption id refuses the call, and `composition_id` refers to a Group id from `project://compositions`. This goes well beyond the schema's basic property descriptions.

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

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

The description clearly states a specific verb and resource: correct captions against the project's reference text using the configured correction script. It also distinguishes the tool from sibling operations by mentioning re-segmentation, word timing, and refusal conditions, so an agent can tell what this tool uniquely 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?

It provides strong usage context: the tool works on all captions by default, `layer_ids` narrows scope, non-caption ids are refused, and the correction script must be configured. It references `apply_transcripts` and `set_project_settings` for related concepts, but it does not explicitly contrast this tool with alternatives like `merge_captions` or `restyle_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?

Beyond the destructiveHint annotation, the description discloses that checkpoints persist in the project file, survive later commits, are shown in the agent panel with Restore buttons, and return a specific object. It also includes the notable 'Unrecorded' behavioral trait. This provides substantial behavioral context that annotations alone do not 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?

The description is three sentences with no wasted words. The primary action and return value are front-loaded, followed by persistence details, panel behavior, usage guidance, and the important 'Unrecorded' note. Every sentence earns its place.

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

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

For a single-parameter creation tool with a non-destructive annotation and no output schema, the description is complete. It covers what the tool does, what it returns, persistence, lifecycle behavior, UI representation, and when to use it. Nothing essential is missing.

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

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

The schema covers the only parameter, label, with 'Checkpoint name.' The description adds conceptual context by calling it a 'named checkpoint' and mentioning the returned label, but it does not add syntactic or format details beyond the schema. Baseline 3 is appropriate given full schema coverage.

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

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

The description clearly states a specific action and resource: creating a named checkpoint of the current state. It also distinguishes checkpoints from the redo tail by noting they survive later commits, which separates this tool from related concepts. The return value is specified, leaving no ambiguity about what the 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?

The description gives explicit usage context: 'Use it at logical batch boundaries.' This tells the agent when the tool is appropriate. It does not explicitly name alternatives or exclusions, but the checkpoint semantics and sibling tools like restore_checkpoint and list_checkpoints make the intended workflow reasonably clear.

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

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

Annotations only supply destructiveHint=false, so the description carries most of the behavioral burden and does so well: it names the three refusal conditions, states that placement and links are preserved, and even discloses the return payload ('the Group clip and composition') in the absence of an output schema. It stops short of explaining what happens to the original layer stack or whether the operation is 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?

Four tightly packed sentences, front-loaded with the action and followed by constraints and return value. Minor redundancy between 'preserving their placement and links' and 'Group members retain their own timing and effects,' though each carries slightly different 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, the description compensates by naming the return value, and it covers preconditions and preservation semantics for a small two-parameter mutation. It lacks any note on permissions, undo/checkpoint interaction, or effect on the source layers, which would make it fully self-sufficient.

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

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

Schema description coverage is 100% and both parameters carry their own descriptions (label optional with UI-derived fallback; layer_ids as at-least-one, single-composition layers). The description adds no parameter-level detail beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Pre-compose selected clips into a new Group') and clarifies that it operates on selected clips rather than layers/tracks generally. It does not explicitly contrast itself with the closely related siblings add_group_layer, add_group_members, or ungroup_layer, so an agent must infer the distinction 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?

Usage is implied by 'pre-compose selected clips,' and the refusal conditions (partial links, locked members, incompatible selections) implicitly tell the agent when the call will fail. However, there is no explicit statement of when to choose this over add_group_layer or ungroup_layer, nor any prerequisite guidance.

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

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

Annotations only declare destructiveHint=false, so the description carries the burden and does it well: it discloses the failure mode, the opt-in reassign escape hatch, the side effect of removing members from prior links, and the cascade of auto-dissolving links that fall below 2 members. It also names the returned record shape. Note: the reassign path does destroy/dissolve links, which sits in tension with destructiveHint=false, but because destruction is strictly opt-in and the default refuses instead, this reads as a nuance rather than a flat contradiction.

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

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

Three dense sentences, front-loaded with the core action, then the failure/reassign rule, then the return value. 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?

With no output schema, the description fills the gap by naming the returned fields, and it covers prerequisites, failure conditions, and side effects for a 2-param mutation tool. 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 coverage is 100%, so baseline is 3, but the description adds semantics the schema does not: that ids must be *distinct*, that the conflict failure applies per layer, and that reassign has a cascade effect (auto-dissolving undersized links). That is meaningful meaning beyond the field docs.

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 ('Create a new link') plus the input constraint (>=2 distinct layer ids), which clearly separates it from update_link and delete_link among the many siblings. An agent knows exactly what this tool produces.

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

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

It gives the explicit conflict condition ('If any layer is already in another link, the op fails') and the remedy ('unless reassign=true'), which is real when-to-use guidance. It stops short of naming the sibling alternative (e.g., update_link for existing links), so it is not a full 5.

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

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

Annotations only mark destructiveHint=true; the description adds crucial side-effect context that the previously open project is saved and that the frame rate locks once a layer is placed. It also discloses defaults and the return shape, with no contradiction to annotations.

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

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

A dense but efficient paragraph front-loads the create/open action, then adds usage condition, side effect, defaults, and return value. Every sentence contributes to correct 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?

Covers the return value despite no output schema and includes side-effect and default information. It leaves some ambiguity around what `replaced` means and does not explicitly route the agent to open_project, so it is strong but not fully complete.

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

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

Schema description coverage is 100%, so baseline is 3, but the description adds default values not present in the schema: `default_parent_folder` and 1920x1080 at 60 fps. It also explains the rate-lock behavior, adding useful meaning beyond the parameter definitions.

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: creates `<parent_folder>/<name>` and opens it, explicitly analogized to New Project. The create/open action is clear and distinguishable from sibling tools such as 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?

Gives the condition 'only when the user asked,' which is clear context for invocation. However, it does not name open_project as the alternative for existing projects or state exclusions beyond that condition.

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 provide destructiveHint=true, and the description substantially expands on that: deletion is limited to the restore point, edits persist, undo history is unaffected, and the operation is unrecorded. It discloses the CheckpointNotFound error condition and the deliberate non-interaction with history locking. This goes far beyond the annotation.

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 sentences deliver a large amount of behavioral information with no filler, and the main action is front-loaded. The phrasing 'CheckpointNotFound for an id list_checkpoints does not report' is slightly awkward, but the structure is still tight and readable.

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 description covers the effect, non-effects, undo implications, error behavior, lock interaction, and undo/recording status. Nothing an agent needs to decide whether to call it or anticipate its consequences is missing.

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

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

The schema already documents checkpoint_id with 100% coverage, giving a baseline of 3. The description adds that the id must be one list_checkpoints reports or CheckpointNotFound is raised, which clarifies the valid value source. This extra error-condition context raises the score above baseline.

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

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

The description opens with a precise verb and resource: 'Drop a named checkpoint.' It distinguishes the action from restore/revert paths by stating 'Only the restore point goes — the edits it marked stay,' which differentiates it from restore_checkpoint. Clear and unambiguous.

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

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

It gives clear context that dropping a checkpoint does not alter timeline or undo stack, implying it is for cleanup rather than revert. It also explicitly clarifies that set_history_lock does not block this operation, which tells an agent when this tool remains available. It does not name sibling alternatives explicitly, so it stops 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?

The destructiveHint annotation already flags mutating behavior, and the description adds valuable context beyond it: the tool refuses while references exist, includes the CompositionInUse error with ref_count, mentions the root composition exclusion, and notes that the operation is recorded. This meaningfully enriches the annotation-only picture.

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

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

Three sentences with no filler: the main action is first, constraints and failure modes follow, and the 'Recorded' outcome note is a compact final touch. 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 one-parameter destructive tool with a complete schema and a clear annotation, the description fully covers what the agent needs: when it is appropriate, when it will fail, and what happens afterward. No output schema is needed because the behavior is simple and fully disclosed.

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 covers the single parameter completely (composition_id with description 'Composition id.'), so the baseline is 3. The description adds no additional parameter-level semantics, but none are needed for such a simple, well-documented parameter.

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

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

The description states a specific verb (Delete) and resource (composition), and further narrows the scope to orphaned compositions that nothing references. It clearly differentiates this from sibling tools like delete_layers or delete_track, which operate on other entities.

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

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

The description gives clear conditions for use: delete only a composition nothing references, specifically orphans left after Group layer deletion. It also states when the tool refuses to operate (referenced compositions and root), effectively defining exclusions, though it doesn't name an alternative tool explicitly.

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 annotation already marks this as destructive, and the description's 'Remove' is consistent with that. The description adds no further behavioral context such as irreversibility or side effects, but for such a simple deletion there is little additional behavior 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?

One focused sentence with no filler. The key action, resource, scope, and parameter mechanism are all communicated efficiently.

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

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

This is a simple two-parameter destructive operation. The description plus schema fully cover what the tool does and what arguments are needed; nothing an agent requires 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 description coverage is 100%, and both layer_id and effect_id are described in the schema. The description's 'by id' loosely maps to these parameters but adds no meaning beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

The description states a specific verb ('Remove'), a resource ('effect'), and a scoping detail ('from a layer by id'). This clearly differentiates it from sibling tools like add_effect, update_effect, and move_effect without needing to inspect their schemas.

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

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

The description gives clear context: this tool is for removing an existing effect from a layer using IDs. It does not explicitly name alternatives or say when not to use it, but the operation is unambiguous enough for an agent to route correctly among siblings.

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

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

Annotation already declares destructiveHint=true, so the safety profile is covered. The description goes beyond that by disclosing the side effect when the removed keyframe was the last one ('the track collapses to Static holding that key's value'), which the agent could not infer from annotations or schema.

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

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

Three short sentences, zero filler, with the core action front-loaded and the prerequisite and side-effect following. 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 single-keyframe destructive op with no output schema and full schema coverage, the description covers purpose, the id-prerequisite, and the collapse side effect. It omits reversibility/undo guidance, which for a destructive tool is a minor remaining gap.

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

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

Schema description coverage is 100%, so the schema already documents layer_id, param_key (with full enum/pattern enumeration), and keyframe_id. The description only echoes 'by id' and 'layer param' and adds no format or semantics beyond the schema, 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 ('Remove') and resource ('a keyframe by id from a layer param'), and the granularity ('a keyframe', single, by id) implicitly distinguishes it from bulk siblings like clear_keyframes or track-level delete_track.

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 prerequisite/routing instruction: 'Get the id from get_param_track,' which tells the agent the upstream workflow needed before calling. It doesn't state any when-not conditions or name a preferred alternative for bulk removal, but the context is clear enough to invoke correctly.

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 provide only destructiveHint=true, yet the description discloses the full behavioral profile: atomic all-or-nothing refusal naming the specific blocker (LayerLocked, TrackLocked, RippleInsideHole, RippleCollision, RippleLinkStraddles, RippleLockedLayer), pre-write validation, track pruning, marker/playhead behavior, and the empty-set edge case.

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 ripple semantics are front-loaded before the error catalog, and every sentence carries information. It is dense but not padded; the long single paragraph and back-to-back parenthetical error codes slightly hurt scannability.

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

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

For a destructive batch-mutation tool with no output schema, the description covers defaults, atomicity, side effects (track pruning, downstream shifts), and the complete failure taxonomy, leaving nothing an agent needs to call it correctly unspecified.

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 goes well beyond the schema's one-line ripple definition by specifying exactly what shifts (every remaining layer at/after a hole, on every track, anchored markers riding along, free markers and playhead unaffected), how touching holes merge, and how layer_ids interacts with the ripple refusal cases.

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 clause states a specific verb and resource ('Delete a set of layers') plus the salient semantic detail that it is 'one recorded edit'. An agent can distinguish this from siblings like shift_layers or ripple_delete_gap, which operate on gaps rather than a batch of layers.

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 thoroughly explains the when-to-choose decision between the two modes: ripple=false leaves the span empty, ripple=true closes holes and shortens the film. It does not explicitly name alternative sibling tools (e.g. ripple_delete_gap) or say when not to use this tool, so it falls short of 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?

The annotations already declare destructiveHint=true, so the description does not need to restate destructiveness. It adds useful context that the member layers are preserved, which clarifies a non-obvious side effect beyond the bare annotation.

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 a single succinct sentence followed by one high-value clarification. The core action is front-loaded, and every clause earns its place without redundancy.

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

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

For a simple, single-parameter destructive operation with complete schema coverage pending, the description covers the essential action and the key side effect (layers are preserved). It does not discuss return values or undo behavior, but given the low complexity and existing annotations, the core information an agent needs is present.

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

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

The input schema fully documents the sole parameter link_id with a basic description. The tool description adds no additional meaning about how to obtain or format link_id, relying entirely on the schema's 100% coverage.

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

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

The description opens with a specific verb, 'Dissolve (delete)', and identifies the resource as 'a link', making the primary action unambiguous. The clarification that member layers are not deleted also differentiates this from layer-deletion tools like delete_layers and clarifies scope relative to link-related 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?

No explicit when-to-use or alternative tool guidance is provided. The agent must infer from sibling names like create_link and update_link that this is the tool for removing a link; there is no mention of when not to use it or how it compares to deleting compositions or motifs.

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 annotation already declares destructiveHint=true, so the agent knows it is destructive. However, the description adds no extra behavioral context beyond that—no mention of irreversibility, confirmation, or side effects. It essentially restates the action without enriching the agent's understanding.

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

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

The description is a single, efficient sentence that conveys the core action with no wasted words. It is appropriately sized for a simple delete 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?

For a simple one-parameter destructive tool with annotations covering the destructiveness, the description is minimally adequate. However, it could mention that the deletion is permanent or that it targets a specific marker by ID, but given the schema and annotations, it is sufficient for basic use.

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 provides 100% coverage of the single parameter (marker_id) with a description, so the baseline is 3. The tool description adds nothing about the parameter, but the schema already handles it adequately.

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 clear verb ('Remove') and resource ('a marker'), which distinguishes it from siblings like add_marker and update_marker. It is specific enough to know the action, though it doesn't specify any additional scope or conditions.

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

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

There is no guidance on when to use this tool versus alternatives like update_marker or set_marker_anchor. The description does not mention contexts, prerequisites, or conditions, leaving the agent to infer usage.

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 annotation only provides `destructiveHint: true`, but the description goes far beyond that: it discloses the rejection unless force, the atomic commit, link dissolution below two members, transient lane pruning, TrackLocked refusal, and recording behavior. This is exactly the kind of side-effect disclosure an agent needs for a destructive operation, and it does not contradict the annotation.

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 every sentence contributes: the core action, the conditional, the cascade specifics, and the recording behavior. It is front-loaded with the primary purpose and organized logically from the basic operation to edge-case details, with no filler or repetition.

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

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

For a destructive tool with no output schema, the description covers the main behavior, failure modes (rejection, TrackLocked), and side effects (links, lanes, recording). The only notable omissions are the success return (if any) and behavior for a non-existent media_id, though these are minor for a delete operation and the description is otherwise quite 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?

Although schema coverage is 100%, the description adds substantial meaning beyond the schema's `force` description. It details the atomic commit, the exact behaviors of links/lanes, and the recording distinction, which the schema only vaguely refers to ('their links and emptied lanes go too'). This gives the agent a much richer understanding of the parameter's consequences.

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: 'Remove a media item.' It then clarifies the conditional behavior with `force`, making the tool's core function unmistakable. It also distinguishes itself from the sibling `delete_layers` by referencing that tool's behavior in the cascade, so an agent can tell them apart.

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 clearly explains when `force=true` is needed (when layers reference the media) and what the default rejection means. It also evokes `delete_layers` as the analogous cascade behavior. However, it does not explicitly state 'use delete_layers when you only want to delete layers and keep media' or otherwise draw a direct when-to-use line between the siblings, leaving that to inference.

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

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

With destructiveHint=true, the description adds crucial context: it refuses built-ins and unknown ids, and explains that placed layers referencing it degrade to an error placeholder. This goes beyond the annotation, informing the agent of 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?

Two concise sentences, front-loaded with the action and scope, then important constraints and consequences. No wasted words.

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

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

For a simple one-parameter destructive tool, this is complete. It identifies the target, valid sources of id, refusal conditions, and downstream effects, leaving nothing essential unknown.

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 already fully covers the id parameter (100% coverage), but the description reinforces that the id should come from list_motifs, adding practical guidance on how to obtain a valid id, which is slightly beyond the schema description.

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 states the tool deletes a Motif by id, specifying that it applies to installed or draft user Motifs and that built-ins and unknown ids are refused. It also references list_motifs for what exists, distinguishing it from other sibling tools.

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

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

It implies when to use: to delete an installed or draft Motif, and when not: built-ins or unknown ids are refused. It doesn't explicitly mention alternatives, but the context is clear enough for an agent to know this is the deletion action.

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`, so the description carries the real behavioral load and does so richly: error codes, cascade behavior (layers deleted with the track), link cleanup folded into the same undo entry, Group-layer `ref_count 0` semantics, and the A/B-roll-only protection rule. This is well beyond what the annotation conveys.

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 dense sentences, front-loaded with the core action, each covering a distinct edge case (refusal, cascade, group composition, protected track types). No filler or repetition despite the detail.

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 mutation with only a destructiveHint annotation and no output schema, the description covers everything an agent needs: preconditions, force semantics, cascade and link side effects, undo scoping, and the protected-track exception.

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 earns extra credit by describing the *consequences* of `force=true` (layers go with it, links cleaned up in one undo entry) rather than just restating the boolean's default and refusal behavior already 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 ("Remove a track") and immediately scopes it against siblings by describing the refusal path, the protected track classes, and routing the leftover composition to `delete_composition`. An agent can distinguish this from `delete_layers` and `delete_composition` 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 states when the tool refuses (non-empty track, `TrackNotEmpty`) and how `force=true` changes the outcome, plus names `delete_composition` as the follow-up for an orphaned Group composition. It does not explicitly compare against `delete_layers` for the case where the caller wants to keep the track, leaving one inference to the agent.

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 annotation already signals destruction, but the description adds valuable context: provenance-based shrinkage, layer movement, and the fact that the system never makes room. It also notes the action is recorded and lists error types, going beyond the annotation.

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 technically detailed. While every sentence adds information, it is longer than necessary for a delete operation and could be tightened. The core action is front-loaded, but the paragraph format makes it less scannable.

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 mechanical behavior, error cases (TransitionRestoreCollision, TransitionNotFound), and recording status. It does not explicitly state return values, but for a delete action this is often implicit.

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

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

Schema description coverage is 100% for transition_id, so the baseline is 3. The description does not add new info about the parameter itself, but it references internal fields like extended_us and duration_us that explain the operation's mechanics, which is acceptable since the parameter is straightforward.

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 states the verb 'Remove' with the resource 'transition' and the outcome 'restore the hard cut'. It distinguishes this from sibling tools like add_transition and update_transition by describing the specific deletion behavior and provenance routing.

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 tool's purpose is obvious from the description, and it explicitly provides handling for the TransitionRestoreCollision error by advising to move or delete the blocker first. It does not explicitly name alternatives, but the context of siblings makes it clear this is for removal.

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 readOnlyHint annotation: discloses caching (per source range, keyed by fps/focus/language), strict backend behavior that errors rather than substitutes, error messages naming the missing binary/model/endpoint, and remapping of retimed clips onto source time. This is unusually rich behavioral context for a read 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 core action and return shape, then details parameters; every sentence carries information. It is dense and parenthetical-heavy (engine names, defaults, cache-key notes), which slightly hurts scannability.

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

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

With no output schema, the description supplies the full return contract (`{ backend, model, segments: [...] }` with field meanings and source-absolute microseconds), plus defaulting, caching, and failure behavior. Nothing needed 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 coverage is 100%, so the baseline is 3, but the description adds real meaning: it explains what focus does to the returned tags, that language is a BCP-47 tag and part of the cache key, that backend is a strict override, and that fps sampling is capped to the model's context. It largely mirrors rather than exceeds the schema, hence 4 rather than 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 (describe), resource (VideoClip layer), and output shape (timestamped open-vocabulary segments), and names the model family doing the work. This is clearly distinguishable from siblings like analyze_clip, transcribe_clip, and analyze_audio, which cover other modalities.

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 sampling model, the optional windowing, and the privacy-relevant consequence of choosing a local backend (frames never uploaded), which all inform when to pick this tool. It never explicitly names a sibling to prefer or a when-not-to-use condition, so it stops short of full routing guidance.

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

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

Annotations already declare readOnlyHint=true, and the description reinforces it with 'Read-only'. It adds substantial behavioral context beyond annotations: the exact detection algorithm (peak below threshold_amp for min_pause_us, bridge_us exception), the return shape, timeline-absolute µs, sorted order, noise_floor_amp meaning, peaks_source values, and the error/retry condition. This is rich, non-redundant behavioral disclosure.

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

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

The description is dense but every sentence earns its place: purpose, read-only distinction, algorithm, defaults, layer resolution, return format, and error handling. It is front-loaded with the core purpose and the read-only note, then flows logically into parameters and behavior. No filler or repetition of schema text.

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

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

For a read-only detection tool with no output schema, the description is complete: it explains the return value shape, units, sorting, the meaning of derived fields, the error condition, and the retry strategy. 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 100%, so the schema already documents all four parameters. The description adds value by explaining the algorithm's semantics (how threshold_amp, min_pause_us, and bridge_us interact) and by clarifying that layer_id accepts a VideoClip that resolves to its linked Audio layer and is refused when it plays no sound. This goes beyond the schema's field-level descriptions.

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

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

The description states a specific verb ('Find'), a specific resource ('pauses in a clip's audio'), and the exact detection criteria. It also distinguishes itself from siblings by naming remove_pauses and add_marker as the write counterparts, so an agent can tell it apart without opening schemas.

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

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

The description explicitly says when to use this tool (to find pauses) and names alternatives (remove_pauses to cut, add_marker to mark). It also gives operational guidance: wait for media:job_complete with kind=waveform and retry if the waveform job hasn't finished. This is clear context with exclusions and alternatives.

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 readOnlyHint annotation by disclosing that it validates after each op, halts at the first error, and returns a specific `{ results, halted_at }` shape. It also documents refusal behavior for `ripple: true` and the special `transition_kind` handling, providing rich behavioral context.

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

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

The description is dense but efficiently organized: the core behavior is front-loaded, and the supported-ops list and return type are packed into compact, readable sentences. Every clause earns its place, and the use of backticks and inline examples aids comprehension without bloat.

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 tool's complexity, the description is complete: it specifies the clone-and-validate behavior, the halt condition, the return shape, the full set of supported operations, and the exclusions. It also references the per-op schemas indirectly via 'that tool's args', so an agent can combine this definition with the sibling tool schemas without missing any needed information.

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?

Even though schema coverage is 100%, the description adds meaning beyond the schema by listing the exact supported operation kinds and explaining that add_transition uses `transition_kind` because `kind` names the op. It clarifies the expected shape of each operations array item and what values are valid.

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: 'Run a sequence of edit operations against a clone of the project WITHOUT committing.' This clearly differentiates dry_run from the many actual mutation tools among the siblings, and the phrase 'before touching real state' reinforces that it is a rehearsal, not a real edit.

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

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

It explicitly says when to use the tool ('check overlaps and invariants before touching real state'), what it supports (a specific list of ops), and what it refuses ('ripple: true is refused'). It also names non-dry-runnable operations, giving clear exclusion criteria.

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

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

Behavioral details go well beyond the `destructiveHint: false` annotation: the description explains that the history lock is released, the current view and activity records are kept, running tasks are not canceled, MCP is not disconnected, later calls are not prohibited, and the action is 'Unrecorded.' It also discloses the force behavior and the ownership condition, giving a complete picture of side effects and limitations.

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 tightly packed with information in a logical flow: core action, then clarifications of non-effects, then ownership/force rules, then a pointer to read_project, and a final note on recording. Every sentence earns its place, and the most important information is front-loaded.

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

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

For a 1-optional-parameter tool with no output schema, this description is complete. It covers the action, side effects, ownership rules, force semantics, how to check ownership, and the unrecorded nature. An agent has all necessary information to correctly invoke the tool and decide whether force is appropriate.

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 describes the `force` parameter as 'End another connection's session too. Default false.', the description enriches it with context: `force: true` takes over another connection's session (and its lock) when its owner is gone. This explains the intended use case and adds meaning beyond the schema, outweighing the high schema coverage baseline.

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

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

The description opens with 'End your work session and release its history lock,' a specific verb-resource pair that clearly states the tool's core action. It further distinguishes itself from siblings like begin_agent_session and set_history_lock by focusing on session termination and lock release. The addition of what it does not do (cancel tasks, disconnect MCP, prohibit later calls) removes ambiguity.

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 explicit when-to-use guidance by clarifying that only the owning connection may end a session and that `force: true` is for when the owner is gone, pointing to `read_project { view: "session" }` as the way to check ownership. It also implicitly states when not to use it (e.g., if you need to cancel tasks) by listing non-effects. This gives an agent clear decision criteria.

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

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

Beyond the `readOnlyHint` annotation, the description adds meaningful behavioral context: it 'Records nothing' and explicitly says the caller must write `body` to a file themselves. It also discloses that captions are returned in time order and that cue text is 'as it stands,' which prevents assumptions about retiming or normalization.

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

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

The description is compact and front-loaded: it states the output type, the source and ordering, the return payload, the caller's required follow-up, and the side-effect guarantee. Each sentence adds distinct necessary information with no filler.

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

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

Because there is no output schema, the description correctly explains the return contract as `{ format, cues, body }` and tells the agent how to use `body`. It covers lane selection, ordering, and read-only guarantees; the only minor omission is the internal shape of the `cues` array, which is not essential for writing `body` to a file.

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

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

Schema description coverage is 100%, so the parameters are already well documented. The description reinforces the meaning of `format`, `track_id`, and composition selection, and adds the time-order behavior, but it does not provide substantial parameter-specific detail beyond what the schema already supplies.

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 states that the tool returns the captions of a composition as a subtitle document, with `format` restricted to `srt` or `vtt`. It also defines the source scope (all lanes or one `track_id`) and ordering, which clearly distinguishes it from caption-mutating siblings like `apply_subtitles` or `restyle_captions`.

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 context for when to use the tool: when you need a subtitle document from existing caption lanes and want the cue text as-is. It does not explicitly name alternatives or state when not to use it, but the read-only export framing and 'Records nothing' signal the correct use case without needing further 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 cover readOnlyHint=true; the description adds rich behavioral context: it never uploads anything, refuses layers with no audio, caps windows at 60 s, returns a specific JSON metadata shape plus an MCP audio block, and describes the conversion (mono 16 kHz 16-bit). This far exceeds what the annotation provides.

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

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

The description is front-loaded with the core purpose but then packs a dense parenthetical field list, a units note, a default note, a window formula, and refusal conditions into one long paragraph. Every sentence carries information, but the density and the inline field enumeration make it harder to scan than necessary.

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

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

Given a 3-param tool with no output schema, the description supplies the return shape, the audio encoding, the default behavior, the window limit, the source-offset mapping formula, and refusal conditions. 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 100%, so baseline is 3, but the description adds meaning beyond the schema: it explains that t_start_us/t_end_us are composition-absolute µs, default to layer endpoints, and that the window cannot exceed 60 s of source audio (which depends on playback_rate). It also warns that a VideoClip's audio is its own stream, not its linked Audio layer.

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 precise verb+resource ('Extract a VideoClip or Audio layer's ORIGINAL source audio') and adds a scope qualifier ('before gain, mute, effects or mixing') that distinguishes it from siblings like analyze_audio, separate_audio_to_new_track, and transcribe_clip. The distinction from transcribe_clip is reinforced by 'for an agent running its own speech model; no engine or API key is involved.'

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 signals when to use it ('for an agent running its own speech model') and implicit alternatives (transcribe_clip, analyze_audio) via the 'no engine or API key' framing. However, it never names a sibling or states explicit exclusions, so it falls 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?

The readOnlyHint annotation already establishes this is a safe read, so the bar is lower; the description still adds value by disclosing that the result includes refusal reasons for unavailable modes. It does not describe the result shape in detail, but for a non-mutating query that is acceptable.

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

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

A single compact sentence that front-loads the action and scope, with zero filler. Every clause earns its place.

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

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

No output schema exists, so the description's mention of refusal reasons partially compensates for the missing return documentation. For a two-parameter read-only query with fully described params and a safety annotation, that is nearly complete.

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

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

Schema description coverage is 100%, so both parameters (purpose enum, layer_ids) are already documented in the schema. The description's 'Preview or Export' and 'per clip' wording mirrors that without adding syntax or format detail, 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?

State's a specific verb ('Query') and resource ('Preview or Export interpolation support per clip'), so an agent can distinguish it from the write-side sibling set_frame_interpolation. It stops short of naming that sibling explicitly, which is the only thing keeping it from 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?

'Query ... support' implies a pre-check before calling set_frame_interpolation, and 'refusal reasons for unavailable modes' hints at diagnostic use. However, no explicit when-to-use, prerequisites, or named alternative is given, leaving usage 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?

The annotations already declare readOnlyHint=true, and the description reinforces this with 'Read' and 'before editing', which clarifies the non-destructive intent. It adds useful context beyond the annotation by specifying the source shape ('{ manifest, html }') and the motif kinds covered.

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

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

Three short sentences, each earning its place: the core action, the behavioral guidance, and the parameter source. No filler or repetition beyond the schema's id note.

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 read-only tool with a simple input schema, the description is complete. It states what will be read, the scope of motifs, when to call it, and where the id comes from. The absence of an output schema is mitigated by the inline '{ manifest, html }' shape.

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

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

Schema description coverage is 100% and the schema already states 'The Motif id (from `list_motifs`)'. The description repeats the same guidance for `id`, adding no new semantic detail beyond what the schema provides. Baseline 3 applies because the schema carries the load.

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

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

The description uses a specific verb ('Read') and resource ('a Motif's source'), and states the scope ('any built-in, installed, or draft'). This clearly distinguishes it from list_motifs (listing) and write_motif_draft (writing), even 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?

The description gives clear usage context: 'Read this before editing so you can base your changes on the current source.' It also tells the agent where the id comes from ('`id` comes from `list_motifs`'), but it does not explicitly describe when not to use it or name alternative tools.

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 readOnlyHint annotation already covers safety. The description goes beyond that by giving the full return shape (Static vs Keyframed), explaining tangent semantics, continuity, segment classes, and that preset_id is absent on hand-tuned curves and the last key. This is rich behavioral context for a read operation.

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

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

It is front-loaded with purpose and a return example, but the long third sentence is a dense run-on detailing many nested fields (in/out, continuity, segment, preset_id). Every detail is arguably relevant, yet the structure is packed rather than scannable.

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 the return, and it does so thoroughly, including field-by-field semantics. It omits pagination or error behavior, but for a read track call this is nearly complete.

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

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

Schema coverage is 100%, so the schema already documents both params, giving a baseline of 3. The description adds mode-specific context for position params (x/y in XY mode, path_progress in Path mode as a fraction not a percentage), which is useful but not tied to the required layer_id/param_key mechanics.

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: read a layer param's animation track. It also frames its role in the workflow ('the record to inspect before editing keys'), which orients the agent without needing any sibling schema.

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

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

The phrase 'the record to inspect before editing keys' implies the read-before-write workflow, but no explicit when-to-use/when-not guidance and no named alternative (e.g., set_param_track) are provided. Usage is inferable but not 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?

Richly discloses behavior beyond annotations: hashing with blake3, conditional ffprobe metadata probing, special subtitle handling, validation refusals before writing, rollback of provisional rows on failed reads, and 'Unrecorded' state. This goes well beyond the single destructiveHint=false annotation and provides no contradictions.

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 information-dense but well-structured: purpose, processing behavior, return shapes, error handling, and record state. Every sentence adds value, and the primary purpose is front-loaded.

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

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

Despite no output schema, the description fully documents return values for both media files and subtitle documents, and covers failure modes including invalid paths and interrupted reads. This is complete enough for an agent to invoke the tool correctly without additional inference.

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

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

Schema description coverage is 100%, and the single 'path' parameter is well documented in the schema. The description reinforces the absolute-path requirement and adds the subtitle special case, but the schema already carries the semantic load.

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?

Description uses a specific verb ('Import') and resource ('ONE media file from an absolute path'), distinctly identifying the operation. It clearly differentiates from sibling tools like delete_media and apply_subtitles by focusing on ingestion of a file.

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 intended use is clear: import a single readable media file from an absolute path. It does not explicitly name alternatives or exclusions, but the scope is narrow and well-defined by the input constraints and the unique functionality among siblings.

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

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

Annotations provide only destructiveHint=true; the description adds rich behavioral context beyond that: version bumping so every placement re-renders, rebinding and migrating current-project layers, the refusal case, and the `{ motif_id }` return value. This tells the agent what side effects to expect when invoking the tool.

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

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

A single dense sentence with zero filler — every clause earns its place, front-loading the core action before the mode details. It is slightly run-on with nested parentheticals, but appropriately sized for the semantic complexity it conveys.

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 3-param mutation tool with no output schema, the description covers modes, target resolution, failure condition, side effects, and the return shape `{ motif_id }` (needed because no output schema exists). Only minor gaps remain, such as error behavior for invalid draft_id, which are acceptable given the complexity.

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

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

Schema description coverage is 100%, so the baseline is 3. The schema already documents mode, draft_id, and target_id semantics thoroughly; the description's added value is the refusal condition and the version-bump effect, which is marginal since the core parameter meaning is already fully 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+resource ('Install a draft') and precisely distinguishes the two publish modes: 'new' publishes under the draft's own id, 'update' republishes over a target. This clearly separates it from siblings like write_motif_draft (creates drafts) and preview_motif_draft (previews), so an agent can pick the right tool without opening schemas.

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

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

Explains mode selection and target resolution in detail, including the fallback to the draft's recorded `write_motif_draft { from }` target and the refusal condition when neither target exists. It references the draft-producing sibling explicitly, giving clear context, though it stops short of an explicit 'use this instead of X' exclusion statement.

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 annotation only says destructiveHint=true, and the description adds substantial behavioral detail: out-of-range indices are refused with live bounds, evicted entries affect the numbering, records nothing, and a later edit truncates future history like undo. This goes far beyond the annotation without contradicting it.

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

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

The description is dense but every sentence earns its place: purpose first, then parameter semantics, bounds, lock interaction, and side effects. There is no fluff or repetition, and the most important distinguishing facts are front-loaded.

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

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

For a single-parameter tool with no output schema, the description covers what matters for a correct call: what the tool does, how to compute the index, refusal behavior, lock blocking, and post-jump truncation semantics. It is sufficiently complete for an agent to invoke it confidently.

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

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

Even though the schema already describes index at 100% coverage, the description enriches it with the exact numbering scheme (`ops[i]` sits at `window_start + i`), the role of `evicted`, and how bounds are computed. This is precisely the kind of semantic context an agent needs to compute a valid index.

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

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

States a specific verb and resource: 'Move the history cursor to an absolute stack index.' It also distinguishes itself from undo/redo/restore_checkpoint by describing it as the way to reach a state that is neither one undo away nor a checkpoint, which clearly separates it from 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 explicit usage context: the history panel's click-a-row, and the way to jump to an arbitrary state. It names related tools (undo/redo/restore_checkpoint) and an exclusion condition (set_history_lock blocks it), so an agent knows when and when not to use it.

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

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

No annotations are provided, so the description carries the behavioral burden; it discloses the GUI side effect, the wait-for-endpoint behavior, automatic catalog availability via tools/list_changed, and idempotency when already running. It does not mention timeout or explicit failure behavior, but the essential behavioral profile is well covered for a 0-parameter launcher.

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, each carrying distinct useful information: the action and side effect, the success effect, and the invocation condition. The description is front-loaded with the core purpose and contains 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 zero-parameter tool with no output schema and no annotations, the description covers the prerequisite, the side effect, the success behavior, and the already-running case. The only notable omission is failure/timeout behavior, which keeps this just short of fully complete.

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

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

The input schema has zero parameters, and the description adds no parameter detail because none is needed. Per the rubric, 0 parameters receives a baseline score of 4.

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 ('Launch') and resource ('WeftCut desktop app'), and clarifies the immediate side effect: it opens the GUI and waits for the MCP endpoint. It is clearly differentiated from sibling tools like weftcut_status by framing the launch as the action to take when the status says the app is not running.

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 explicitly tells the agent to call this tool 'after weftcut_status says the app is not running' and explains that calling it when already running is safe and reports instead of double-launching. This is clear selection and precondition guidance.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds useful context by specifying the ordering (oldest first) and the absence of project snapshot data, which helps set expectations. It does not describe pagination or limits, but with zero parameters and a simple list operation, this is acceptable.

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

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

One sentence that front-loads the action and scope, then adds the return fields and the key exclusion (no project snapshot). Every word earns its place; 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 zero-parameter read-only list tool, the description is complete: it states what is returned and what is not. The only minor gap is no mention of pagination or maximum result count, but that is not critical for a checkpoint listing tool with no parameters.

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

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

The tool has zero parameters, so there is no schema burden to compensate for. The description fully explains what the tool returns, making parameter semantics a non-issue. Baseline 4 for zero-parameter tools 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 clearly states the tool lists all named checkpoints, oldest first, and specifies the exact fields returned (id, label, actor, created_at). It also explicitly notes that no project snapshot is included, which distinguishes it from related checkpoint tools like restore_checkpoint or create_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?

The description implies this is a read-only listing tool for checkpoints, and the sibling tools include create_checkpoint, restore_checkpoint, and delete_checkpoint, so an agent can infer when to use it. However, it does not explicitly state when not to use it or name an alternative for snapshot-related operations.

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?

Even with readOnlyHint=true, the description adds substantial behavioral detail: the exact returned array shape, the `status` enum values, the optional `target_id` field, and the fact that drafts are immediately placeable. This goes well beyond the annotation and makes the tool's behavior predictable.

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, each earning its place: scope in the first, return contract in the second, and a downstream usage warning in the third. The most important information is front-loaded.

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

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

There is no output schema, so the description fully carries the burden of explaining return values, and it does so with a precise array literal, field names, and enum values. For a zero-parameter read-only tool, 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?

The tool has zero parameters, so there is nothing for the description to explain about input semantics. Per the 0-parameter baseline this is appropriate, and the description correctly focuses on what the returned data means rather than parameters.

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

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

The description opens with a specific verb and resource: 'List every motif `add_motif_layer` can place', and disambiguates the scope as 'built-ins plus installed and draft user motifs'. It clearly distinguishes list_motifs from write/install/add sibling operations.

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

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

It explicitly tells the agent to read `props_schema` before calling `add_motif_layer` because unknown prop keys reject, which is actionable context for when to consume this tool's output. It does not state when not to use it or name alternative listing tools, but there is no direct sibling that lists motifs.

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 exactly what happens: the merged edit is recorded, the span becomes the union, the text is joined by line break, other captions are deleted, and gaps are spanned. It also discloses failure modes (`LayerOverlap`) and the return shape. This fully characterizes the destructive behavior.

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

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

The description is dense but every sentence earns its place: the core action is front-loaded, followed by outcome details, refusal conditions, and return value. There is no filler or repetition of the input schema.

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

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

For a single-parameter destructive tool with no output schema, the description is complete. It covers input constraints, merge semantics, deletion behavior, edge cases (gap spanning), error conditions, and the return value. An agent has everything needed to invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantic meaning: it clarifies that the captions must be on one lane, that the earliest becomes the result, and that the union must not overlap another cue. This goes beyond the schema's simple 'Two or more captions on one caption track' without inventing new parameters.

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

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

The description opens with a specific verb and resource: 'Merge two or more captions of ONE caption lane into the earliest.' It precisely defines the result (span union, joined text, retained style) and distinguishes itself from sibling tools like split_layer and restyle_captions by describing a unique merge behavior. The scope is unambiguous.

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

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

The description clearly states when this tool applies: combining multiple captions on the same caption lane into one. It also gives explicit exclusions by listing refusal conditions (non-caption layers, different lanes, overlapping unions). It does not explicitly name alternatives, but the constraints are specific enough that an agent can select this tool correctly.

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 provide idempotentHint=true and destructiveHint=false, so the bar for behavioral disclosure is lower. The description adds meaningful context about new_index being 0-based and bounded, which clarifies valid behavior. It stops short of describing invalid-index handling, but this is minor given 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?

Two short sentences with no redundant wording. The core operation is front-loaded, and the critical index constraint is stated immediately after.

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 mutation with full schema coverage and annotations covering idempotency and destructiveness, the description provides enough to call the tool correctly. The only missing piece is failure behavior for out-of-range indices, but that is not essential for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds extra meaning to new_index beyond the schema's 'Target position' by specifying 0-based indexing, that 0 is applied first, and that the value must be less than the effect count. This helps an agent compute valid values.

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 states a specific verb ('Reorder') and resource ('effect within its layer's chain'), and distinguishes this from sibling tools like add_effect, update_effect, and delete_effect. The 0-based index semantics also make the purpose actionable.

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

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

The description implies when to use the tool — when reordering effects in a layer chain — and provides a precondition ('Must be < effect count'), but it does not explicitly state when not to use it or contrast it with alternatives like move_layer or add_effect. Usage is clear enough but not fully guided.

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 read/destructive hints by disclosing that the end time shifts by the same delta, that cross-track moves are validated against destination layers, that negative starts are refused rather than clamped, and that linked siblings move along unless escape_link is used. It also names the returned data, giving a clear picture of mutation behavior.

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

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

The description is tightly written with four sentences, each carrying substantive information. The primary action is front-loaded, followed by behavioral notes, validation rules, and return values—all without redundancy or 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 mutation tool with four parameters, no output schema, and modest annotations, this description is exceptionally complete. It covers the operation's effect, validation, edge cases, linked behavior, and return payload, leaving an agent well equipped to invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful semantics beyond the field names: it explains the relationship between start-time changes and the end time, clarifies cross-track validation behavior, and specifies that out-of-range starts are rejected. This enriches the meaning of new_t_start_us and new_track_id beyond 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 opens with a specific verb and resource—'Move a layer to a different track and/or start time'—clearly distinguishing this from siblings like move_effect and move_track. The additional detail about end-time shifting and standalone time moves sharpens the boundary further.

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 use case is implied well: when you need to reposition a layer in time or across tracks. However, it does not explicitly name alternatives such as shift_layers or set_position, nor does it state when not to use this tool over them. The guidance is inferable but not explicit.

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

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

With only destructiveHint=false from annotations, the description carries real weight: it discloses refusal conditions (mixed source compositions, locks, cycles, negative starts, retimed Group membership changes) and edge-case semantics (internal links/transitions move, straddling ones are cut; markers stay; compositions autofit; Group windows stay fixed). This is exactly the kind of consequence detail annotations cannot express.

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

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

Front-loaded with the core action, then layered details in compact sentences with no filler. It is dense but each clause carries behavioral information; slightly telegraphic transitions ('Markers stay; compositions autofit') cost a little readability but no real waste.

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

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

For a complex multi-parameter mutation with no output schema, the description covers destination clock semantics, lane behavior, refusal cases, and post-move side effects. An agent has everything needed to invoke it correctly; nothing material is missing.

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

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

Schema coverage is already 100%, but the description adds meaning beyond the schema: it explains that the anchor lands at anchor_t_start_us while other members retain offsets, and that lane assignment is 'per source track.' The omit/spawn/free-lane semantics largely restate the schema's to_track_id description, so it is an enhancement rather than a gap-filler.

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+scope: 'Move selected layers into another composition.' This is clearly distinguishable from the sibling move_layer (single layer) and move_track, and the plural 'layers' plus 'another composition' pins down the operation.

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 precise in-domain routing for lane assignment: omit to_track_id to find space, use 'spawn' for fresh lanes, or name a free unlocked lane, plus a clear refusal list. It stops short of naming an alternative sibling (e.g., move_layer) for single-layer moves, so it misses the explicit when-not comparison that would earn 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 idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds the boundary constraint 'Position must be < current track count', which is genuinely useful. However, it doesn't disclose what happens when the constraint is violated (error vs clamp vs no-op), and given idempotency, that behavior would matter to the agent.

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

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

Two sentences, zero filler. The primary action is front-loaded, and the z-order zero-point clarification plus boundary constraint each earn their place as operational details the agent needs before calling.

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 two-parameter, non-destructive, idempotent operation with no output schema and no nested objects, the description covers everything an agent needs: what it does, the indexing convention, and the validity bound. The only minor gap is unspecified error behavior on out-of-range input.

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 fully documented in the schema. The description repeats the '0 is the bottom' detail already in the schema and adds the boundary constraint reinforcing new_position. This is marginal added value above the schema, matching the baseline 3 for full coverage.

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

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

States a specific verb (move), resource (track), and outcome (different z-order position). The z-order concept distinguishes it from track CRUD siblings like add_track/delete_track/rename_track and from move_effect/move_layer which target other object types. It doesn't explicitly name the closest sibling (restack_layer/set_position), so it's 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?

The z-order language implies when to use it (reordering tracks in the stack), but it gives no explicit when-not-to-use guidance and names no alternatives. With siblings like restack_layer and move_layer operating on adjacent concepts, explicit routing would strengthen this. Usage context is inferred, not stated.

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

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

With destructiveHint=true already declared, the description goes well beyond annotations by specifying what gets destroyed ('The project open before is saved; its undo history is dropped') and disclosing the return shape `{ name, dir, replaced }`. It also scopes the target folder precisely via project.json.

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, each earning its place: purpose, destructive side effect, alternative lookup, and return shape. Front-loaded with the action and free of 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 single-parameter mutation tool with no output schema, the description supplies the side effects, the disambiguating folder definition, the sibling lookup path, and the return shape. 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?

Only one parameter, path, is fully described by the schema ('Absolute path of the project folder'), giving 100% schema coverage. The description adds marginal clarification that the folder is the one holding project.json, but nothing about format or edge cases. Baseline 3 is appropriate when the schema carries the load.

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 (the one holding project.json) in the editor') and ties it to the start screen's Open action, which disambiguates it from create_project and read_project. An agent can tell exactly what this does without opening the schema.

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

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

The phrase 'only one the user asked for' gives a clear behavioral constraint on when to invoke, and it routes the agent to `read_project { view: "session" }` for recent projects. It lacks an explicit negative case (e.g., when not to open), but the positive guidance and alternative reference are 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?

The description is exceptionally transparent about behavior: it discloses all-or-nothing batch semantics, the specific error conditions (TrackLocked, LayerOverlap), how clones link to each other rather than to sources, and what the return payload looks like. It also notes this is 'one recorded edit,' implying undoability. This goes far beyond the minimal destructiveHint=false annotation and adds real behavioral context.

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

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

The description is dense but every sentence earns its place; there is no filler or repetition of the schema. It front-loads the core purpose and uniqueness before diving into parameter semantics and error behavior. The structure moves logically from what the tool does, to how to use it, to edge cases and return value.

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

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

Despite having no output schema and only minimal annotations, the description covers everything an agent needs to invoke and interpret the tool: parameter relationships, batch atomicity, failure modes, linking behavior, and the return structure. This is a complex tool with four interacting parameters, and the description is complete enough that no critical behavioral question is left unanswered.

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