Morpha

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

Annotations already indicate readOnlyHint=false and destructiveHint=false, so the mutation intent is known. The description adds valuable behavioral context: the overlay plays in the editor preview and is mixed into the MP4 export, and frames are computed at 30 fps with round(s * 30). It does not contradict any annotation.

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

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

Four tightly packed sentences cover formats, prerequisites, parameter mapping, frame conversion, and export/preview behavior without redundancy. The most important action and constraint are front-loaded.

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

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

Given the output schema exists and the input schema covers all parameters at 100%, the description is nearly complete for a 9-parameter mutation. It explains asset prerequisites, timing model, and rendering impact, though it could have briefly noted that modifying an existing overlay belongs to update_audio_overlay.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful parameter nuance: filename comes from an upload response, name is used as the track label, and seconds should be converted with frames = round(s * 30). This goes beyond the schema's field descriptions.

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

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

States a specific verb and resource ('Add an audio overlay') and immediately distinguishes the operation with supported formats and frame-aligned scheduling. This clearly differentiates it from siblings like update_audio_overlay and remove_audio_overlay.

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?

Provides clear prerequisite context: the asset must already be uploaded via upload_audio, create_upload_link, or the editor. It tells the agent to pass the upload's returned filename and name as the track label, but it does not explicitly contrast this with update/remove 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 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 indicate readOnlyHint=false and destructiveHint=false, so the description adds value by detailing the mutation: it adds a layer. It explains the behavioral difference between omitting the block parameter (persistent overlay) and passing it (bounded clip), and notes keyframe sampling relative to start. No contradiction with annotations.

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

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

The description is detailed but every sentence adds value. It front-loads the core action, then provides necessary upload context and behavioral options. No redundancy or fluff.

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

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

Given the tool's complexity (8 parameters, nested block object, upload prerequisite), the description covers all essential context: how to obtain the asset, how to map upload returns to parameters, and the behavioral choice of persistent vs. bounded layer. An output schema exists, so return values need not be in the description.

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%, but the description goes beyond schema by linking `filename` to the upload's returned id and `name` to the label, and explaining the block parameter's default behavior and its impact on keyframes. This adds meaningful context not present in the schema alone.

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

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

States a specific verb ('Add') and resource ('image layer'), clearly distinguishing it from sibling tools like add_video_layer and add_text_layer. It also explains the required precondition (uploaded asset), which sharpens the tool's purpose.

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 explains when to use this tool: after an asset is uploaded, and lists the available upload methods (drag-drop, upload_image, create_upload_link, or API endpoint). It also explains how to duplicate an existing layer by reusing its filename, giving concrete usage scenarios. No confusion with other add tools.

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

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

The 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 already mark readOnlyHint=false and destructiveHint=false, so the description aligns with a mutating but non-destructive operation. It adds valuable behavior: re-keying to fresh ids, pinning to an immutable version, and crucially that edits are local and never propagate to the source. This exceeds what annotations provide.

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

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

The description is a single paragraph of four sentences, front-loaded with the core purpose. It is concise enough and each sentence adds value (purpose, mechanics, local editing, identification). No waste, though it could be slightly 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?

The description covers the main behavior, the mutation effect, version pinning, and how to identify the result. It does not mention error conditions or prerequisites, but the presence of an output schema reduces the need to explain return values. Given the tool's complexity, this is quite complete, though it could add a note about when not to use 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 coverage is 100%, so parameters are fully described in the schema. The description restates the id passing and version optionality without adding new syntax or format details. It does reinforce the constraint 'must not be this project' but that is already in the schema, so the description adds minimal extra value.

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

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

The description uses a specific verb (embed) with a clear resource (another project, 'a morpha') and a specific outcome (version-pinned band). It also distinguishes the result from a plain group via describe_video markers, so it stands apart from sibling tools like add_embed_origin.

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 clear context on when to use the tool (embedding a version-pinned project) and explains local editing behavior. It does not explicitly name alternatives or exclusions, but the mention of re-pinning via the Inspector and describe_video for identification gives useful operational guidance. A small gap is not saying 'use this instead of add_embed_origin'.

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=false, so the description is not required to state mutation. It adds useful behavioral details: no limit on page count, the new page becomes active, its index is returned, and deep-copy mints a fresh id. These go beyond the annotations and help the agent predict side effects.

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

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

The description is somewhat long but well-structured: it starts with the core action, then explains conditional behavior, limitations, return value, and a concrete use case with follow-up steps. Each sentence provides necessary information; the front-loading of the primary purpose makes it easy to scan.

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

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

Given the presence of an output schema, the description does not need to detail return values, though it mentions the index. It covers the two operational modes, the absence of page limits, and provides guidance on how to use the created pages. It could have mentioned prerequisites like project existence, but the phrase 'works on any project' covers that implicitly.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds value by explaining the conditional behavior of duplicate_index (deep-copy with new id) and that without it a blank page is appended. It also mentions the return value (index), which is not in the schema, though the output schema 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?

The description clearly states the verb and resource ('Append a page to the project') and distinguishes the two modes (blank append vs. deep-copy via duplicate_index). It also clarifies the effect on the project ('turning a single-page video into a multi-page one'), which differentiates it from sibling tools like delete_page or select_page.

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 provides a use case ('For several versions of one video... make pages of one project with add_page and duplicate_index') and gives follow-up guidance for editing and exporting the copies. It implies when to use this tool and what to do afterward, though it does not name alternative tools for page addition (since none exist).

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 indicate non-read-only and non-destructive, and the description adds default positioning behavior plus the native-shape caveat. It does not disclose mutation consequences, reversibility, or return format, but the annotations carry the safety profile, so a mid score 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 bloated by a full enum list that duplicates the input schema, consuming most of the text. The genuinely useful guidance—native vector shapes, don't substitute an image, default centering—is buried at the end, so it is not lean or front-loaded.

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

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

For an 8-parameter tool with a nested block object and no visible output schema, the description omits coordinate units, width/height semantics, and return value behavior. It is not complete enough for an agent to call it correctly without opening the schema and guessing.

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%; the description compensates by mentioning x/y/w/h default behavior, but it does not explain coordinate units, origin, or width/height semantics. It also repeats the entire kind enum already present in the schema, adding no new meaning for those 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?

"Add a shape layer" is a specific verb+resource and the note that these are native vector shapes (never substitute an image layer) differentiates it from add_image_layer. However, it doesn't explicitly name the sibling tools like add_text_layer or add_video_layer, so it's clear but not fully differentiated.

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

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

The description implies usage for vector primitives and warns against using an image layer instead, which is a when-to-use signal. It also states default centering when x/y/w/h are omitted. But it never names alternative tools or gives explicit when-not-to-use conditions, so guidance is partial.

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?

With only readOnlyHint=false and destructiveHint=false in annotations, the description carries the full burden and delivers extensively. It discloses creation semantics, default values, the autofit modes' precise behavior (including the guarantee that 'hug' prevents re-wrapping between preview and export), curve direction conventions, and the return value. It even explains the legacy 'shrink' mode. Nothing is left opaque.

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

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

The description is long but every sentence earns its place given the 23 parameters and complex behaviors. It front-loads the core purpose and then covers defaults, styling, autofit modes, and return value in a logical order. It is dense but not redundant; minor verbosity in the autofit explanation is justified by its importance.

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 23 parameters, nested objects, an output schema, and rich sibling interactions, the description is comprehensive. It covers defaults, behavioral nuances, return value, and critical caveats (e.g., curve only works on single lines). An agent can confidently invoke this tool without needing to consult other documentation.

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

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

Schema description coverage is 100%, so every parameter already has an explanation in the schema. The description adds some nuance (e.g., explaining the rationale for hug mode and pairing with set_text_background), but it largely repeats the schema's parameter details. It does not significantly compensate beyond what the schema provides, so the baseline 3 is appropriate.

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

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

The description opens with a specific verb-resource pair ('Create a new text layer') and immediately qualifies it as a 'first-class leaf that animates, groups, and z-orders exactly like an image or shape,' which clearly separates it from siblings like add_caption_track or set_layer_text. It also enumerates the full styling surface, so an agent knows exactly what this tool is for.

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 states what the tool does and hints at usage contexts (e.g., 'what an agent-placed watermark / lower-third almost always wants' in the block parameter), but it never explicitly contrasts it with alternatives or says when not to use it. There is no 'use add_caption_track instead' type guidance, so the when-vs-other-tools decision 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 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 already indicate readOnlyHint=false (mutating) and destructiveHint=false. The description adds meaningful context beyond this: the upload prerequisite, the filename/name mapping, and that duplication auto-assigns a fresh id. This extra detail about side effects (fresh id) is valuable, so a 4 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?

Three sentences, front-loaded with the core purpose, followed by prerequisite, parameter mapping, and a special case. No redundancy or wasted words – every sentence contributes.

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 only non-obvious aspects (upload mapping, duplication) while the schema handles x/y/width/height/projectId. An output schema exists, so return format needs no explanation. Nothing 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%, so the baseline is 3. The description adds extra meaning by linking clip to the upload's filename and name to the upload's label, and explains the duplication reuse case. This goes beyond the schema descriptions, earning a 4.

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

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

The description opens with 'Add a video layer' – a specific verb and resource that clearly distinguishes it from sibling add_* tools (add_image_layer, add_text_layer, etc.). It further clarifies scope by explaining the upload prerequisite and how to map upload results to parameters.

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?

Provides clear usage context: the clip must be uploaded first, and it explains the duplication workflow (reuse clip filename). It does not explicitly contrast with alternative add_* tools, but the purpose is unambiguous enough that an agent can infer when to use it. Lacks explicit 'when not to use' guidance, so a 4 rather than 5.

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

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

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?

Annotations already mark the tool read-only and non-destructive, and the description adds substantial context: client-side execution, mandatory preview proxy, editor behavior, state semantics including 'cancelled' persistence, and audio_split not gating `processed`. There is no contradiction with annotations.

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

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

The description is long but front-loaded with the core purpose and scope. Every subsequent sentence earns its place by explaining states, client/editor execution, audio_split caveats, and the tool's use case. There is no filler or redundant 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?

The tool is complex enough to need the detailed state model, and the description covers it fully: output shape, allowed step values, cancellation behavior, audio_split semantics, and the relationship to transcribe_clip/detect_text_regions. The output schema exists and is complemented, not replaced, by the description.

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 `projectId` and `clip`. The description reinforces the omission behavior of `clip` and adds pipeline context, but it does not add new parameter syntax or format details beyond what the schema provides.

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

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

The description states a specific verb and resource: 'Report whether a clip — or every video clip in the project, if `clip` is omitted — has been through the browser-side video-processing pipeline.' It enumerates the pipeline steps and explicitly names sibling tools (transcribe_clip, detect_text_regions), making its purpose unmistakable.

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

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

It gives explicit when-to-use guidance: 'Use it to know whether transcribe_clip / detect_text_regions will return data, and to surface an unprocessed state to the user.' It also clarifies processing never runs on the server and explains audio_split behavior, preventing incorrect assumptions about when to call this tool.

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

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

The annotations only indicate that the tool is not read-only, not open-world, and not destructive, which is minimal. The description goes beyond this by detailing the cloning behavior (copies JSON, assets, clips), workspace inheritance and fallback rules, failure conditions (view-only source), and the lack of auto-refresh in the editor. This is substantial behavioral context beyond the annotations, though it does not specify error codes or side effects on the source project (which is 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?

The description is detailed but remains focused and front-loaded: it leads with the core purpose and returns value, then explains cloning and workspace placement. It is longer than a typical definition due to necessary complexity, but every sentence serves a purpose (e.g., the warning about view-only source). Minor redundancy exists with the schema descriptions but is acceptable for the added decisional guidance.

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—three parameters with conditional behavior, workspace inheritance, failure modes, and editor refresh behavior—the description covers all necessary decision points. The output schema exists, so the return value is structurally documented. The description is complete enough for an agent to invoke the tool correctly across all scenarios (blank, clone, workspace assignment, personal copy).

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description adds nuance by clarifying the interaction between workspaceId and fromProjectId, and the fallback behavior, which is valuable. However, since the schema already provides detailed descriptions for each parameter, the added semantic value is incremental, justifying a baseline of 3.

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

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

The description states a specific action ('create a new project'), identifies the resource, and explains that it returns a server-minted UUID. It clearly differentiates between creating a blank project and cloning, and names the sibling tool duplicate_project to disambiguate. This is explicit and distinguishes it from other project-related tools like duplicate_project and open_project.

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

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

The description explicitly instructs when to pass fromProjectId (to clone) versus omitting it (blank project), how to use workspaceId to control placement, and warns that cloning a source in a view-only workspace will fail unless workspaceId:null is passed. It contrasts with duplicate_project and provides clear decision logic, leaving no ambiguity for the agent.

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

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

Beyond annotations (destructiveHint=true), the description reveals concrete behavioral details: the link expires after 15 minutes, a second upload replaces the first, and uploads are subject to size caps, SVG safety checks, and storage quota. This is exactly the kind of behavioral context annotations alone cannot provide.

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

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

The description is dense but every sentence contributes: accepted types, return fields, usage workflow, replacement/expiry behavior, validation constraints, alternatives, and a documentation link. It is front-loaded with the core purpose and wastes no words.

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

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

With an output schema present for return values, the description only needs to explain behavior not already structured. It covers the upload flow, time-to-live, overwrite semantics, size limits, and alternative tools, leaving no critical gap for an agent to call the 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 description coverage is 100%, so the baseline is 3. The description adds meaning by explaining that 'name' is the on-disk path used by the returned command, that only its last segment is shown to people, and that the file is stored under a fresh id. This goes beyond the schema's description, though projectId gets no extra clarification.

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: 'Put a file from the caller's own disk into a project' and enumerates accepted file types. It also distinguishes itself from near siblings by explicitly routing shell-less clients to upload_image/upload_audio and video clips to client.addVideo.

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 and when-not-to-use guidance: clients without a shell should use upload_image/upload_audio instead, and video clips must go through morphareels-sdk's client.addVideo. It also explains the full workflow: run the returned command, then pass the filename to add_image_layer, add_audio_overlay, or set_custom_font.

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 by disclosing that the caller becomes owner, that email-based accounts are required (keyless identities fail), and that duplicate names cause a conflict error. These are critical behavioral traits an agent must know, and they don't contradict the readOnlyHint/destructiveHint flags.

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, each carrying a distinct piece of information: purpose and return shape, usage context, ownership and prerequisites, conflict behavior, and a naming tip. No filler or repetition; information is front-loaded.

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

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

For a one-parameter mutation tool, the description covers the return shape, caller permissions, failure mode, and post-creation workflow. Combined with the output schema and annotations, an agent has everything needed to decide, invoke, and interpret the result 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 already fully documents 'name' (100% coverage), so baseline is 3. The description adds practical context — 'Refer to it by `name` when talking to the user, never the id' — and implies the name is the key for the duplicate conflict. This extra guidance justifies a 4.

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

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

The description opens with 'Create a new workspace (a shared team space) owned by the caller' — a specific verb and resource with a clear definition. It then contrasts with create_project and move_project_to_workspace, making the tool's role unmistakable among 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 states when to use it ('when the user wants a new place to group projects') and names the follow-up tools (move_project_to_workspace, create_project) that work with the new workspace. No ambiguity about when this tool is the right choice.

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?

Annotations already mark destructiveHint=true, but the description goes further by specifying exactly what gets destroyed, the permission model, the fact that deletion is permanent, and the lack of session auto-refresh. This is substantial added context beyond the annotation flags.

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, each carrying distinct information: the scope of deletion, permission requirements, and an edge case plus session behavior. It is front-loaded with the main effect, and no sentence is wasted, though it is slightly dense.

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 action, the description covers all necessary context: what is destroyed, who can perform it, whether deletion is permanent, the edge case of the last project, and user session behavior. An output schema exists to explain return values, so nothing essential is missing.

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

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

The schema fully documents the only parameter (projectId) with a description. The tool description adds no extra parameter-specific information, but the schema coverage is 100%, 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 the exact action (permanently delete) and the resource (project), and enumerates the sub-resources destroyed (JSON, shortlist, versions, uploaded assets, clips). This distinguishes it from sibling tools like delete_page or delete_version, which target different resources.

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

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

Explicitly states the prerequisite of edit access and lists who qualifies (owner, workspace editor/admin/owner, or direct-share editor), plus the opaque not-found for others. It also notes the edge case that deleting the last remaining project is allowed, providing clear 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 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?

The annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds significant behavioral context: it explains the platform_safe_area concept, the z-ordered tree, the pages block, and explicitly states that keyframe values and styles are unbounded and not included. It also notes that on multi-page projects, content tools target the active page. This adds value beyond the annotations and helps the agent understand the tool's exact scope and limitations.

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

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

The description is detailed but well-structured. It front-loads the core purpose ('Structural OVERVIEW') and then provides a logical breakdown of what it includes, what it excludes, and how it relates to other tools. While it is longer than the average description, every sentence contributes value—the platform_safe_area explanation, the z-order tree, the pages block, and the guidance to use inspect_layers. No fluff or redundancy.

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

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

Given the tool's complexity and the presence of an output schema, the description is comprehensive. It covers what the tool returns (structural overview with specific fields), what it does not return (keyframes and styles), and how to interact with multi-page projects. It also provides a clear workflow ('Start here, then call inspect_layers'). The agent has all the information needed to decide when and how to invoke this tool correctly.

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

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

The input schema has one parameter, projectId, with a 100% description coverage. The schema already describes it as 'Opaque project id (a v4 UUID, from list_projects/create_project). Selects which existing project this call mutates.' The description does not add additional semantics for this parameter, which is fine given the high schema coverage. 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 tool's purpose: 'Structural OVERVIEW of the composition (the table of contents)' and enumerates what it includes (canvas size, duration, platform_safe_area, backdrop summary, z-ordered layer tree). It also explicitly differentiates from sibling tools by noting it does NOT include keyframe values or styles, and it points to inspect_layers for detailed layer info. This is a specific verb+resource with clear scope and differentiation.

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

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

The description gives explicit usage guidance: 'Start here, then call inspect_layers([elementId, …]) for full detail on the specific layers you'll change.' It also explains how to manage pages (select_page, add_page, delete_page, reorder_pages) and clarifies that content tools target the active page. This is a clear when-to-use vs alternatives with concrete next steps.

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?

Annotations only declare readOnlyHint=false and destructiveHint=false; the description adds substantial behavioral context beyond that: fresh opaque ids, the workspace-following default, failure rather than silent fallback for view-only sources, the non-member edge case landing in personal space, the no-auto-refresh UX behavior, and the returned workspaceId identifying placement. Nothing contradicts the annotations — destructiveHint=false is consistent with creating a brand-new copy rather than destroying the source.

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 its core purpose and organized with a WORKSPACE: label plus parenthetical edge cases, which aids scanning. However, it partially duplicates the schema — the name default ('Defaults the copy's name to "<source name> copy"') and the 'FOLLOW THE SOURCE' rule are already stated in the schema's workspaceId description. At roughly 250 words it is longer than strictly necessary, though most of the extra length carries genuinely new information like failure modes and refresh behavior.

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

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

This is a high-complexity tool — workspace placement policy, role requirements, failure modes, non-member edge cases, and UX refresh semantics — and the description addresses all of them, plus return-value semantics ('The returned workspaceId tells you where it went'). An output schema exists, so the return structure is covered structurally. An agent has everything needed to invoke this tool correctly under every workspace scenario described.

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

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

With 100% schema coverage, the baseline is 3 and the schema already documents all three parameters well. The description goes further on workspaceId by adding the failure condition ('If the source lives in a workspace you can only VIEW, the call FAILS') and the non-member edge case, which are not stated in the schema. projectId and name gain little beyond the schema, so the added value is moderate but real.

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

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

The opening sentence states a specific verb and resource with concrete scope — 'Duplicate an existing project into a brand-new one — a full copy of its layers, animations, styles, uploaded assets, and clips.' This distinguishes it from siblings like create_project (a new blank project) and duplicate_layer (a layer, not a project), and the 'full copy' phrase makes the semantics actionable. No ambiguity about what this tool does.

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

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

The description gives explicit when-not-to-use guidance: 'For several versions of one video (hooks, languages, a sheet's rows), make pages of one project with add_page and duplicate_index.' It also provides conditional usage rules for workspaceId — when to override (edit-capable role), when the call fails (view-only source), and when to pass null — so the agent can decide correctly between this tool and workspace operations. This is explicit when/when-not guidance, not merely implied context.

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

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

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 already declare destructiveHint=true and readOnlyHint=false, so the mutation is known. The description adds valuable behavioral context: the group composes transforms onto descendants, pivot is seeded to centroid, x/y are translation offsets around the pivot, and groups have no static body. This goes beyond the annotations and helps the agent predict side effects.

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

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

The description is dense but purposeful, with the core instruction front-loaded and the behavioral details following. It is longer than average, but every sentence earns its place by explaining either when to use the tool or what the group does. The only minor inefficiency is the parenthetical list of examples, which is illustrative rather than strictly necessary.

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

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

Given the tool's complexity (transform composition, pivot behavior, parent constraints) and the presence of an output schema, the description covers all the essential behavioral and usage information an agent needs. It explains the group's transform model, the pivot seeding, the parent precondition, and the naming rationale. 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 coverage is 100%, so the schema already documents all three parameters. The description adds meaning by explaining the group's transform model (x/y offsets around pivot, pivot seeded to centroid), which clarifies the effect of the 'name' and 'elementIds' parameters beyond their raw schema descriptions. It doesn't add syntax details, but the schema already covers those.

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 ('Wrap sibling elements in a new group') and immediately distinguishes the tool from siblings like ungroup_layers, rename_group, set_group_parent, and set_group_box. It also gives concrete examples of what constitutes a groupable thing, making the purpose unmistakable.

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 'USE THIS whenever several layers are one thing' and explains why loose siblings are a defect, giving the agent a clear decision rule. It also states a precondition ('All listed elementIds must currently share the same parent'), which is essential for correct 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 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, and the description does not contradict this. It adds valuable context: the default scope (personal projects), the meaning of id vs. name (ids opaque, names human-readable), and the editorUrl usage. It also explains the membership requirement for workspace listing, going beyond the schema.

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

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

The description is comprehensive but not bloated. It is logically structured: output fields first, then default behavior, then workspace parameter, then usage cues. Every sentence adds information without redundancy, though it is a bit longer than strictly necessary.

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

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

For a simple read-only tool with an output schema, the description covers everything needed to call it correctly: the output format, the default behavior, the optional parameter, and when to invoke it. Nothing essential is missing.

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

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

Schema coverage is 100% (workspaceId has a description), so the baseline is 3. The description adds value by explaining where to get the value (from list_workspaces), what it does (lists workspace projects including teammates'), and that it returns ownerEmail. This goes beyond the schema's brief description.

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

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

The description states a specific verb ('List'), resource ('projects'), and the exact output shape ('{ id, name, editorUrl }'), which distinguishes it from siblings like list_workspaces and list_versions. It also explains the semantics of each field, making the tool's purpose unmistakable.

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

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

It explicitly gives the trigger conditions ('Call this when the user asks "what projects do I have?" or hasn't named a project but you need to operate on one') and explains the alternative behavior when workspaceId is provided, pointing to list_workspaces as the source. This is clear guidance on when and how to use it.

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

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

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, but the description adds substantial behavioral context: role semantics and permissions, the empty-list behavior for keyless/dev identities, and the instruction to use id internally while using name for user-facing communication. These go well beyond the structured fields.

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

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

Every sentence earns its place: output shape, role meaning, downstream usage, edge-case behavior, and a clear call-to-action. The information is front-loaded and compact without being padded.

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

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

For a no-parameter, read-only lookup tool with an output schema and clear annotations, the description is fully complete. It covers what is returned, what the values mean, when to call it, and how to use the results with related tools.

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

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

The tool has zero parameters and the schema has no properties, so there is nothing for the description to clarify. A baseline of 4 is appropriate here because there are no parameter gaps to compensate for.

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 a well-defined resource ('workspaces (shared team spaces) the account belongs to'), and immediately distinguishes it from sibling tools like create_workspace and list_projects. The output shape is given up front, leaving no ambiguity about what the tool 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?

Explicitly tells the agent when to call this tool ('Call this to discover a workspace before placing a project into it'), how to use its result ('Use the id as the workspaceId argument to create_project, move_project_to_workspace, and list_projects'), and what to display to the user (name, never id). The no-email edge case also removes a likely failure mode.

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?

The description adds rich behavioral context beyond the annotations: the band's inner reel plays relative to the time origin, intro animations fire when the band appears, the current window length is preserved, and a band with no window spans from start to composition end. This goes well beyond the readOnlyHint/destructiveHint flags and gives the agent a clear mental model of the mutation's effects.

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

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

The description is front-loaded with the action, then adds only high-value behavior details and parameter provenance. Every sentence earns its place, and there is no repetition of the input schema.

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

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

For a 3-parameter, 100%-schema-covered tool with an output schema and destructive annotations, the description is complete. It explains purpose, behavioral effects, defaults, and how to obtain the band id, leaving no critical gap for an agent deciding to call this tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds extra value by explaining that bandId must come from describe_video and identify a group with morpha:true, and by linking start to the animation behavior. This is meaningful but not extensive, so a 4 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 uses a specific verb and resource: 'Place an embedded morpha band on the host timeline' and clearly defines the operation as setting its TIME ORIGIN. It also explains the effect this has on the band's intro animations, which distinguishes it from generic move or placement tools like move_layer or shift_group.

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 it: it is 'the fix for the embedded intro doesn't animate' case, and it tells the agent to pass a band group id from describe_video with morpha:true. It does not explicitly name excluded alternatives or say when not to use it, so it falls slightly short of a 5.

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

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

Annotations 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?