MorphaReels

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

With readOnlyHint=false and destructiveHint=false already declared, the description sensibly focuses on effect rather than safety: the overlay "Plays in the editor preview and is mixed into the MP4 export," which tells the agent where the change surfaces. It does not cover failure modes (e.g., bad filename, overlapping overlays), but output schema covers the response shape.

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

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

Four dense sentences, front-loaded with purpose first and prerequisites second, with no filler. The only mild redundancy is restating the upload's `filename`/`name` binding that the schema also documents.

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

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

For a 9-parameter mutation tool with an output schema and annotations, the description supplies the important missing context: accepted formats, the upload prerequisite, the fps math, and the ultimate effect on preview/export. Minor gaps remain around error behavior and how this interacts with an existing overlay on the same track.

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 above baseline by supplying the conversion rule "frames = round(s * 30)" at 30 fps and tying `filename`/`name` to the upload's returned values, which directs how to populate required and optional fields. The remaining params (gain, fades, sourceLayerId) are documented adequately in the schema itself.

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

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

Opens with a specific verb + resource ("Add an audio overlay") and enumerates accepted formats (mp3/m4a/wav/ogg), plus the frame-aligned scheduling constraint. It also names the sibling that must run first (upload_audio), so an agent can place this tool in the workflow 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?

States a clear prerequisite ("The asset must already be uploaded") and points to upload_audio as the alternative entry point, plus how to derive the label from the upload's returned `name`. It stops short of naming update_audio_overlay/remove_audio_overlay as the alternatives for editing or deleting an existing overlay, so the when-not case is left implicit.

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

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

Annotations only say the tool is not read-only and not destructive; the description carries the full behavioral burden and does so richly. It discloses hold-eased opacity keyframes, active-line karaoke behavior, the always-wrapped 'captions' group, welding semantics with clip trim, and the return of element ids plus groupElementId. All of this goes well beyond the structured 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 earns its place: mode explanation, karaoke effect, styling, defaults, grouping, return value. It front-loads the core purpose and then increments detail in a logical order. No filler or repetition of schema content.

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

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

For a tool with 9 parameters, two modes, nested line objects, and welding behavior, the description covers defaults, frame semantics, group wrapping, return values, and the relationship to other tools like transcribe_clip. The existing output schema is mentioned and the return ids are explained. 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 parameters are well documented in the schema itself. The description adds extra semantics on top, including the 30fps frame-index convention, the default lower-third position, and the practical purpose of clip_element_id for spreading lines across split source clips. This is meaningful interpretive value beyond the schema.

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

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

The description opens with a specific verb-resource pair ('Build a caption track from pre-timed lines') and immediately clarifies the two modes. It is clearly distinct from sibling tools like add_text_layer, merge_caption_lines, and split_caption_line because it describes building a complete timed caption track with wrapping and styling.

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, including the provenance of input ('derived from transcribe_clip's word timings'), the default lower-third placement, and the caption-group wrapping behavior. It does not explicitly name alternative tools or say 'use this instead of X', but the detailed behavior makes the intended scenario obvious.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the mutation risk is known. The description adds valuable behavioral context: 'Add or overwrite' (idempotent overwrite semantics), 'adjacent keyframes crossfade stop-by-stop' (interpolation behavior), '30 fps; frame is 0-indexed' (timing convention), and the special background.canvas synonym. This goes beyond the schema and 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?

Four dense sentences with zero filler. The core action and target are front-loaded, followed by the special-case background synonym, value semantics, and timing convention. Every sentence earns its place and adds non-redundant 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?

The description covers the essential call semantics: what is mutated, the target format, the value type, interpolation behavior, and timing. The output schema exists, so return values don't need explanation. Minor gap: it doesn't mention whether the keyframe is inserted into an existing track or creates one, but the 'fill track' phrasing and overwrite semantics make this largely inferable.

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 6 parameters thoroughly, including the Fill object variants and easing enum. The description adds a few nuances (crossfade stop-by-stop, 0-indexed frame, background.canvas synonym) but mostly reinforces what the schema already says. 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 states a specific verb ('Add or overwrite'), a precise resource ('colour keyframe on a fill track'), and the target scope ('leaf (shapes.<id>, image.<id>, video.<id>, group.<id>)'). It clearly distinguishes itself from generic add_keyframe/add_keyframes siblings by specifying the fill track and color value 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 to use this tool: when targeting a fill track with a color/Fill value. It also clarifies the special 'background.canvas' synonym for the pinned is_background image_layer. However, it doesn't explicitly state when NOT to use it or name alternatives like set_layer_fill or remove_color_keyframe, so it stops short of full exclusion guidance.

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

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

Annotations (readOnlyHint=false, destructiveHint=false) already establish it as a non-destructive mutation. The description adds that the curve is 'editable' and explains arrowhead behavior, but it does not discuss side effects, reversibility, or interaction with existing content. Given annotation coverage, this is adequate but not extensive.

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

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

Two sentences, front-loaded with purpose and use case, then parameter details. No redundant or vague phrasing. 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?

The description covers endpoints, bend, color, stroke, arrowhead, and use case. The required projectId is described in the schema with context ('selects which existing project this call mutates'). An output schema exists (per context signals), so return format is not needed. It is reasonably complete for an add 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?

With 89% schema coverage, the baseline is 3, but the description adds meaningful clarifications: 'bend pushes the midpoint perpendicular (px, 0 = straight line, positive/negative curves either way)' and the default for arrow_head ('none|end|both (default end)'). It also clarifies units ('canvas pixels'), going beyond the schema 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 the tool draws an editable arrow/curved line, a stroked quadratic bezier with arrowhead. It specifies the verb (draw), resource (arrow/curved line), and even a concrete use case ('callout arrows'), distinguishing it from siblings like add_shape or add_text_layer.

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 provides a when-to-use context: 'Use this for callout arrows (e.g. swooping into a link).' This gives clear guidance on when to apply the tool. However, it does not mention alternatives or when not to use it, which would elevate it to 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?

Beyond the annotations' readOnlyHint=false and destructiveHint=false, the description discloses idempotency ('re-adding an existing entry is a no-op') and the normalization rule (scheme/port/path stripped to a bare lowercased hostname). It also adds the security-relevant detail that Morpha sends the allowlisted website no request, so an agent understands what granting embed access entails.

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 plus a documentation reference, with the primary purpose front-loaded. Each sentence earns its place: purpose, idempotency, normalization, and the no-request security note. The prose is slightly dense for a simple 2-param tool, which keeps it from a perfect score.

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

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

For a 2-param tool with 100% schema coverage, a true output schema, and annotations covering the mutation safety profile, the description covers everything an agent needs: purpose, idempotency, normalization, and access implications. The reference link provides an escape hatch for deeper questions, and return-value details are left to the output schema.

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

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

Schema description coverage is 100%, with both origin and projectId fully documented in the input schema, so the description carries no additional parameter burden. The description's normalization note mirrors — rather than extends — the schema's own origin field description. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb and resource: 'Add one hostname to the project's embed allowlist.' It distinguishes itself from the many sibling add_* tools (add_audio_overlay, add_caption_track, etc.) by naming its exact target, and the 'one hostname' phrasing separates it from set_embed_origins and remove_embed_origin. An agent can select it correctly without opening the schema.

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

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

The description gives clear context — this is an incremental, idempotent addition to the allowlist, explicitly scoped to a single hostname per call. It does not explicitly name alternatives like set_embed_origins for wholesale replacement or remove_embed_origin for removal, so exclusions are left implied rather than stated.

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

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

The description richly discloses behavior beyond annotations: it creates a fully detached copy with fresh ids, brings children with groups, carries image/clip/font bytes, preserves canvas position, and guarantees source deletions/changes never affect the copy. It also explains live-editor pickup behavior within seconds and the return value, giving the agent a complete mental model.

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 carries unique, necessary information: core operation, parameter mapping, copy semantics, prerequisites, live pickup, and return shape. It is front-loaded with the primary purpose and maintains a logical flow without repetition 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 tool with copy semantics, group behavior, detachment guarantees, and prerequisites, the description covers everything an agent needs to call it correctly: what ids to pass, what happens during the copy, what constraints exist, and what to expect in the response. An output schema exists, so return-value documentation is not a 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?

The schema already documents all three parameters with 100% coverage, so the baseline is 3. The description adds value by clarifying the roles of projectId (destination) versus sourceProjectId (home project), explicitly tying elementId to list_collection output, and reinforcing that fresh ids are generated.

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: adding an item from the user's Collection into a project as a self-contained copy. It clearly distinguishes this from sibling tools like add_to_collection, which moves items into a collection, and list_collection, which lists collection items.

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 invocation context: use list_collection to obtain sourceProjectId and elementId, and pass the destination projectId. It also states prerequisites (the element must be in the source project's collection and readable), though it does not explicitly contrast with alternatives like add_to_collection or remove_from_collection.

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

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

Annotations already cover readOnly=false, destructive=false, openWorld=false, so the bar is lower. The description still adds valuable behavior: the aspect-preserving sizing rule (passing both non-matching sides stretches the picture), and the auto-assigned fresh id when duplicating. It doesn't state permissions or what happens on an invalid/missing filename, but the sizing-stretch warning is exactly the kind of trap an agent 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?

Front-loaded with purpose and prerequisite, which is good. But the block/name/filename semantics are partially duplicated from the already-detailed schema descriptions, and the all-caps 'SIZE THE BOX TO THE PICTURE' plus repeated aspect explanation adds bulk. It's informative but not tightly trimmed.

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-param, nested-object, mutation tool with an output schema, the description covers the key traps: upload prerequisite, filename-vs-name mapping, aspect-based sizing, and duplication. The `block` default (persistent overlay vs bounded clip) is left entirely to the schema, but the output schema means return values needn't be explained. Mostly complete.

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

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

Schema coverage is 100%, so baseline is 3. The description nonetheless adds semantics beyond the schema: it maps the upload's returned `filename` to the stored id and `name` to the label, and clarifies that passing width alone derives the other side. The duplication-by-filename trick is a meaning-level addition not 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 ('Add an image layer') and distinguishes itself from siblings by explaining the upload prerequisite via upload_image versus reusing an existing filename to duplicate. An agent can tell this apart from add_shape, add_text_layer, or upload_image 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?

Explicitly names upload_image as the prerequisite and its two input modes, and gives the alternative path for duplicating an existing layer by reusing its filename. The 'usual call passes width alone' guidance, mirrored in the schema, adds a clear default behavior.

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 far beyond the annotations by disclosing overwrite behavior, override of static base values, absolute vs. offset coordinate spaces for leaves/groups, 30 fps timing, scale pivot behavior, and opacity range. This fully complements destructiveHint=true with concrete mutation semantics.

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

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

The description is dense but every sentence adds necessary semantic information, starting with the core action and then layering coordinate rules, group behavior, scale/opacity conventions, and the override caveat. There is no filler or redundant restatement of schema fields.

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

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

For a nuanced tool with curved, width, height, and group-specific behavior, the description is mostly rich but incomplete: it omits semantics for width, height, and curve keyframes, and never addresses when the specialized sibling keyframe tools should be preferred. An output schema exists, so return values need not be explained, but the property coverage gap remains.

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

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

With 83% schema coverage, the baseline is already good, and the description adds meaningful semantics for value and frame: canvas units, degrees, scale relative to 1, opacity 0..1, and fps. The main gap is that width, height, and curve property values are not semantically explained beyond the schema enum.

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

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

The description clearly identifies the action as adding or overwriting a keyframe on a layer's animation track, which is a specific verb and resource. However, it does not explicitly differentiate itself from sibling tools like add_color_keyframe or add_speed_keyframe, so it stops short of full sibling 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?

There is no explicit statement of when to use this tool versus specialized siblings such as add_color_keyframe, add_speed_keyframe, or set_keyframes_batch. The detailed coordinate semantics imply animation use, but the agent is left to infer routing between 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?

Annotations already flag mutating/destructive behavior, and the description adds useful side-effect context: it can fold set_track_loop into the same call and factors elementId/property out of the caller's loop. It does not spell out whether existing keyframes are replaced or appended, but that is not required once destructiveHint and output schema are present.

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 distinct jobs: purpose, use case, alternative. The purpose and key constraint are front-loaded, and the examples are compact and illustrative rather than 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 5-parameter mutation tool, the description plus rich schema, annotations, and output schema cover what the tool does, when to use it, and how it differs from the closest sibling. No critical calling decision is left unaddressed.

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

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

Schema coverage is high (80%) and already documents elementId, keyframes, projectId, and loop with enums/defaults. The description adds contextual meaning for elementId/property factoring and loop-mode folding, but it does not materially explain parameter formats beyond the schema, so the high-coverage 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 opens with a specific verb-plus-resource statement: 'Add many keyframes to ONE element's ONE property in a single call,' then narrows scope (per-layer tracks) and explicitly contrasts with set_keyframes_batch. This makes the tool unambiguous among the many add_* and keyframe 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?

It states the intended scenario ('idiomatic form when every layer in a multi-element animation gets its own track') and gives explicit alternative routing ('Use set_keyframes_batch instead when you need to mix elements/properties in one atomic call'). This is exactly the when/when-not guidance an agent needs.

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

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

Annotations only declare readOnlyHint=false and destructiveHint=false; the description adds real behavioral context beyond that — no page-count limit, the new page becomes active, its index is returned, and deep-copy mints a fresh id. These are operationally important facts an agent cannot get from the annotations.

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

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

Front-loads the core action and mode distinction, then follows with the conceptual model and follow-up tooling. It is somewhat dense and long, but nearly every sentence carries operational value; only the conceptual 'versions are pages' explanation could be trimmed marginally.

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

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

An output schema exists so return values needn't be detailed, yet the description still notes the index is returned. Combined with the mode explanations and sibling routing, an agent has everything needed to call this correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes further by explaining the two distinct modes of duplicate_index (deep-copy at a 0-based index vs blank append) and the canvas sizing of blank pages. It adds meaningful semantics over the schema's terse parameter text.

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

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

Starts with a specific verb+resource ('Append a page to the project') and immediately clarifies scope by noting it works on any project and converts single-page videos into multi-page ones. This clearly distinguishes it from siblings like create_project, duplicate_project, and reorder_pages.

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 splits behavior on the duplicate_index parameter: blank append without it, deep-copy with it. It also names follow-up siblings (select_page, describe_video) and export routes (editor Videos option, renderVideo with page), and clarifies that styles/hooks/languages/rows are pages of ONE project rather than separate projects.

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 cover safety (readOnlyHint=false, destructiveHint=false) but the description adds crucial beyond-schema behavior: new shapes stack ON TOP of every layer, default positioning in canvas centre when x/y/w/h omitted, and a warning when a shape covers the whole canvas naming the hidden layers. It doesn't mention permissions or the return payload, but that's a minor gap given the output schema exists.

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

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

Front-loaded with purpose, then kind enumeration, then behavioral warnings. The 38-item kind list is long but serves the required enum and reinforces vector-not-image intent, so it earns its place. Slightly dense but efficient.

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

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

Given 8 params, nested block object, an output schema, and read-only annotations, the description supplies the layer-stacking, default-position, and background-alternative context needed to call correctly. Missing only minor details like what the response returns (covered by output schema) and block-timing guidance beyond the schema.

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

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

Schema description coverage is only 38%, so the description has to compensate, and it does for the most ambiguous params: it explains kind values (redundantly with the enum but emphasizes native-vector intent) and the default position behavior for omitted x/y/w/h. It adds no detail on color format beyond the schema or on block timing, leaving a partial gap.

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

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

States a specific verb+resource ('Add a shape layer') and immediately enumerates the exact primitive kinds the kind parameter accepts, distinguishing the tool from add_image_layer by insisting on native vectors. An agent can tell it apart from siblings 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?

Explicitly names the alternatives and when to use them: 'never substitute an image layer', 'for a background colour or gradient use set_layer_fill on "background.canvas"', and 'to place a shape behind other layers follow with reorder_layer'. This is textbook when/when-not/alternatives routing.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the mutation is known. The description adds valuable behavioral context: the curve is anchored to the clip, moving the clip carries the ramp and never changes duration, and the ramp multiplies the layer's constant speed. It also explains the derived timeline length. This goes beyond the annotations.

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

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

The description is well-structured and front-loaded with the core action. Every sentence adds value: the overwrite behavior, the frame constraint, the anchoring behavior, the alternative tool, and the rate semantics. No fluff 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?

Given the output schema exists and annotations cover the destructive nature, the description is complete. It covers the key behavioral nuances (anchoring, duration derivation, rate range, frame constraint) that an agent needs to invoke the tool correctly. The alternative tool is named, and the mutation target is clear.

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 parameters. The description adds meaning by explaining the relationship between frame and the clip's timeline_start_frame, and how rate values map to real-time/half-speed/double-speed. It also clarifies that the curve is anchored to the clip, which is not in the schema.

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

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

The description clearly states the tool's function: 'Add or overwrite a speed-ramp (time-remap) keyframe on a video layer' with a specific rate that changes over the clip. It distinguishes itself from set_clip_speed for constant speed, and from sibling tools like add_keyframe and remove_speed_keyframe by specifying the speed-ramp context.

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 vs alternatives: 'For a constant slower/faster clip use set_clip_speed instead.' It also provides constraints like frame must sit on the clip and rate range, giving clear context for when this tool 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?

Even though annotations already declare readOnlyHint=false and destructiveHint=false, the description adds substantial behavioral context beyond them: the returned values (layer id, element id, text_box, fits, and an overflow warning naming a fitting text_size), the block/keyframe sampling semantics, curve clamping (±135, single-line only), and the caveat that decorations are not rendered on curved text. That is rich disclosure for a mutating tool.

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

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

The purpose is front-loaded in the first clause and the densest material (autofit modes, block semantics, return values) comes later, so an agent can stop early. It is a long, single-paragraph block and repeats a few schema details, which keeps it just below the top score, but for a 23-parameter tool most sentences carry real 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?

Given the complexity (23 params, nested objects, enums) and the presence of an output schema, the description covers what it must: purpose, defaults, the block/always-present decision, autofit trade-offs, curve behavior, and even a summary of the return payload. Nothing an agent needs in order to call this correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description largely restates what the schema already documents (defaults for x/y/width/height/font_family, the outline and shadow params, the derivation rule for text_size) rather than adding syntax or format detail the schema lacks. It does not materially compensate for anything, so the baseline stands.

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

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

The opening sentence gives a specific verb+resource ('Create a new text layer') and immediately characterizes what kind of object it produces ('a first-class leaf that animates, groups, and z-orders exactly like an image or shape'). This cleanly separates it from the other add_* leaf tools such as add_image_layer and add_shape, so an agent can identify 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?

The description gives genuine context cues: it says the default (no `block`) is 'what an agent-placed watermark / lower-third almost always wants' and enumerates when each `text_autofit` mode is appropriate. It does not, however, explicitly route the agent against alternatives like add_caption_track or set_layer_text, so it stops just short of the 5 anchor.

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

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

Annotations only provide readOnlyHint=false and destructiveHint=false; the description carries the full burden of behavioral disclosure. It explains that adding copies the entire subtree and asset bytes, making copies immutable, and that editing/deleting the source won't affect placed copies. It also notes that teammates can access the collection if the project is in a workspace. This is rich behavioral context 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?

The description is front-loaded with the core purpose, then systematically explains input types, side effects (immutability), team sharing, and a prerequisite. Every sentence adds unique value—no filler. Though lengthy, it is appropriately sized for the tool's complexity and reads 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?

The description covers all necessary aspects: what it does, what inputs are valid, what happens to the element, how copies behave, applicability to solo projects, and a naming prerequisite. It also references related tools (list_collection, add_from_collection). With an output schema present, return details are not needed. Nothing essential is missing for an agent to invoke this correctly.

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

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

Schema coverage is 100%, so both parameters are already documented. The description adds value beyond the schema by detailing what elementId can accept (leaf or group ids with examples like lower-third, logo sting) and emphasizes naming before adding. This goes beyond the schema's generic description, though projectId is not elaborated beyond the schema.

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

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

The description clearly states the verb ('Add') and resource ('layer to the user's reusable Collection'). It distinguishes from siblings like add_from_collection (which places a copy into another project) and list_collection (which lists the collection). The explanation of leaf vs. group ids further clarifies scope, 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 explicitly tells when to use this tool (to add a layer to the reusable collection) and points to the alternative add_from_collection for placing a copy elsewhere. It also provides a prerequisite (rename the layer first) and clarifies applicability to solo projects, giving the 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?

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false), so the bar is lower. The description adds real context beyond that: the upload prerequisite, the shape of the upload return ({ filename, name }), and that the editor auto-assigns a fresh id on duplication. It does not describe failure modes (e.g. what happens with an invalid clip), keeping it from a 5.

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

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

Front-loads the action, then prerequisite, then the parameter mapping, then the duplication shortcut. Each sentence earns its place, though the clip/name mapping is somewhat dense relative to what the schema already 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?

With an output schema present, return values need not be explained, and the prerequisite plus id semantics are covered. The main remaining gap is the absence of any failure/validation behavior, which is minor for this create operation.

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 each parameter, including that `clip` is a stored filename and `name` is the label. The description's mapping of the upload's { filename, name } onto `clip`/`name` largely restates that, so the baseline 3 applies.

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

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

States a specific verb and resource ('Add a video layer') that is immediately distinguishable from the sibling add_image_layer, add_text_layer, and add_audio_overlay. 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?

Gives a clear prerequisite ('The clip must already be uploaded; clips are uploaded in the MorphaReels editor') and a specific alternative path ('To duplicate an existing layer, reuse its clip filename'). It does not explicitly name sibling tools or state when-not to use this tool, but the context is strong.

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

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

Annotations already convey that the tool is destructive and mutating; the description adds no behavioral detail beyond that. It does not disclose what gets overwritten, such as existing keyframes or animation settings, nor does it mention any prerequisites or side effects.

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

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

A single, front-loaded sentence states the essence of the tool with no filler or repetition. It earns its place entirely, even though other dimensions lack content.

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

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

Combined with the schema's descriptions for projectId and startFrame, the destructive annotation, and the self-explanatory preset enum, the agent probably can invoke the tool correctly. However, the description remains thin around parameter semantics and the exact effect on the layer's existing animation.

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

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

With 50% schema description coverage, the description should compensate for undocumented parameters, but it does not. It gives no meaning to elementId or the preset enum values, and the only indirect hint is that the target is a 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?

The description clearly identifies the operation (apply), the resource (a layer), and the kind of input (a canned animation preset). It does not explicitly distinguish itself from the sibling apply_preset_stagger, but the core purpose 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?

No when-to-use or when-not-to-use guidance is provided. The description does not point to alternatives like apply_preset_stagger or fade_layer, nor does it explain when a plain preset is appropriate versus a custom animation or staggered application.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true. The description adds the startFrame calculation and ordering semantics, which is useful context, but it does not disclose specific side effects beyond what annotations carry (e.g., whether existing animations are overwritten or whether it 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?

Three sentences with no filler: the main purpose is front-loaded, followed by use cases, then the exact calculation and ordering instruction. 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?

The tool has an output schema and clear annotations, so the description needn't cover return values. It explains the core behavior, formula, and ordering, and distinguishes from apply_preset. Minor gaps like edge cases (negative stagger) or prerequisites are not critical 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 80%, so the baseline is 3. The description adds meaning beyond the schema by explaining the relationship between startFrame, stagger, and elementIds with the formula `startFrame + i * stagger` and the ordering requirement, which is not present in the schema.

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

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

The description states a specific verb ('Apply'), resource ('the same preset to a LIST of layers'), and the distinguishing feature (per-element startFrame offset). It explicitly contrasts with apply_preset and gives concrete use cases, so an agent can immediately tell it apart 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?

It clearly names apply_preset as the alternative and explains when to use this tool ('one call instead of N apply_preset calls', 'For diagonal pop-in grids...'). It lacks an explicit when-not clause, but the context is strong enough that an agent can infer the boundary.

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 readOnly/non-destructive annotations by disclosing that processing never runs on the server, that the preview proxy is mandatory and auto-built by the editor on project open, the 'cancelled' transcript persistence behavior, and that audio_split never gates `processed`. These are non-obvious behavioral traits an agent cannot infer from 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?

Purpose and usage are front-loaded effectively, but the long prose walkthrough of the return object and its enum values is largely redundant given an output schema exists. The 'cancelled'/'audio_split' notes earn their place; the inline response shape does not.

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 full behavioral picture for a read-only status probe and explains the step-state semantics thoroughly. It is more complete than needed since the return format is duplicated from the output schema, but nothing an agent needs 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 both parameters including the 'omit clip to report every video clip' semantics. The description restates that omission behavior rather than adding 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 specific verb (report) and resource (clip processing status), and enumerates exactly what the pipeline covers: proxy build, audio split, transcription, OCR. An agent can immediately distinguish this read-only status probe from the mutation siblings like transcribe_clip or detect_text_regions.

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 names the downstream alternatives it gates: 'Use it to know whether transcribe_clip / detect_text_regions will return data.' It also states the precondition that processing is browser-side, not server-side, so the agent knows this is the only way to learn the state.

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

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

Annotations only declare it is not read-only and not destructive; the description adds substantial context beyond that – what gets copied on clone (JSON, assets, clips), workspace inheritance, the edit-role requirement, the hard failure for view-only sources, and the editor not auto-refreshing. That is exactly the kind of behavioral detail an agent cannot infer from 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?

Front-loaded with the core action and return value, but the single block mixes creation, cloning, workspace rules, and page-vs-project guidance; it is dense and could be broken into clearer sentences. Every sentence is relevant, but the structure is 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?

For a mutation tool with an output schema and rich sibling set, the description covers default behavior, override paths, failure modes, and disambiguation from related tools. Nothing an agent needs in order to call it correctly appears to be missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description nevertheless adds meaning – that name is user-facing, that fromProjectId triggers cloning with specific copy semantics, and the three-way behavior of workspaceId (omit=follow source, id=place, null=personal). It does not add syntax beyond the schema but reinforces the operational consequences of each 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?

States a specific verb and resource ('Create a new project') and immediately clarifies the returned id is server-minted and opaque. It explicitly contrasts with sibling duplicate_project and with add_page/duplicate_index, so an agent can tell this apart from cloning or page-level 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?

Gives explicit when/when-not conditions: blank project by default, pass fromProjectId ONLY to clone, pass workspaceId or null to control placement, and use add_page/duplicate_index for versions of one video. It names the alternatives (duplicate_project, add_page, duplicate_index) and the failure mode when cloning a view-only workspace project.

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 annotations: discloses the return shape { id, name, role, memberCount }, the ownership side effect, the email-account requirement (keyless identities cannot create), and the conflict-on-duplicate-name behavior. Annotations only state it's non-read-only and non-destructive.

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 is front-loaded, return shape is early, and each sentence carries distinct information (what it does, when to use, follow-on tools, auth requirement, conflict behavior). Dense but well-organized; only the parenthetical is slightly expendable.

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 return values, side effects, prerequisites (email account), error behavior (conflict), and integration points with sibling tools. With an output schema present, the return-value sentence is still useful for agent planning; nothing material is missing.

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

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

Schema coverage is 100% and the single `name` parameter is already documented (verbatim in switcher). The description adds the uniqueness constraint (duplicate name → conflict), which meaningfully extends 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?

Specific verb+resource ("Create a new workspace") with a parenthetical clarifying what a workspace is and stating the caller becomes owner. Clearly distinguishes from sibling list_workspaces, rename_workspace, and move_project_to_workspace.

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

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

Explicitly says when to use it ("when the user wants a new place to group projects") and names the follow-on tools (move_project_to_workspace, create_project) that consume the created workspace. Also explains the conflict-refusal case for repeated requests.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds substantial behavioral context: it shifts every keyframe/marker/audio overlay/loop region/start_at, splits straddling video layers, truncates interior audio overlays, refuses on speed-ramp layers, shrinks composition length, and clamps endFrame. This goes far beyond the annotations and is critical for a destructive operation.

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

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

The description is dense and front-loaded with the core operation, then details consequences and refusals. It is long but every sentence adds a distinct behavioral fact. It could be slightly more concise, but the complexity of the operation justifies the length.

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

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

Given the complexity of a ripple delete with source-aware video layers, speed ramps, audio overlays, and composition length changes, the description covers all the edge cases an agent needs to predict the outcome. The output schema exists, so return values don't need explanation. Nothing critical 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 adds meaning by explaining the frame semantics (0-indexed, 30 fps, exclusive endFrame, clamped to composition length) and the delta calculation, which is not fully in the schema. It doesn't add per-parameter detail beyond that, but the schema already covers the basics.

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 ('Ripple-delete'), the resource ('a time window [startFrame, endFrame)'), and the exact effect ('remove that span and pull all later content earlier by delta'). It clearly distinguishes this from other timeline operations like set_video_clip or move_band, and the title/description align.

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 it (ripple delete / close gap) and when NOT to: it 'REFUSES to cut across a video layer that carries speed-ramp keyframes' and instructs to 'remove them, or cut outside that layer's span, first.' This is explicit exclusion guidance beyond what the schema provides.

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 the tool as destructive, and the description adds meaningful edge-case behavior beyond that: out-of-range failure, the one-page minimum, and exactly how active_index changes when the active page is deleted. This is the kind of behavioral context that agents need.

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

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

Two sentences, front-loaded with the primary action, then the edge cases. Every sentence carries necessary information and there is no fluff.

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

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

With a destructive annotation, a full output schema, and 100% parameter coverage, the description adds exactly what was missing: the project invariant and active-index fallback behavior. Nothing an agent needs to call this correctly is absent.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema. The description reinforces that `index` is the page position, but it doesn't add meaningful semantics beyond the schema.

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

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

The description uses a precise verb-resource pair ('Remove the page at `index`') and immediately distinguishes itself from related operations like add_page, reorder_pages, and delete_project. The scope (a single page within a project) 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?

It clearly states the context in which the call succeeds and the invariant that limits it (a project must keep at least one page). It does not explicitly name alternatives, but the failure conditions give enough guidance to avoid misuse.

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 destructiveHint/readOnlyHint annotations by disclosing reversibility and its 30-day limit, what is ultimately destroyed (saved versions, uploaded images, clips), the auth roles accepted, the opaque not-found response for unauthorized callers, and the last-project edge case. This is unusually rich behavioral context for a mutation tool.

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

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

Front-loads the core action in the first clause, then layers restore window, return shape, auth, and edge case in descending order of importance. Every sentence carries distinct information 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 one-parameter destructive tool, the description covers reversibility, timing, authorization, error behavior, edge cases, and return shape. Even though an output schema exists and return values needn't be restated, the inclusion is accurate and harmless; nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100% for the single projectId parameter, so the schema already carries the parameter meaning and the baseline of 3 applies. The description adds no syntax, format, or ID-source guidance beyond what the schema provides.

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

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

States a specific verb and resource with the exact semantics of the operation: 'Move a project to Recently deleted,' which immediately signals a reversible soft-delete rather than a hard delete. This distinguishes it from siblings like delete_version and restore_project without the agent needing to open any schema.

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

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

Explicitly names the counterpart tool (restore_project) and the 30-day window in which it applies, and clarifies that permanent deletion is the person's own step on their projects page — 'no tool does it' — closing off a plausible alternative the agent might otherwise hunt for. It also enumerates the exact access conditions required.

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

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

Annotations already mark destructiveHint=true and readOnlyHint=false, so the safety profile is known. The description adds substantial behavioral context beyond that: it is permanent, accepts both UUID and v<N>, the v<N> sequence keeps gaps causing external snippets to fail, and it is idempotent with a no-op for non-existent versions. This is exactly the kind of side-effect and post-condition disclosure that agents need.

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 minimal waste. It front-loads the primary purpose, then provides the two most important operational details (accepted identifiers and side effects) in compact, well-structured sentences. 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 delete operation with two parameters, destructive annotations, and an output schema present, the description is complete. It covers what is deleted, how to identify it, the irreversible side effect, the v<N> gap behavior, and idempotency. There is no missing information an agent would need to call 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 baseline is 3. The description adds value beyond the schema by explaining the consequences of using v<N> shorthand (gaps remain, external references break) and by clarifying idempotent behavior for non-existent versions. This is meaningful semantic enrichment even though the schema already documents both 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 clearly states the tool's action: 'Permanently delete one saved version (bookmark or auto-snapshot).' It uses a specific verb and resource, and distinguishes this from sibling tools like delete_page, delete_project, and restore_version by naming the target as a saved version. The mention of UUID and v<N> shorthand further clarifies the exact scope.

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

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

The description gives clear context for use: it is for permanently deleting a saved version, which implies the appropriate situation. However, it does not explicitly name alternatives such as restore_version or list_versions for comparison, nor does it state when NOT to use this tool. It stops short of the explicit 'use X instead' guidance seen in top-tier examples.

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

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

Annotations already declare readOnly/destructive=false, but the description adds substantial context beyond them: it discloses what is deliberately excluded (keyframe values and styles, because they are unbounded), the semantics of platform_safe_area including the null case, that the tree describes the ACTIVE page, and the shape of the pages block. This is exactly the extra behavioral context the annotations cannot carry.

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

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

Front-loaded with the core purpose and the primary alternative, and nearly every clause carries information an agent needs. It is, however, a single dense paragraph with heavy parenthetical nesting, which slightly hurts scannability for such a long description.

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

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

Even though an output schema exists (so return values need not be explained), the description still describes the returned structure well enough to set expectations, and it covers scope (active page), exclusions, and next steps. 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?

There is one parameter and schema coverage is 100%, so the schema already fully documents projectId. The description adds no syntax or format detail for the parameter itself (only notes that content tools target the active page). Baseline 3 is appropriate when the schema does the work.

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

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

Names a specific verb+resource ('Structural OVERVIEW of the composition') and enumerates exactly what the overview contains: canvas size, duration, platform_safe_area, backdrop, and a z-ordered layer tree with elementId, type, geometry, fits, and animated properties. It explicitly draws the boundary against inspect_layers, so an agent can distinguish it from siblings 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 routing: 'Start here, then call inspect_layers([elementId, …]) for full detail on the specific layers you'll change,' plus a negative instruction ('Don't guess keyframe/style values from this overview'). It also explains the multi-page case and points to select_page / add_page / delete_page / reorder_pages for page management.

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 destructiveHint=false)Skip; the description adds substantial behavioral context: 0.3s sampling at upload, one-time OCR for images, R2 caching, status values, source-pixel coordinate space, and confidence range. This goes well beyond what annotations alone 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 dense but every sentence carries distinct information: scope, input selection, processing cadence, caching, return shape, coordinate space, and an explicit use case. It is front-loaded with purpose and avoids 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 read-only analysis tool with a clear output shape, the description covers all call-relevant concerns: input selection, coordinate system, confidence semantics, and a practical application. 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% and the schema already documents clip, image, and projectId. The description enriches this by clarifying the mutual-exclusion rule, what 'clip' and 'image' filenames refer to, how each source is processed, and that image results have a single frame. That is meaningful semantic value beyond the schema.

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

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

The description opens with a precise verb and resource: 'Return the OCR text regions detected in a clip's video frames OR a still image asset.' It clearly distinguishes itself from transcribe_clip and other media-analysis tools by focusing on text-region detection for graphics collision avoidance.

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 concrete usage context: 'Use to know where titles / subtitles / lower-thirds are baked into the video or image so the Morpha title + intro graphics can be positioned to not collide.' It also explains the clip-vs-image choice with 'not both.' It does not explicitly name alternatives or state when not to use the tool, 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?

Discloses the exact per-step math (i·(dx,dy), i·d_rotation, d_scale^i), states that 'Styles are copied', and suggests a follow-up animation workflow. These details go well beyond the annotations, which only indicate a non-read-only, non-destructive mutation.

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 efficient: the first sentence defines the operation, the second gives canonical use cases, and the third closes with workflow advice. Every sentence earns its place with no filler.

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

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

For a seven-parameter composition primitive, this is complete: it defines legal element ids, the transform math, examples, and what happens to styles, while the output schema covers return values. The annotations cover the mutation profile, so no safety information is missing.

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

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

Schema coverage is 100%, so the schema already documents every parameter. The description adds relational meaning by explaining how parameters accumulate across copies and by naming the d_scale^i formula, going just beyond the 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?

States a specific verb ('clone') and resource ('leaf (image.<id> / video.<id> / shapes.<id> / text.<id>)') and includes an exact cumulative transform formula. The 'Composition primitive' framing separates it from add_* layer tools and duplicate_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 clear usage context: 'One call instead of dozens' plus concrete patterns (circle of stars, row of chevrons, fractal, staggered grid). It doesn't explicitly name alternatives or say when not to use it, but the examples strongly imply copy-with-transform scenarios.

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

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

Beyond the annotations (which only declare non-read-only, non-destructive, non-open-world), it discloses the workspace inheritance rule, the edit-role prerequisite, the hard-failure instead of silent fallback, the returned workspaceId, and that the user's editor won't auto-refresh. These are substantive side effects and failure modes not present in 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?

Front-loads the core purpose and the copy contents before moving into the WORKSPACE block. It is long, but the density is largely justified by the non-obvious workspace-routing rules; a few clauses (e.g. the picker/reload note) could be tightened.

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

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

An output schema exists, yet the description still calls out the salient returned field (workspaceId) that resolves the ambiguous destination. Combined with the failure semantics and defaults, 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 schema already documents name, projectId, and workspaceId. The description adds meaning beyond it: the edit-capable role requirement for workspaceId, the null-forces-personal semantics, and the edge case of a project shared from a workspace the user isn't a member of.

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 ('Duplicate an existing project into a brand-new one') and enumerates exactly what is copied (layers, animations, styles, uploaded assets, clips). It also explicitly distinguishes itself from sibling concepts by clarifying that versions/options of one video are pages of ONE project (add_page, duplicate_index), not separate projects.

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 and when-not guidance: it names list_workspaces as the source for workspaceId, explains the default workspace-following behavior, and states the failure case (view-only source) with the two remedies. It also routes the agent away from duplicating pages via add_page/duplicate_index.

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

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

Goes well beyond the annotations (readOnly=false, destructive=false) by disclosing the internal mechanics (layers inlined, re-keyed to fresh ids, pinned to an immutable source version) and the crucial non-propagation guarantee: edits to inner layers affect only THIS video. That is exactly the kind of behavioral 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?

Front-loads the core action in the first sentence and keeps each subsequent sentence purposeful (mechanism, params, local-edit semantics, identification cue). It is slightly dense at six sentences, but no sentence is redundant with the schema or annotations.

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

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

For a mutating tool with an output schema (return values needn't be explained), the description covers purpose, mechanics, parameter roles, side-effect scope, and a distinguishing identification cue via describe_video. Nothing an agent needs in order 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 conceptual framing that the schema lacks: it explains the host-vs-source relationship (projectId = the project being mutated, source_morpha_id = the project being embedded) and that version is an optional label. This clarifies how the parameters relate rather than merely restating them.

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

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

Names a specific verb+resource (embed another project as a version-pinned band) and immediately describes the resulting artifact (inlined layers, collapsible group, re-keyed ids). It also explicitly distinguishes the produced band from a plain group ('describe_video marks an embedded band with morpha:true'), so an agent can tell it apart from group_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?

Gives clear operational context: which id to pass (source_morpha_id), the optional version label, and the re-pin path via the editor Inspector. However, it does not name or exclude the potentially confusable siblings (add_embed_origin, set_embed_origins), leaving the agent to infer when embed vs. embed-origin 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?

The annotations already declare destructiveHint=true and readOnlyHint=false, so the description doesn't need to re-state that it mutates the project. The description adds a key detail: it performs the fade in one call, implying it replaces manual multi-step keyframing. However, it doesn't explain what happens to existing keyframes or opacity settings, which is a gap. Since annotations cover the safety profile, a 3 is appropriate.

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, concise sentence that communicates the action and scope efficiently. It is front-loaded with the main purpose, uses no filler words, and is easy to parse. This is an excellent example of minimal, high-value prose.

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

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

The tool has 6 required parameters and an output schema, so the description doesn't need to explain return values. However, it doesn't clarify the exact behavior of the fade (e.g., interpolation type, whether existing keyframes are overridden). For a mutation tool with destructiveHint=true, this lack of behavioral detail slightly compromises completeness. The core purpose is clear, but additional context on effects would improve it.

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

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

Schema description coverage is 50%: two parameters (fromOpacity, toOpacity) have descriptions ('0..1.'), and projectId has a description. The tool description does not explain the meaning of fromFrame/toFrame or elementId further, but the schema likely has enough context via property names. The description adds no new parameter semantics beyond the schema, so a baseline of 3 is correct given the coverage.

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

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

The description states a clear verb ('Fade') and specific resource ('a layer's opacity') plus the scope ('between two frames in one call'). It clearly distinguishes from siblings like 'set_layer_visible' or 'add_keyframe' by focusing on a single operation. This is precise 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?

The description implies when to use this tool (when you need to fade opacity over frames), but it doesn't explicitly state when not to use it or mention alternatives like 'add_keyframe' for more complex animations. There is no discussion of prerequisites or edge cases, so the guidance is minimal but not misleading.

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

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

Beyond the annotations (readOnlyHint false, destructiveHint true), the description discloses the destructive clearing action, the auto-fit behavior, the 1-second floor, and a significant edge case where it can under-fit in headless mode and later self-correct. This adds valuable behavioral context not present in the annotations.

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

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

The description is efficient and front-loaded with the core purpose. The note about headless under-fitting is long but necessary and clearly separated. Overall it is well-structured without unnecessary 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?

The description covers the primary behavior, the inverse relationship with set_duration, and a critical edge case that affects correctness. Since an output schema exists, return value details are not required. For a single-parameter mutation tool, this is complete and actionable.

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 provides a thorough description of projectId (opaque v4 UUID, from list_projects/create_project, selects project to mutate). The tool description does not add any additional parameter details, but with 100% schema coverage, the baseline is 3. No extra value is needed.

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: 'Clear an authored composition length and return to AUTO-FIT', specifying the resource (composition length) and the behavior (tracks furthest content with a 1-second floor). It also identifies itself as the inverse of set_duration, which distinguishes it from sibling tools like set_duration.

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 names set_duration as the inverse, providing a clear alternative and implying when to use this tool (to revert to auto-fit). It also gives a specific condition (headless with null source_out_frame) where under-fitting may occur, helping the agent decide when to invoke it and what to expect.

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 discloses the destructive behavior (clip is cut), matches the destructiveHint annotation, and explains the resulting image layer is editable ('resize, split, move or delete it like any other layer'). It also clarifies the output field 'frozenSourceFrame' differs from 'frame' on retimed clips, adding value beyond annotations. No contradictions with the annotations.

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

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

The description is thorough but not bloated. It front-loads the core action, then explains the mechanism, the layer nature, the prerequisite, the output field, and the constraint. Each sentence adds value, though it's slightly longer than minimal. It earns a 4 for being appropriately detailed without 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 destructive tool with 5 parameters and an output schema, the description covers all critical aspects: the timeline effect, the layer editability, the image upload prerequisite, the default holdFrames, the output semantics, and the frame constraint. Nothing essential is missing 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%, and the schema already describes each parameter's meaning (frame, image, elementId, projectId, holdFrames). The description adds context (e.g., the still is an image layer, holdFrames default matches), but these are largely restatements. It doesn't add significant new semantics beyond the schema, 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?

The description clearly states the action: 'Freeze the picture at a frame: the clip is CUT there and a still of that frame is inserted between the halves.' It specifies the resource (clip) and the effect (frame hold), and distinguishes it from other layer operations by describing the unique NLE behavior. No sibling tool does this, so it's 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 explains when to use it ('This is how you hold a moment — play, freeze, continue') and provides a clear prerequisite: the PNG must be uploaded first ('rendering one needs a browser, so capture and upload it first'). It doesn't mention alternatives, but there is no obvious competing tool in the sibling list, so this is sufficient.

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 readOnlyHint=false and destructiveHint=true but say nothing about mechanics; the description supplies the non-obvious behavior: transforms compose onto descendants, pivot rotates/scales at (pivotX, pivotY) seeded to the child centroid, and group x/y track values are translation offsets around that pivot with no static body. This is substantive disclosure well beyond what the annotations carry and does not contradict them.

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

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

The core action is front-loaded in the first clause, and the paragraph is dense but mostly earns its length through pivot and composition semantics. The four illustrative examples and some re-explanation of the parent constraint are slightly redundant and could be trimmed.

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 structural mutation with an output schema present (so return values need not be explained), the description covers the action, the required precondition, pivot seeding, transform composition, and translation semantics. 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 description coverage is 100%, so elementIds and projectId are already documented, and the description's parent-sharing constraint restates the schema text. It adds mild meaning for `name` (the label of the new panel row) but no format or edge-case 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 ('Wrap sibling elements in a new group') and immediately clarifies the observable result in the Layers panel, distinguishing it from unrelated mutations. The parenthetical examples (butterfly, icon, card, lower-third) make the operation concrete without 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 provides a real precondition (all elementIds must share the same parent, root or one existing group), which is genuine usage context. However, it never names alternatives such as ungroup_layers or set_group_parent, nor states when a group should be preferred over another structural operation, leaving usage implied rather than directed.

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 destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context: it returns complete records with animation tracks, keyframes, extrapolation modes, and style, and it warns against pulling the whole project. It doesn't describe pagination or response size limits, but the output schema exists and the read-only nature is clear. A 4 is appropriate because the description adds value beyond annotations without contradicting them.

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

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

The description is two sentences with zero waste. The first sentence front-loads the core purpose and return contents; the second gives the workflow guidance. Every clause earns its place, and the structure is easy to scan.

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

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

For a read-only inspection tool with a full output schema, 100% parameter coverage, and annotations covering safety, the description is complete. It tells the agent what to pass, where to get it, what to expect back, and how to use it efficiently. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description adds value by explaining the source of elementIds (from describe_video's tree) and the intended usage pattern (only for layers about to mutate). It also clarifies the element id format implicitly by referencing describe_video. This goes beyond the schema's basic descriptions, so a 4 is warranted.

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 ('inspect'), a resource ('layers'), and the exact scope: per-element drill-in returning complete records including fields, animation tracks, keyframes, extrapolation modes, and style. It explicitly positions itself as 'the open this layer half of the browser,' distinguishing it from describe_video and other sibling tools. An agent can immediately tell 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 explicit when-to-use guidance: pass elementIds read from describe_video, and pull detail only for the handful of layers you're about to mutate, not the whole project. It also implies the alternative (describe_video for the overview) and the workflow relationship. This is clear, actionable usage guidance.

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

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

Annotations already mark it read-only and non-destructive, and the description adds meaningful behavioral detail: the exact return shape, the semantics of personal vs. team scope, the fact that items are self-contained copies when reused, solo-account behavior, and that it takes no arguments. This goes well beyond what the annotations alone 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?

The description is dense but every sentence adds value: what a Collection is, what the response contains, how scope works, how to present it to the user, and how the results connect to add_from_collection. It is front-loaded with the core purpose and avoids filler.

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

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

Given there are no parameters and an output schema is present, the description provides all the operational context an agent needs: return item fields, scope meaning, downstream usage, and solo-account behavior. Nothing necessary for correct invocation is missing.

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

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

There are zero parameters, so the input schema is already complete. The description reinforces this by stating "takes no arguments," which is useful confirmation for an agent. Baseline for 0 params is 4, and the description does not need to do more.

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 the user's reusable Collection," and clarifies exactly what a Collection contains with concrete examples (lower-thirds, logo stings, brand intros). It also distinguishes itself from related collection tools by saying the returned identifiers feed add_from_collection, so an agent can tell list_collection apart from add_to_collection and remove_from_collection.

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 this tool is relevant: when the user wants to view reusable collection items, especially as a precursor to add_from_collection. It does not explicitly state when-not-to-use or name alternative tools like add_to_collection/remove_from_collection, so it stops short of 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?

Even with readOnlyHint=true, the description adds meaningful behavior: the aggregated multi-source listing, the 'custom' source surface, the limit/max behavior, and the guarantee that returned families work directly in font_family without manual mapping. This goes well beyond the annotation and tells the agent exactly what to expect.

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 with no filler: the scope is front-loaded, followed by use case, return format, filtering options, and a critical integration note. Every sentence earns its place and the structure is ideal for scanning.

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

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

Given its simplicity and the presence of annotations, the description covers everything needed to invoke it correctly: the exact return shape, the four parameters (all schema-documented), the filter/limit behavior, and the downstream integration with the text tools. Nothing an agent needs is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description mostly restates the schema's q/source/limit semantics, though it does add a useful note about 'custom' returning only uploaded faces and the integration guarantee. There is no significant added meaning beyond the schema.

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

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

The description names a specific verb ('List'), a concrete resource ('available font families'), and the full scope (every source plus custom uploads), which clearly distinguishes it from the mutation tools around it such as set_layer_text and add_text_layer. The inclusion of the return shape and the mention of the font sources removes any ambiguity about 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 explicitly says to use this tool before set_layer_text/add_text_layer when you don't know what to pick, which is strong contextual guidance. It doesn't state exclusions or when not to use it, but for a read-only discovery tool the context is sufficient.

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 destructiveHint=false, so safety is covered. The description adds scoping behavior beyond that: personal projects are returned by default, workspaceId switches to workspace (including teammates') projects and adds ownerEmail, and name falls back to 'Untitled'. It stops short of describing pagination or volume limits.

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

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

Front-loads what the tool returns before branching into the workspace case, and every sentence carries information. It is slightly dense with three field explanations plus two usage clauses, but nothing is wasted.

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

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

With an output schema present, return structure needn't be re-described, and the description still supplies the field semantics, the default-vs-workspace behavior, and the triggering scenario. 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%, so the baseline is 3, and the description adds real meaning: the default (omit for personal projects), the membership requirement, that workspace results include teammates', and that each gains an ownerEmail. This exceeds what the single schema field states.

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

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

States a specific verb+resource (list projects) and immediately clarifies the return shape and the meaning of each field (id maps to projectId, name is the editor label, editorUrl opens the project). It distinguishes the default personal-project listing from the workspace listing, so an agent can tell it apart from list_workspaces and the create/rename/delete_project 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?

Explicitly names the trigger ('what projects do I have?' or when no project is named but one must be operated on) and points to list_workspaces as the source of workspaceId. Both when-to-use and the alternative path are covered without 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?

Goes well beyond the readOnly/non-destructive annotations by disclosing the retention rule (purgeAt is epoch ms, 30 days after deletion), what deletedBy encodes (you/person/agent with label semantics), and what canEdit gates. This is exactly the behavioral context an agent needs to decide whether restoration is still possible.

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 what is listed, then the purge/restore constraint, then the field semantics, then the default scoping — a sensible order. Slightly dense with backtick-heavy field explanations, but nearly every clause carries information the agent can act on.

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?

Even though an output schema exists, the description usefully explains the retention/restore path and default scoping, leaving no gap an agent would need to guess at for a zero-required-parameter list 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% and the single parameter's description already covers the from-list_workspaces sourcing, the scope change, and the membership requirement. The description restates that behavior rather than adding new meaning, so the baseline 3 for a fully documented schema 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 (List) and resource (projects in Recently deleted) with the exact shape of each entry, which cleanly separates it from siblings like list_projects and list_versions. An agent knows exactly what it will get back 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?

Explains the default scope (caller's personal deleted projects) versus the workspaceId-scoped behavior, and points at list_workspaces as the source of the id and restore_project as the follow-up action. It never explicitly says when NOT to use it (e.g., use list_projects for live projects), 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?

Although annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, the description goes far beyond by detailing the semantics of the returned fields: 'kind' differentiates bookmarks (deliberate saves, partner-pinnable) from auto-snapshots (restore-only), 'version_number' stability rules (deletes leave gaps, numbers never re-shuffle), and 'cp' meaning (page changes, special values like '*' and absence). It also discloses that the tool returns summaries, not the inner project JSON. This is rich behavioral context that helps the agent interpret results correctly.

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 function ('List every saved version of a project, newest-first') and then systematically explains each relevant field. Every sentence provides necessary context (kind distinctions, version_number stability, cp semantics, and downstream usage). The length is justified by the complexity of the output fields; it is not verbose or redundant.

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

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

Given that an output schema exists (as indicated by 'Has output schema: true'), the description does not need to detail the return structure. It covers all essential operational aspects: what is returned, field semantics, ordering, and how to use the output with related tools. Combined with the annotations, there is nothing an agent needs to call this tool 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?

The schema already provides 100% coverage for projectId ('Project whose versions to list.'), so the description does not need to add parameter details. The description does not explicitly restate the parameter, but the baseline for fully covered parameters is 3, and no additional semantic value is required or added.

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

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

The description states a specific action ('List every saved version of a project'), the resource ('saved versions of a project'), and the ordering ('newest-first'). It clearly distinguishes itself from sibling tools like save_version, restore_version, rename_version, and delete_version by focusing on the read-only listing nature and explicitly noting it returns summaries, not the inner project JSON.

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 usage context by explaining the returned fields (kind, version_number, cp) and explicitly directs the user to use the returned id with restore_version, rename_version, or delete_version. It does not explicitly state when to use this tool over alternatives, but the intent is obvious given the sibling set and the read-only nature. A minor gap is the lack of explicit 'when not to use' guidance, but the context is strong enough.

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 destructiveHint=false, so the safety profile is covered. The description adds genuine value beyond that: the role enumeration (owner/admin/editor/viewer), the permission implication (only owner/admin/editor can add projects), and the empty-list edge case for keyless/dev identities. Minor gap: no statement about ordering or pagination, though openWorldHint=false implies a bounded set.

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

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

Three tight sentences, front-loaded with what is listed and what comes back. Every clause carries distinct information: the entry shape, role/permission meaning, the id cross-reference, and the empty-list condition. No restatement of the title or annotations.

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

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

With an output schema present, return values need not be re-explained, yet the description still adds the role enum semantics, sibling id mapping, and the empty-list failure mode. Nothing an agent needs in order to call this zero-arg read tool correctly is missing.

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

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

The tool takes zero parameters, so the baseline of 4 applies. The description instead documents output field semantics (role values, id mapping) rather than parameters, which is above the floor even though an output schema already exists.

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

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

States a specific verb and resource ('List the workspaces (shared team spaces) the account belongs to') and even enumerates the returned shape {id, name, role, memberCount}. An agent can distinguish this from siblings like list_projects or create_workspace 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?

Names the consuming siblings explicitly — the returned `id` is the workspaceId argument of create_project, move_project_to_workspace and list_projects — which tells an agent when this tool is a prerequisite. It stops short of an explicit when-not clause or a direct comparison against list_projects.

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

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

Annotations already declare destructiveHint=true, and the description adds specific behavioral details: the earliest line survives, others are removed, and texts are joined in time order with a union window. It also warns about the constraint on other lines. This goes beyond annotations without contradicting them, though it doesn't describe failure modes or return details.

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 that front-load the main action and outcome, then state constraints and a hint. No filler or repetition; 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 mutation tool with clear constraints, the description covers the essential behavior, prerequisites, and the reason for the destructive hint. It is complete for an agent to know when and how to invoke it, especially with the sibling split tool available for contrast.

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%, with both parameters well-documented (projectId as opaque UUID, elementIds as text.<id> list). The description adds minimal new parameter semantics beyond the schema, 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?

The description states a specific verb and resource: 'Merge two or more caption lines into one.' It also details the outcome (earliest survives, union window, time-ordered texts) and distinguishes from the sibling split_caption_line by focusing on the merge action. This is clear and non-tautological.

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 conditions for use: all lines must share one flavour (same clip or standalone) and no other line may sit inside the merged span. It even suggests a workaround ('move or include it first'). It implicitly differentiates from split_caption_line by specifying merge behavior. This provides strong when-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 provide readOnlyHint=false and destructiveHint=true, but the description adds significant context beyond these: keyframe overrides, refusal behavior, clear_animation semantics, and group-specific limitations (no width/height/rotation; use add_keyframe for group rotation). This fully discloses side effects and edge cases, so the agent is well aware of potential pitfalls.

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

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

The description is concise, front-loading the primary purpose and then detailing constraints. However, it is somewhat dense—the section on keyframe overrides could be seen as lengthy. Each sentence adds important information, so it earns a high score, but a slight restructure could improve readability.

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

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

Given the tool's complexity (10 parameters, different layer types, animation interactions) and rich schema annotations, the description fully covers what an agent needs to use this tool correctly. It explains the keyframe interaction, group behavior, coordinate systems, and clear_animation usage. The output schema exists, so return values are not needed in the description. This is 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 schema already covers 100% of parameters with detailed descriptions, giving a baseline of 3. The description adds substantial value by explaining the interaction between parameters and the keyframe system, particularly for scale/opacity with clear_animation. It also clarifies that group layers use different properties (pivotX/pivotY). This exceeds the baseline and makes the parameter meanings even clearer.

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

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

The description clearly identifies the tool's purpose: setting a layer's static base transform (x/y/w/h/rotation), scale, and opacity. It specifies the exact resource types and properties affected (image.<id>, video.<id>, shapes.<id>, group.<id>) and distinguishes group behavior. This enables an agent to understand it as the static-transform tool, distinct from animation-focused tools like add_keyframe.

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 instructs when to use this tool vs. alternatives: 'use add_keyframe to animate, move_layer to set the un-animated default.' It also explains when the tool will refuse to write (if a property has an existing keyframe track) and how to override that with clear_animation:true. This is comprehensive guidance for correct selection and invocation.

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

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

Annotations already declare destructiveHint=true, and the description does not contradict this; it adds valuable behavioral detail: visibility to all members with role-based edit/view, and the clean dropping of old membership when switching workspaces. It also discloses permission requirements. This goes beyond the annotation's generic destructive flag, providing concrete consequences.

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

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

The description is front-loaded with the core action and immediately covers both usage modes. Every sentence adds essential information—permissions, side effects, and parameter guidance—with no filler or repetition. It is concise yet complete for a tool of this complexity.

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 an output schema, the description covers all essential aspects: the action, the two distinct use cases, required permissions, membership behavior, and the source of the workspace ID. An agent has everything needed to call the tool correctly and anticipate its effects, without needing to open the schema or guess return behavior.

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

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

Schema coverage is 100%, so both parameters are documented. The description adds extra semantics beyond the schema: it specifies that workspaceId should come from list_workspaces, explains the null case for returning to personal space, and clarifies the effect of each mode. This enrichment justifies a score above the baseline of 3.

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