Sequencer

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

With no annotations, the description carries the full behavioral burden. It says 'add', but does not disclose what happens on channel collisions, how autoChannel interacts with an explicit channel, what relativeStartTime requires (a pinned shot), permission needs, or whether the call is idempotent. For a 15-parameter mutation, this is a substantial gap.

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

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

A single dense sentence with the action front-loaded and no filler. It is efficient, though cramming six feature groups into one clause makes it read as a feature list rather than guiding the caller.

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 15-parameter mutation with no annotations and no output schema, the description is adequate at the surface level but omits the cross-parameter interactions (autoChannel vs channel, relativeStartTime requiring pinnedToShotId) and any failure/error behavior an agent would want before calling.

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 15 parameters in detail. The description groups them into themes (placement, trim, fades, volume automation, channel, shot pinning), which is a useful mental model but adds no syntax or interaction detail beyond the schema.

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

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

States a specific verb (add) and resource (audio track on edit timeline) and scopes the source as an 'existing workspace audio media item', which implicitly separates it from generate_audio_track. It does not name any sibling explicitly, but the resource and the source constraint are unambiguous.

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

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

Usage is only implied by the word 'existing' — the agent can infer this places already-uploaded audio rather than synthesizing it, but the description gives no explicit when-to-use, prerequisites, or when to prefer generate_audio_track instead.

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

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

With no annotations, the description carries the full burden but discloses no side effects, permissions, or behavioral traits. It does not mention that a track is auto-created (per schema), nor what happens to existing overlays, how mutations are reversible, or any auth requirements.

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 sentence that front-loads the core purpose and then enumerates capabilities. It is efficient and contains no filler, though the long feature list is a minor detraction from crispness.

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 26-parameter mutation tool with nested objects, no annotations, and no output schema, the description is far too thin. It should cover required parameters, track auto-creation, side effects, and return behavior, but only lists high-level feature categories.

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 enumerates feature categories (transform, border radius, shadow, etc.) but adds no syntax, defaults, or meaning beyond what the schema already provides for each parameter.

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

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

States a specific verb ('Add') and resource ('image or video media overlay') scoped to the 'edit timeline'. It clearly distinguishes itself from siblings like add_text_overlay, add_audio_track, and add_remotion_overlay by specifying the media type.

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 no when-to-use guidance, no alternatives, and no prerequisites. It lists capabilities but never says when to choose this tool over add_text_overlay or add_remotion_overlay.

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

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

No annotations are provided, so the description must carry the full behavioral burden. It implies an additive mutation but does not disclose side effects, permission requirements, whether the node is persisted immediately, what happens to existing workflow structure, or what the tool returns.

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

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

The description is front-loaded with the core action and then supplies the valid node type list. It contains no filler, and every element is useful for correct invocation.

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

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

The schema fully documents the five parameters, and the description adds the complete node type enumeration. However, with no annotations and no output schema, it omits behavioral details such as side effects, prerequisites, and return value, leaving meaningful gaps for a mutation tool with a nested config object.

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 substantial value by enumerating all valid nodeType values, going beyond the schema's brief examples and helping the agent avoid invalid node types.

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: "Add a node to a workflow." This clearly distinguishes it from delete_node, update_node, and connect_nodes by action, but it does not explicitly name or contrast those siblings.

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

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

The description provides no guidance on when to use add_node versus alternatives such as update_node or connect_nodes, nor does it state prerequisites like needing an existing workflow or workspace. Usage is only implied by the verb "add."

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 no annotations, the description carries the full behavioral burden. It discloses the render-order semantics but says nothing about required permissions, whether a new track is empty, what identifier is returned for later item placement, or whether ordering collisions are resolved. For a mutation tool this is a significant gap.

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

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

Two tight sentences with the creation purpose front-loaded and the ordering rule immediately after. Nothing is wasted, though the ordering sentence is partly redundant with the schema.

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

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

There is no output schema, so the description would ideally state what creating a track returns (e.g., a track ID needed by add_overlay_item). It is adequate for a simple creation call but leaves the return contract and lifecycle context 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 description coverage is 100%, so name, order, locked, visible and the two IDs are already documented. The description's stacking statement merely restates the schema's 'Stack order; higher renders on top' and adds no new parameter meaning.

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

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

States a specific verb (Create) and resource (overlay track) plus the kinds of overlay content it supports (text, image, video). It distinguishes the track-level tool from item-level siblings such as add_text_overlay and add_media_overlay, though it never names them explicitly.

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

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

No guidance on when to create a new track versus reusing an existing one, and no mention of the alternative add_audio_track or of the update_overlay_track/delete_overlay_track lifecycle. The only conditional information is the stacking behavior, which is not 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?

With no annotations, the description carries the full burden, and it does disclose one meaningful behavioral trait: the layer 'Compiles and test-renders it before saving,' telling the agent there is validation with a possible failure path before persistence. That is genuinely useful. It still omits auth/permission requirements, what happens on compile or render failure, whether the item can be edited afterward, and any latency expectations.

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

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

Three short sentences, front-loaded with the action, followed by behavioral disclosure and the prerequisite. Zero filler; 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?

This is a complex, 20-parameter tool with nested objects and no output schema, so the description needs to carry more weight than a simple CRUD tool. It covers purpose, key behavior, and a prerequisite, but leaves gaps around failure semantics of the compile/test-render step, whether the created overlay is addressable by a returned id (relevant given the sibling update_overlay_item / delete_overlay_item tools), and timeline placement requirements.

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

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

Schema description coverage is 80% across 20 parameters, so the schema already documents nearly everything (size, position, enter/exit, keyframes, legacy shorthands, remotionConfig.source). The description adds no parameter-level meaning, which is acceptable given the high coverage — baseline 3 is correct here.

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

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

The description names a specific verb and resource: 'Create a custom Remotion React animation layer on the edit timeline.' This is enough to distinguish it from the sibling add_text_overlay and add_media_overlay tools, since it is explicitly a Remotion React layer rather than a preset overlay. It stops short of differentiating further (e.g. vs. update_overlay_item or add_overlay_track), but the resource identity is clear.

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

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

'Call get_remotion_layer_guide first' gives an explicit prerequisite, which is real routing guidance. However, it says nothing about when to choose this tool over the other overlay-creation siblings, nor what conditions make a Remotion layer the right choice. Usage is implied (custom React animation) but not contrasted against alternatives.

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

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

With no annotations, the description carries the full behavioral burden for a mutation tool, yet it does not state side effects on existing refs, permission/auth needs, or reversibility. The legacy-compatibility note overlaps with the schema's alsoSetPrimaryMediaId description, so little new behavioral context is added.

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

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

Two tight sentences, with the core purpose front-loaded and the role enumeration immediately useful. No filler or redundant phrasing.

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

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

The schema is rich and fully documented, which offsets the missing output schema, but for a nine-parameter mutation tool with zero annotations the description is thin on consequences and edge cases. It is minimally adequate but leaves gaps an agent would want filled.

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

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

Schema description coverage is 100%, so all nine parameters are already documented, giving a baseline of 3. The description's mention of roles and legacy media ids restates what the schema already provides rather than adding syntax or format detail.

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

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

States a specific verb and resource ("Add a fine-grained media reference to a shot") and enumerates the exact role values, so an agent understands the operation immediately. It does not explicitly distinguish itself from close siblings like update_shot_media_ref or delete_shot_media_ref, leaving that to the name.

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

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

Usage is only implied by the verb and the role list; there is no explicit when-to-use versus update_shot_media_ref or add_media_overlay, and no stated prerequisites. The one contextual hint (legacy compatibility) is a behavior note rather than routing guidance.

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

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

With no annotations, the description carries the full burden. It usefully discloses the auto-creation of an overlay track and the preset/text override precedence, but says nothing about permissions, failure behavior, or what is returned for a mutation of this size.

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

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

Four tight sentences, front-loaded with the core action and then the preset/custom choice and the track side effect. No filler, though the parenthetical preset list is 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 42-parameter mutation with no annotations and no output schema, the description covers the primary workflow adequately since the schema documents all parameters. It is still thin on behavior (no return value, no permissions/error context) given the complexity.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning the schema lacks: the presetId-to-style mapping, the fact that text overrides the preset default text, and the presetId-or-textConfig alternative. That interaction between parameters is not expressed anywhere in the schema.

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

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

States a specific verb and resource ('Add a text overlay to the video timeline'), which clearly separates it from media/audio/remotion overlay siblings. It does not name a sibling explicitly (e.g. add_media_overlay), so it stops short of the 5-level 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?

It gives the two invocation routes (presetId vs custom textConfig) and enumerates the preset IDs, which is helpful. However it never states when to use this tool versus siblings like add_media_overlay, update_overlay_item, or add_overlay_track, and gives no exclusions or prerequisites.

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

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

No annotations are provided, so the description carries the full behavioral burden for a mutation tool. It conveys additivity but says nothing about required permissions, what happens on a boundary conflict, or side effects; it also doesn't reconcile the additive framing with the schema's replaceExistingBoundary defaulting to true.

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

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

A single sentence with zero waste; the key differentiator ('without replacing the whole transition list') is front-loaded and immediately actionable.

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 10-parameter mutation tool with no annotations and no output schema, the description is thinner than ideal, though the 100% schema coverage compensates for parameter detail. An agent gets the operation's intent but little about side effects or failure conditions.

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

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

Schema description coverage is 100%, so the schema already documents all 10 parameters including type, duration, startTime, and the boundary identifiers. The description adds no parameter-level meaning beyond that, 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?

States a specific verb+resource ('Add a single timeline transition between adjacent shots') and clarifies the additive scope versus a wholesale replacement. It is distinguishable from delete_transition/update_transition by the 'add a single' framing, though it never names a sibling explicitly.

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

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

The phrase 'without replacing the whole transition list' implies when to prefer this over a bulk-transition operation, but no alternative is named and no condition or prerequisite (e.g. shots must be adjacent) is stated. Usage is inferable rather than explicit.

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

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

With no annotations, the description carries the full behavioral burden. It does disclose real behavior beyond the schema: analysis targets the actual export artifact 'when possible' (implying a fallback), the result is cached on the export doc, and the return includes findings plus report-generation instructions. It omits what happens if no completed export exists, cost/latency, and permission requirements.

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

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

Two sentences, front-loaded with the core action, and each sentence adds distinct information (what is analyzed/cached, what is returned). No filler or restatement of the tool name.

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

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

For a four-parameter tool with no annotations and no output schema, the description does cover the return ('findings plus instructions for generating the compliance report') and caching semantics. It is still incomplete on preconditions (no completed export, in-flight exports), failure behavior, and its relationship to generate_ip_report.

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 editId, exportId, workspaceId, and forceRefresh are already fully documented, including the default-to-latest-export behavior. The description adds no parameter-level detail beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb+resource pair: 'Run IP and copyright analysis on the completed exported video.' An agent can distinguish this from generic analysis or generation tools. It does not name the obvious sibling generate_ip_report, so differentiation is only implied via 'instructions for generating the compliance report.'

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

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

The phrase 'on the completed exported video' implies a precondition (the export must exist and be finished), and the schema notes a default of the latest completed export. However, there is no explicit when-to-use versus generate_ip_report or when-not guidance, so routing between the two compliance-related tools is left to inference.

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

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

With no annotations, the description carries the full burden. It usefully discloses that the result is a NEW asset (non-destructive) and that the track can optionally be repointed, which are real behavioral traits. However, it omits whether the operation is long-running/async, whether it costs credits, and what happens to the source media.

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

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

A single front-loaded sentence that names the action, the result, and the optional side effect with no filler. Every clause earns its place.

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

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

For a mutation/generation tool with no annotations and no output schema, the description is adequate but incomplete: it explains the create-plus-optional-track behavior yet says nothing about the return value, async nature, or failure modes an agent would need to invoke it confidently.

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

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

Schema description coverage is 100%, so all six parameters (including modelId, voiceId, voiceReferenceUrl) are already documented in the schema. The description adds no format, constraint, or dependency detail beyond what the schema provides, so the baseline of 3 applies.

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

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

States a specific verb (create) and resource (a new voice-changed version of an audio media item), and clarifies the operation is additive rather than an in-place edit. It implicitly distinguishes itself from the change_video_voice sibling by scoping to audio, but never names that alternative.

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

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

No when-to-use guidance, no prerequisites, and no mention of the near-identical change_video_voice sibling or when to prefer generate_audio_track. The only usage hint is the optional track-repointing behavior, which is about mechanics, not selection.

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

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

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses that this is a multi-stage mutation that produces a new completed media version, but omits whether the operation is long-running/async, whether the original media version is altered, what permissions or credits are required, and how failures mid-pipeline are handled.

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 that names the operation first and then the pipeline stages. No filler, no repetition of the tool name.

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

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

For a six-parameter mutation pipeline with no annotations and no output schema, the description covers what happens but not how the caller should behave: no async/polling expectations, no indication of what the completed media version returns, and no differentiation from sibling voice/lip-sync 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?

Schema description coverage is 100%, so all six parameters (including voiceId, videoUrl override, and voiceReferenceUrl) are already documented in the schema. The description adds no syntax, format, or dependency guidance (e.g., clone vs. reference mode) beyond that 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+resource ('Run the video voice-change pipeline') and then enumerates the exact pipeline stages, which lets an agent distinguish it from change_audio_track_voice (audio-only) and lip_sync_video_media 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?

No when-to-use guidance, no prerequisites, and no routing against obvious alternatives such as change_audio_track_voice or lip_sync_video_media. The agent must infer from the name that this operates on a whole video rather than an audio track.

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

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

With no annotations, the description must carry the safety profile; 'check' implies a read, but it never states read-only/non-mutating behavior, permissions, or error behavior. It does disclose the return semantic (per-asset approved/rejected status), which is the main behavioral value added.

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, no filler, with the core purpose front-loaded and the workflow rationale second. Every clause earns its place.

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

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

For a simple two-parameter read tool with no output schema, the description covers purpose, scope, and the shape of the result (approval status per asset). It could say slightly more about the returned status values or ordering, but nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so editId and workspaceId are already documented in the schema. The description adds no extra meaning about their format, required-ness, or relationship beyond 'associated with an edit' — baseline 3 applies.

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

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

States a specific verb (check), resource (asset approval status), and scope (all assets associated with an edit). This scope wording separates it from single-asset siblings like get_asset and from generic list_assets, which does not surface approval state.

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

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

Explicitly names the decision context: use it to determine whether the user approved/rejected each asset before proceeding to scene and shot creation. That is a clear when-to-use signal, though it names no alternative (e.g. get_asset for a single asset) and states no exclusions.

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

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

No annotations exist, so the description carries the full burden. It usefully discloses a validation rule (sockets must match node direction), which is behavioral context beyond a mere label, but it says nothing about failure behavior on invalid sockets, whether duplicate connections are rejected or replaced, permission/auth requirements, or reversibility.

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

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

Three short sentences, the core action front-loaded, and every sentence adds a distinct constraint. No filler or restatement of the name.

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

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

For a 6-required-parameter mutation tool with no annotations and no output schema, the description covers the socket semantics well but omits error behavior, duplicate-connection handling, and what the tool returns on success. Adequate but with visible gaps an agent would likely need.

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

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

Schema coverage is 83%, so the schema already defines each field. The description adds a cross-parameter constraint the schema does not state – sourceSocketId must be an output of the source node and targetSocketId an input of the target node – which helps the agent avoid an invalid pairing. It still says nothing about the workflowId/workspaceId relationship.

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 ('Connect two nodes in a workflow') and is immediately distinguishable from siblings like add_node, update_node, and delete_connection. The follow-on sentences narrow the scope to a socket-level linkage, so the agent knows exactly what operation is being performed.

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

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

Gives clear operational context: use the exact socket IDs returned by add_node, and the sockets must be an output of the source / input of the target. It references the sibling that produces the required IDs (add_node) but does not mention delete_connection for undoing a link or any ordering/prerequisite beyond add_node.

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 this is a non-readOnly, openWorld, non-idempotent, destructive operation, and the description adds that it returns a tracked task with a playable result when complete. It does not warn that this is a paid generation, nor mention cost capping or idempotency-key behavior despite the tool being destructive and expensive. With annotations carrying the safety profile, this is a reasonable 3.

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

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

Three short sentences, front-loaded with the conversion action and the model prerequisite, with no filler. It is slightly terse given the tool's complexity, but nothing wastes space.

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

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

An output schema exists so return values need not be explained, and the schema covers most parameters, so the description is adequate for invocation. However, for a 21-parameter, destructive, paid generation tool, it omits cost/idempotency guidance and makes no attempt to orient the agent among the many video-mutation siblings.

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 81%, so the schema already documents most parameters and the baseline is 3. The description adds only marginal meaning by pointing at modelSettings for output-format selection; it says nothing about prompt, mediaInputs, idempotencyKey, maxCostUsd, or referenceImages semantics beyond what the schema already 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+resource ('Convert an existing video to HDR') and adds a real constraint (the catalog model must support video_hdr). It does not explicitly contrast with near-neighbors such as enhance_video_media or edit_video, so an agent must still infer the boundary, but the HDR specificity is strong enough to identify the tool.

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

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

It gives an actionable prerequisite: 'Use get_model_catalog to choose a supported model and its settings,' which routes the agent to the sibling needed before calling. There is no explicit when-not guidance or comparison to the other video-mutating siblings, so it falls short of a 5.

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

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

With no annotations, the description carries the burden and does disclose key side effects: character/location/prop creation triggers reference-image generation, style assets do not, and supplying existingMediaUrl skips generation entirely. It does not mention permission requirements, credit/cost implications of image generation, or whether duplicate names are allowed, which are relevant for a creation tool.

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

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

Three tight sentences with the purpose front-loaded, followed by the behavioral distinction and the optional-parameter note. Every sentence adds distinct information with no redundancy or filler.

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

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

For a 12-parameter creation tool with no output schema and no annotations, the description covers the essential behavioral distinctions (image generation vs. text-only, edit.style alternative, existing-media path). The remaining gaps, such as the editId-in-editor requirement and voiceDescription, are already documented in the schema, so the description is largely sufficient.

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

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

Schema description coverage is 100% across 12 parameters, so the schema already explains prompt, modelId, editId, and the existingMedia* fields in detail. The description reinforces the prompt and existingMediaUrl semantics but adds little beyond what the schema states; 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 (Create) and resource (asset) and enumerates the four asset subtypes it accepts, which matches the type enum exactly. An agent can distinguish this from siblings like generate_image, create_shot, or create_folder without opening any schema.

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

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

Gives a clear routing rule for the ambiguous case: style assets do not generate images, and routine projects should store global visual style in edit.style instead. It also clarifies when existingMediaUrl applies (user-supplied reference image). It does not, however, address when to prefer update_asset over create_asset or when an asset belongs in an edit 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?

With no annotations provided, the description carries the full behavioral burden. It discloses that aspect ratio is required and controls every generated shot, lists default model choices (useful for resource allocation), and states the return value ('Returns the new edit ID'). It doesn't mention side effects like whether it consumes credits or what permissions are needed, but it covers more than typical.

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 coherent paragraph of three sentences, front-loaded with the core purpose. It packs multiple useful details (aspect ratio rationale, model defaults, return value) without egregious redundancy, though the aspect ratio guidance is repeated in both description and 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?

Given 5 parameters, no output schema, and no annotations, the description is fairly complete: it explains the required aspect ratio, provides defaults for models, and states the return ID. It lacks discussion of error conditions or workspace permissions, but covers the essentials for a creation tool.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds marginal value by reiterating the aspect ratio guidance and model defaults, but doesn't introduce new syntax or constraints beyond what's in the schema. Baseline 3 is appropriate when 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+resource ('Create a new edit (project) in a workspace') and distinguishes from siblings like create_production and create_shot by naming the 'edit' entity. The parenthetical '(project)' clarifies the domain term.

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 guidance on aspect ratio selection ('use 9:16 for vertical/social films unless the user asks for another format'), which is a usage heuristic. However, it doesn't differentiate when to use create_edit versus alternatives like create_production or create_workspace, nor does it state prerequisites.

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

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

No annotations are provided, so the description carries the full behavioral burden, and it says almost nothing beyond the bare operation. It omits permission requirements, name-uniqueness or collision behavior, whether parentFolderId defaults to root, and whether the operation is reversible.

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

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

A single short sentence that is front-loaded with the verb and resource and contains no filler. It is efficient, though its brevity comes at the cost of the missing details noted elsewhere.

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

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

For a simple three-parameter create operation with full schema coverage and no output schema, the description is minimally viable. Gaps remain around permissions, name constraints, and parent-folder handling that an agent would benefit from knowing before calling a mutation tool.

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

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

Schema description coverage is 100%, so all three parameters (name, workspaceId, parentFolderId) are already documented in the schema. The description adds no additional meaning such as naming rules or parent-folder semantics, so the baseline 3 applies.

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

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

States a specific verb (Create) and resource (folder) with a clear scope (in a workspace), so an agent understands what the tool does. It does not, however, differentiate itself from nearby siblings such as list_folders or move_item_to_folder, which handle related folder operations.

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

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

There is no guidance on when to use this tool versus alternatives, no prerequisites, and no mention of related tools like list_folders or move_item_to_folder. Usage must be inferred entirely from the name.

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

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

Annotations already declare the write/destructive/open-world/non-idempotent profile, so the description's job is the rest. It adds genuinely useful behavior: the call returns tracked tasks and the caller must poll get_production_status, and the output is an editable project rather than a finished render. It does not explain cost implications or why destructiveHint is set for a create 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?

Front-loads the core capability, then branches per mode, and closes with the async polling note. Every clause is informative, though the middle section is dense enough that the three modes run together.

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

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

Covers the modes, prerequisites, and the async return path, which is important given there is no output schema. For a nested-schema, four-parameter creation tool with zero parameter descriptions in the schema, however, key invocation details (valid model strings, type/resolution/aspectRatio behavior, workspace scoping) remain undocumented.

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 0% across four parameters (including a nested `definition` object), so the description carries the burden. It clarifies intent for `referenceImages` (product ads) and `parameters` (localization target language) and the authored shot prompts, but says nothing about `workspaceId`, `model` values, `type`, `aspectRatio`, or shot duration limits.

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 and enumerates the three supported modes (product ad, 3-5 shot story, localized creative), which map directly to the `kind` enum. It does not, however, contrast itself against closely-related siblings like run_production_template or create_edit, so an agent must infer the boundary.

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

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

Gives concrete when-to-use context: product ads require passing the real product image as a reference and using extract_product_image or an upload first; localization requires the original creative, target language as a parameter, and preservation instructions. No explicit when-not-to-use or named alternative (e.g., run_production_template) is supplied.

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 no annotations, the description carries the full behavioral burden and delivers almost nothing: it does not say where a new scene is inserted (order default), whether locationRef is optional association, what permissions are required, or what is returned. For a mutation tool with zero annotation coverage this is a significant gap.

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

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

A single six-word sentence with no filler, front-loaded with the action. It is efficient but borders on under-specification rather than true conciseness.

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 with no annotations and no output schema, the description leaves out ordering behavior, defaults, and side effects. The schema covers parameter naming, but the agent still lacks the behavioral context needed to invoke this confidently.

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

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

Schema description coverage is 100%, so all five parameters (name, order, editId, locationRef, workspaceId) are already documented in the schema. The description adds no syntax, defaults, or semantics beyond it, which is the expected baseline 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 ("Create a new scene") and scopes it to an edit, so the operation is unambiguous. It does not distinguish itself from siblings like create_shot, create_edit, or duplicate_shot, but the core action is clear.

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

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

No guidance on when to use this versus create_shot or create_edit, and no prerequisites stated. "in an edit" faintly implies an edit context is needed, but the required workspaceId/editId relationship is left entirely to the schema.

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

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

With no annotations, the description carries the full burden. It does disclose genuinely non-obvious behavior: supplying prompt auto-creates a linked MediaDocV2, videoPrompt omission falls back to the visual image prompt, and dialogue is never auto-appended. It stops short of covering permissions, failure behavior, or ordering side effects on the edit.

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

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

Three short sentences, front-loaded with the core action and followed by two conditional behaviors. Every sentence adds information and none is filler, though the fallback sentence is terse enough to need the schema for full meaning.

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

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

For a 22-parameter mutation tool with nested objects, no annotations, and no output schema, the description covers only the prompt-related surface. Required IDs, default/derived fields (startTime, duration), and sibling selection are left entirely to the schema, leaving meaningful gaps.

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 22 parameters, establishing a baseline of 3. The description adds modest cross-parameter meaning (prompt vs videoPrompt fallback, dialogue separation) but does not clarify the nested mediaRefs/speedRamp structures or the linkStartToPrevEnd-style options.

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

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

States a specific verb and resource: 'Create a new shot in an edit.' An agent immediately knows what the tool produces. However, it never distinguishes itself from close siblings such as create_shot_with_media or duplicate_shot, so the agent must infer the boundary from names alone.

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

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

The description implies usage through the optional prompt/videoPrompt behavior, giving some sense of when to supply generation prompts. But it offers no explicit when-to-use versus create_shot_with_media, no prerequisites, and no mention that the three IDs are required.

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

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

With no annotations, the description carries the full behavioral burden and discloses important traits: asset resolution, prompt-formula application, immediate generation when references are ready, and queuing when they are not. It omits permissions, cost implications, or failure behavior, but covers the core conditional execution.

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

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

Two compact sentences, front-loaded with the core action and followed by the execution logic. Every clause adds useful information without repetition.

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

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

For an 11-parameter creation/generation tool with no output schema and no annotations, the description explains the key workflow and conditional generation path. It could go further by describing return values, permissions, or cost behavior, but it is sufficient for correct invocation based on the rich input schema.

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

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

Schema description coverage is 100%, so parameter documentation is already thorough in the schema. The description adds only high-level context about tagged assets and the prompt formula, not syntax or edge cases beyond the schema.

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

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

The description states a specific verb, resource, and scope: creating a shot with an image prompt in a single call. It also explains the internal workflow that distinguishes it from a plain create_shot sibling.

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 first sentence and workflow imply when to use the tool, but there is no explicit guidance on when to prefer it over siblings like create_shot or generate_shot_video, nor any stated exclusions.

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

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

With no annotations, the description carries the full behavioral burden. It usefully signals this is a mutation step that precedes node creation, but omits whether the new workflow's identifier is returned (critical for chaining into add_node), any permission requirements, and idempotency behavior.

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

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

Two short sentences, zero filler, with the core action front-loaded and the follow-up guidance second. Nothing to trim.

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

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

There is no output schema and no annotations, so the description should ideally say what is returned (notably the new workflow ID needed by add_node). The chaining hint partially compensates, but the return-value gap leaves it merely adequate for a mutation tool.

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

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

Schema description coverage is 100% for both parameters (title, workspaceId), so the schema already documents them. The description adds no format or constraint detail beyond the schema, making the baseline 3 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+resource ('Create a new workflow') and scopes it to a workspace, which cleanly separates it from get_workflow, list_workflows, and execute_workflow. It stops short of naming any sibling explicitly, so it earns a solid 4 rather than a 5.

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

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

It gives clear procedural context: after creation, use add_node and connect_nodes. That tells the agent how this tool fits in the workflow-building sequence, though it offers no when-not-to-use guidance or alternative creation paths.

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

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

No annotations are provided, so the description carries the full behavioral burden, and it discloses almost nothing: not whether the caller needs permissions, not whether the new workspace becomes active/selected, not whether the operation is idempotent, and not what happens to existing state. 'Create' implies mutation, but none of the mutation's consequences are described.

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

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

A single front-loaded sentence with zero filler; the verb and resource lead, and the parenthetical clarification is the only extra word. Nothing is padded or buried.

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

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

With no annotations and no output schema, the description should say more than it does for a creation tool: what the created workspace looks like on return, whether it is scoped to a user/account, and how it relates to sibling containers. As written, an agent can call it but cannot predict the result.

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

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

Only one parameter (title) exists and schema description coverage is 100%, so the schema fully documents it. The description adds no format, length, or uniqueness constraints beyond the schema, which is the expected baseline when the schema already does the work.

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

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

States a specific verb and resource ('Create a new workspace') and adds a clarifying gloss ('project container') that tells an agent what a workspace actually is. It does not, however, differentiate itself from the many sibling creation tools such as create_production, create_folder, or create_edit, so an agent must infer which container to create.

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

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

There is no guidance on when to create a workspace versus a production, folder, or scene, and no prerequisites or sequencing hints. The agent gets a definition of the object but nothing about when this tool is the right call.

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 no annotations provided, the description carries the full behavioral burden. It discloses a key side-effect boundary: referenced media documents are not deleted, which is important for a destructive operation. However, it omits whether deletion is reversible, permission requirements, and error behavior for referenced assets.

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

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

Two short, front-loaded sentences with no filler. The scoping caveat is appropriately placed second. It could be slightly more efficient but wastes nothing.

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

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

For a destructive tool with no annotations and no output schema, the description is minimal but covers the core action and one important side-effect boundary. It leaves gaps around permissions, reversibility, and failure modes, which an agent might need for safe operation.

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

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

Schema coverage is 100%, so both parameters (workspaceId, assetId) are already fully documented in the schema. The description adds no parameter-specific meaning beyond the schema, so baseline 3 applies.

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

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

States a specific verb (Delete) and resource (asset from a workspace), and crucially clarifies a distinction from other delete siblings: referenced media documents are NOT deleted. This scoping detail differentiates it from more invasive delete tools.

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

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

The description implies usage for asset deletion but offers no explicit when-to-use guidance, alternatives (e.g., update_asset vs delete_asset), or prerequisites such as whether the asset must be unreferenced or reviewed first.

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

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

No annotations are provided, so the description carries the full behavioral burden. It helpfully discloses that the underlying media document is preserved, but it omits whether the deletion is reversible, what permissions are required, and what the response contains.

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

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

Two short sentences that are front-loaded and free of waste. The preservation note earns its place by clarifying destructive scope.

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?

Adequate for a three-parameter mutation tool with full schema coverage and no output schema. However, the lack of any usage guidance or reversibility/permission context leaves gaps for an agent deciding whether and how to invoke 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 100%, so the schema already documents workspaceId, editId, and trackId. The description adds no syntax or format detail beyond what the schema provides, meriting the baseline 3.

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

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

States a specific verb and resource ('Delete an audio track') and scopes it to 'the edit timeline', which identifies the domain and distinguishes it from media-level deletions like delete_asset.

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

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

No when-to-use guidance or alternatives named. Siblings like update_audio_track and list_audio_tracks exist but the description doesn't route the agent to them, nor does it state prerequisites such as the track first existing.

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 no annotations, the description carries the full burden. It says 'delete' but discloses nothing about reversibility, required permissions, whether removing by source/target node deletes multiple edges at once, or behavior when the edge does not exist.

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

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

A single front-loaded sentence with zero filler. However, for a destructive tool with three alternative deletion modes, this brevity shades into under-specification rather than tightness.

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?

A mutation tool with no annotations and no output schema, where the description omits the crucial point that edgeId and the node-based parameters are competing deletion strategies. An agent could pass conflicting parameters without warning.

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

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

Schema description coverage is 80%, so the schema already explains edgeId, workspaceId, sourceNodeId and targetNodeId. The description adds only the conceptual framing that a connection links two nodes; it adds no syntax or selection logic beyond the schema.

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

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

States a specific verb+resource ('Delete a connection (edge)') and clarifies the ambiguous term 'connection' with 'edge'. It is distinguishable from delete_node and connect_nodes, though it doesn't explicitly name those siblings.

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

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

No guidance on when to use this versus delete_node, delete_transition, or connect_nodes, and no indication that the three delete modes (by edgeId, by sourceNodeId, by targetNodeId) are mutually exclusive alternatives.

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

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

With no annotations, the description bears the full burden of behavioral disclosure, yet provides none. It doesn't state whether deletion is permanent, what happens to connected edges, whether it requires specific permissions, or what side effects occur. 'Delete' implies destruction but nothing beyond that.

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, economical sentence that is front-loaded with the action. There is no wasted text, but the brevity reflects under-specification rather than optimal conciseness.

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, three-parameter operation with no annotations and no output schema, the description is completely inadequate. It omits essential information about scope, side effects, permissions, and error conditions, leaving the agent without the context needed to invoke it safely and 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 three required parameters with only 33% description coverage (only workspaceId is described, as 'The workspace ID'). The description adds no meaning for nodeId or workflowId, and doesn't explain the relationship between them or the hierarchical scoping (workspace > workflow > node). It fails to compensate for the low schema coverage.

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

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

States a specific verb and resource ('Delete a node from a workflow'), which is marginally clearer than a tautology. However, it provides no differentiation from the many sibling delete_* tools (delete_connection, delete_transition, delete_audio_track, etc.), and doesn't clarify the context (workflow graph node vs. other node types). It's essentially a minimal restatement.

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 usage guidance whatsoever. The description doesn't say when to use this tool, what conditions must be met (e.g., node must exist, workflow must be editable), or what alternatives exist (e.g., delete_connection for edges).

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

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

No annotations are provided, so the description carries the full behavioral burden. 'Delete' implies destruction, but the description does not state whether the deletion is permanent, whether it cascades, what permissions are needed, or what happens to dependent track data.

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

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

The definition is a single, front-loaded sentence with no wasted words. It is efficient, though its brevity contributes to gaps in behavioral and usage detail.

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

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

For a destructive mutation with four required parameters, no annotations, and no output schema, the description is too sparse. It omits side effects, permission requirements, and any indication of how the call relates to sibling item-management 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?

Schema description coverage is 100%, with all four required IDs documented in the input schema. The description adds no parameter meaning beyond the schema, so the baseline of 3 applies.

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

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

The description states a specific verb and resource: 'Delete an overlay item from a track.' This clearly distinguishes the item-level deletion from the sibling delete_overlay_track, though it does not explicitly name that alternative or contrast the two scopes.

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

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

No when-to-use guidance, no alternatives, and no prerequisites are given. The agent must infer that this is a destructive edit operation and that update_overlay_item or move_overlay_item_to_track should be used instead for non-deletion changes.

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

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

No annotations are provided, so the description carries the full burden. It does disclose the key behavioral trait — the call fails if items exist unless deleteItems=true — and that a cascade delete of child items occurs. It omits other relevant behavior: irreversibility, required permissions, and side effects on the parent edit.

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

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

Two tight sentences, zero filler, with the core action front-loaded and the failure condition placed immediately after the parameter that controls it.

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 call with no output schema and three schema-documented required IDs, the description covers the critical trap an agent must avoid (silent failure vs. cascade deletion). It stops short of warning that this delete is destructive and likely irreversible, which would be valuable given no annotations.

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 goes beyond the schema by explaining the consequence of deleteItems (failure when omitted, cascade deletion when set), which the schema's one-line description does not convey. Required IDs remain schema-documented only.

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

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

States a precise verb+resource ("Delete an overlay track") with no ambiguity, and the resource name distinguishes it from nearby siblings such as delete_overlay_item, delete_audio_track, and delete_transition. An agent can identify the operation 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 genuine conditional guidance for invoking it: set deleteItems=true to remove items too, otherwise the call fails. However, it offers no guidance on when to choose this tool over alternatives (e.g., delete_overlay_item for individual items, or update_overlay_track), so usage is implied rather than fully routed.

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 no annotations, the description carries the full behavioral burden. It usefully discloses the key side effect that referencing shots become orphaned, which is genuinely valuable context beyond the schema, but it omits whether deletion is permanent/undoable, whether it cascades, or whether special authorization is needed.

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

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

Two short sentences with zero filler; the core action is front-loaded and the side-effect caveat follows immediately. Every sentence earns its place.

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

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

For a simple 3-parameter delete with no output schema and no annotations, the description covers the action and the main side effect, but leaves out irreversibility, permissions, and downstream reference handling. It is adequate but not fully self-sufficient.

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

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

Schema description coverage is 100%, so the schema already documents workspaceId, editId, and sceneId. The description adds no format, constraint, or relationship detail beyond implying that a scene belongs to an edit, 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 gives a specific verb and resource ('Delete a scene from an edit'), which clearly separates it from siblings like delete_shot, delete_asset, or update_scene. It does not explicitly name an alternative tool, so it stops short of full sibling routing.

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

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

There is no statement of when to use this tool versus alternatives (e.g., update_scene to detach shots first) and no prerequisites such as required permissions. The orphan note describes a consequence, not a usage condition, so an agent gets no routing guidance.

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

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

No annotations are provided, so the description carries the full behavioral burden. It does disclose one genuinely useful non-obvious trait: deletion does not cascade to linked media, which persists in the workspace. However, it omits irreversibility, permission requirements, and what happens to shot ordering or scene references after deletion.

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

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

Two short sentences, zero filler, with the core action front-loaded and the important caveat immediately after. Nothing is wasted and nothing critical is buried.

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

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

With no annotations and no output schema, a destructive delete tool should ideally state irreversibility, error behavior, and any auth requirements. The description covers the key non-cascade semantics but leaves the rest of the destructive-operation profile 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 description coverage is 100% — all three required parameters (workspaceId, editId, shotId) are documented in the schema itself. The description adds no additional parameter meaning, so the baseline of 3 is appropriate.

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

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

The description states a specific verb and resource ("Delete a shot") and immediately scopes the blast radius by clarifying that linked media documents are not removed. It does not explicitly name a sibling to contrast with, but the non-cascade note implicitly separates it from tools like delete_shot_media_ref or delete_asset.

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

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

There is no statement of when to use this tool versus alternatives (e.g., delete_scene, delete_shot_media_ref, or moving a shot instead of deleting it), nor any prerequisites such as permissions or required prior state. Usage is only implied by the verb.

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

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

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses the cascading side effect of clearing imageMediaId/videoMediaId, but that sentence largely restates the schema's clearPrimaryMediaId description, and it says nothing about irreversibility, error behavior when no ref matches, or authorization requirements 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?

Two tight sentences with the core delete action front-loaded and the side effect second. No filler, though the second sentence duplicates the schema's clearPrimaryMediaId wording rather than earning its place with new information.

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

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

For a six-parameter destructive tool with no annotations and no output schema, the description covers the primary action and the main cascade, but omits irreversibility, failure modes, and permission requirements. Adequate but with clear gaps given the tool's complexity.

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

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

Schema description coverage is 100%, so all six parameters are already documented, and the enum values for role are enumerated in the schema. The description references mediaId, role, and the clear behavior but adds no format, default, or interaction detail beyond what the schema already states, so the baseline 3 applies.

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

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

States a specific verb and resource ('Delete shot media refs') plus the matching criteria (mediaId and optional role), which cleanly separates it from add_shot_media_ref and update_shot_media_ref. It does not explicitly name those siblings, so an agent must infer the distinction from the verb, but the action is unambiguous.

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

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

Usage is implied by the matching semantics (delete refs for a given mediaId, optionally narrowed by role), but there is no explicit when-to-use guidance, no mention of when to prefer update_shot_media_ref, and no stated prerequisites such as required permissions or edit/shot ownership.

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

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

No annotations are provided, so the description carries the full behavioral burden for a destructive mutation. 'Delete' implies irreversibility, but the description does not state required permissions, whether the deletion can be undone, or what happens to the timeline after removal. It adds only the two identification modes, which is thin for a delete 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?

A single front-loaded sentence with zero filler that conveys verb, resource, cardinality, and targeting options. Nothing to trim.

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?

Parameters are fully covered by the schema, so the main gap is behavioral: with no annotations and no output schema, the description should say more about the consequences of deletion and error conditions. It is adequate but leaves the agent guessing about a destructive operation.

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

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

Schema description coverage is 100%, so each parameter is already documented, giving a baseline of 3. The description does add one useful relational detail — that a transition can be targeted by either transitionId or boundaryId — but it does not explain when to prefer one over the other.

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 ('Delete one timeline transition') with the scope clearly bounded to a single item. It does not explicitly differentiate itself from the sibling tools update_transition and add_transition, but the verb+resource pair 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?

There is no when-to-use or when-not-to-use guidance, no mention of prerequisites, and no reference to alternatives such as update_transition or add_transition. Usage is only inferable from the tool name itself.

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

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

No annotations are provided, so the description carries the full burden. The key behavioral disclosure — 'Media documents are referenced, not copied' — is valuable since it tells the agent the duplication is shallow, avoiding wasted copies. However it says nothing about permissions, side effects on the source shot, or whether the new shot gets a fresh ID.

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 sentence that front-loads the action and lists the carried-over attributes compactly, with the shallow-copy caveat as a tight second sentence. Zero 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?

Adequate for a shallow-copy tool with a fully-covered schema and no output schema. It does not cover where the duplicate lands by default, required permissions, or return value, which for a creation tool with no annotations leaves gaps.

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 five parameters including the optional destination sceneId and order. The description adds nothing about parameter behavior, so baseline 3 applies.

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

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

States a specific verb+resource ('Duplicate a shot') and enumerates exactly which attributes carry over (media refs, trimming, playback, frame-linking, prompts, dialogue, tags). It is immediately distinguishable from update_shot, create_shot, and split_shot.

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

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

Usage is implied by the verb, but there is no explicit when-to-use vs create_shot (which also produces a new shot) or split_shot. The default destination (same scene as source) and required workspace/edit context are not stated.

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

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

With no annotations, the description carries the behavioral burden and does well: it discloses non-destructiveness ('Creates a new version on the media doc — the original is preserved') and names the underlying model. It does not mention latency, cost, or rate limits, keeping it below 5.

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

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

Four tight sentences, zero redundancy. Purpose comes first, then required inputs, then a behavioral guarantee, then a usage constraint — well front-loaded and highly readable.

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

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

For a 4-parameter mutation-style tool with no annotations and no output schema, the description covers purpose, inputs, non-destructiveness, and usage limits. It does not explain the return value (a new media version ID would be useful) but is otherwise complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds narrative context around mediaId ('the image to edit') and editPrompt ('describing what to change'), and notes the model parameter has a default, which is slightly more than the schema alone 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?

Specific verb+resource: 'Edit an existing image using AI', with the required inputs (media ID + text prompt) named. It clearly distinguishes itself from siblings like generate_image (new image) and edit_video (video editing) by scoping to existing images.

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

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

Explicit when-to-use guidance: 'Use sparingly — only when the user explicitly asks to modify an existing image.' This is a strong, actionable exclusion criterion that routes the agent correctly and prevents over-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=false, openWorldHint=true, destructiveHint=true, idempotentHint=false, so the safety/mutation profile is covered structurally. The description adds real value by stating the source clip is preserved and that a tracked task with a playable result is returned, but it says nothing about cost exposure, failure/credit behavior, or what the destructive annotation actually implies for the caller.

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

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

Four short sentences, front-loaded with the core operation and followed by the two facts an agent most needs (non-destructive output, model catalog pointer, async result). No filler, though the closing return-value sentence is mildly redundant given the output 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 21-parameter async generation tool with a documented output schema and full annotations, the description covers the essentials: what it does, the non-destructive guarantee, and where to get valid model/settings values. The dense optional parameters (resolution, aspectRatio, referenceImages, idempotencyKey) are left entirely to the schema, which is acceptable at this coverage level.

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 81%, so the schema already documents model, sourceMediaId, prompt, mediaInputs, scaleFactor, and the rest; the baseline of 3 applies. The description only echoes the source-video-plus-prompt inputs and points at get_model_catalog, adding no syntax or format detail beyond the schema.

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

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

States a specific verb and resource (edit existing footage from a source video plus prompt) and adds the important scope fact that it produces a separate result while the original is preserved. It does not explicitly differentiate itself from close siblings such as enhance_video_media, expand_video, or upscale_video, which keeps it short of a 5.

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

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

It gives one concrete routing rule — call get_model_catalog to pick a supported model and its settings — which is useful. But it never says when to choose this tool over generate_video, enhance_video_media, or upscale_video, so the agent must infer the boundary from names alone.

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

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

No annotations are provided, so the description carries the full behavioral burden, and it discloses almost nothing beyond the operation being a processing pass. It doesn't say whether the job is synchronous or asynchronous, whether it consumes credits, whether it mutates the existing media or produces a new asset, or what model-parameter behavior to expect from extraParams.

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

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

Two short sentences with the operation front-loaded and no filler. The second sentence is somewhat of a feature dump that duplicates the schema, keeping it just short of maximum efficiency.

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 complex tool: 14 parameters, a free-form nested extraParams object, no output schema, and no annotations. The description supplies none of the missing context an agent needs to invoke it confidently, such as job lifecycle, result handling, or how the enhancement pass relates to the resulting media version.

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 14 parameters are already documented in the schema, and the baseline is 3. The description's feature list (upscale, HDR, output codec, bit depth, scale factor, arbitrary model parameters) largely restates schema fields rather than adding format, default, or interaction semantics beyond them.

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

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

The description states a specific verb and resource ('Run a video editor enhancement pass on a workspace video media item') and enumerates the enhancement capabilities it covers. It is clear on its own, but it never distinguishes itself from close siblings like upscale_video, convert_video_to_hdr, and expand_video, which the listed capabilities directly overlap with.

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

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

There is no when-to-use, when-not-to-use, or alternative-routing guidance. The second sentence reads as a capability list ('Supports upscale, HDR, output codec...') rather than a condition that selects this tool over upscale_video or convert_video_to_hdr, so the agent must infer when this composite pass 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?

No annotations are provided, so the description carries the full burden. To its credit it discloses the most consequential trait — the tool is legacy and non-functional for execution. However it omits anything about the return payload, authentication, error behavior, or whether calling it has side effects, which matters for a zero-annotation tool.

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

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

Three short sentences, zero waste, and the deprecation warning is front-loaded before the alternatives. 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?

With no annotations and no output schema, the description must do more than redirect. It adequately warns the agent off and points to replacements, but leaves the return value, failure modes, and the meaning of the second required parameter unspecified.

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

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

Two required parameters at 50% schema coverage: workspaceId is documented in the schema, workflowId is not. The description adds no meaning to either — no format, no relationship between workspace and workflow, no indication that IDs must reference an existing graph. It fails to compensate for the coverage gap.

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

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

The description states a specific action ("Check graph execution availability") and immediately clarifies the misleading name by declaring this a legacy tool that cannot run graphs. It distinguishes itself from siblings by naming run_production_template and the workflow API. Point deducted because the tool name still implies execution, and the description never says what the availability check actually 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?

It explicitly redirects the agent: use run_production_template for reusable productions, or the authenticated workflow API for published graph endpoints. That is concrete routing guidance. It stops short of stating the narrow condition under which this tool itself should still be called.

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

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

Annotations already cover the safety profile (readOnlyHint=false, destructiveHint=true, idempotentHint=false, openWorldHint=true). The description adds value beyond them: the 120s/500MB envelope, that output arrives as a tracked task with a playable result when complete, and which models are supported. It does not explain what 'destructive' means here or the cost/retry semantics, which the schema's idempotencyKey description partly carries.

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

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

Front-loaded with the operation and hard limits, then capabilities, then prerequisites and model list. Five sentences, no filler; the model enumeration is long but directly actionable for the required 'model' parameter.

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 22-parameter, nested-schema, open-world generation tool, the description supplies the constraints (time/size), model compatibility, prerequisite for SwitchFrame, async return shape, and the catalog lookup for settings. With a 22-property schema and an output schema present, nothing essential is left unexplained.

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

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

Schema coverage is already high (82%), so the baseline is 3; the description still adds meaning by naming the five valid models and the beeble-switchframe requirement on mediaInputs.reference_image_uri, plus the duration/size limits tied to the duration parameter. It does not clarify the many optional URL-vs-mediaId alternatives, which the schema covers.

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 ('Run the Reframe preset on a complete workspace video'), then enumerates the actual operations (outpaint aspect ratio, join provider chunks, restore audio). This clearly separates it from siblings like edit_video, generate_video, and enhance_video_media without needing to open any schema.

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

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

Gives actionable context: 'Call once per requested source/format/settings variant', 'Use get_model_catalog to choose a supported model', and the SwitchFrame prerequisite for mediaInputs.reference_image_uri. It does not explicitly contrast with the closest siblings (edit_video, upscale_video, enhance_video_media), so routing between them still requires inference.

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

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

With no annotations, the description carries the full burden, but it does add real behavioral detail: it creates an export record, invokes export-project-v2, runs synchronously, and returns preview/download/project URLs. It omits permissions, cost/credit implications, and failure modes, so the disclosure is useful but incomplete for a mutation tool.

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

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

Three tight sentences, front-loaded with the action and followed by mechanism and usage. No filler, though the mechanism sentence ('calls export-project-v2') is arguably internal detail that could be trimmed.

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

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

There is no output schema, so the description correctly steps in to name the return values (video preview, download, and project URLs) and describes the synchronous flow. For a 7-parameter tool with a nested settings object, this is nearly complete, missing only cost/auth context.

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

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

Schema description coverage is 100%, so the schema already documents all seven parameters including the nested exportSettings object. The description adds no parameter-level meaning beyond the schema, which is the baseline 3 when structured data 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 ('Start a production export for an edit') and distinguishes itself from read-oriented siblings like get_export and list_exports by describing it as a starting/production action. An agent can tell what it does without opening the schema.

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

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

The trailing sentence 'Use these links for final delivery' implies the tool's purpose (final delivery output) but never states when to choose it over get_export or list_exports, nor any prerequisites. Usage is implied rather than explicit.

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

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

The annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so safety behavior is covered. The description adds useful extraction behavior about preferred structured data and failure handling, but it does not explain permissions, rate limits, or what happens during partial extraction.

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 short and front-loaded with the core action. The phrase about page_preview is somewhat cryptic, but the overall three-sentence structure is efficient and avoids unnecessary 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?

It covers the basic purpose, extraction preference, and failure fallback, which is useful for a read-only annotated tool. However, with no output schema and no parameter descriptions, it leaves workspaceId semantics and return behavior unresolved.

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 0% and the description does not explain either required parameter meaningfully. It implies productUrl from 'product URL' but says nothing about workspaceId, leaving half the required parameters undocumented beyond the schema's raw types.

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-resource pair: find a product image from a product URL. It is clear enough to distinguish extraction from generation or editing tools, but it does not explicitly name sibling alternatives or fully clarify what 'find' 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?

It gives some when-to-use context, including preferring Product structured data and falling back to upload or direct image URL if extraction fails. However, it does not name the fallback tools or specify when this tool should be avoided in favor of siblings.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the paid/generative nature is covered structurally. The description adds the model-resolution precedence ('An active skill's explicit model still takes priority') and the workspace-defaulting behavior, but those largely restate the model and workspaceId schema descriptions, and it never states outright that this starts a billable generation.

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

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

Purpose and trigger conditions are front-loaded in the first two sentences, which is the right ordering for a router-style tool. The trailing sentences about default models and workspaceId partly duplicate the schema, adding mild redundancy, but the text stays free of filler.

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

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

With an output schema present, return values need not be explained, and the description covers provider coverage, default model fallback, skill precedence, and workspace defaulting. It leaves cost behavior and the interaction between voiceId/stylePrompt and specific model families to the schema, which is acceptable but not exhaustive for a paid, destructive generation tool.

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

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

Schema description coverage is 100%, so all eight parameters are already documented in the schema, making 3 the baseline. The description reinforces model defaults and workspaceId omission, and adds the skill-priority rule, but contributes no syntax or format detail beyond what the schema already 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+resource ('Generate AI audio through Sequencer') and enumerates the modalities it covers: speech, voiceover, narration, music, song, sound effects. It does not, however, differentiate itself from close siblings such as generate_audio_track or generate_video_audio, so an agent still has to infer which generator to pick for timeline- or video-scoped audio.

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

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

It gives strong positive routing: 'Use this whenever the user asks to make, create, generate, or render speech, voiceover, narration, music, a song, or a sound effect with Sequencer or names an audio/music model/provider Sequencer supports.' It also names the supported providers and the default model resolution rule. What is missing is any when-not guidance relative to the adjacent audio 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?

No annotations are provided, so the description carries the full behavioral burden. It reveals that this is a mutating generation-and-placement operation and that IDs are returned, but it omits permissions, asynchronous generation behavior, effects on existing timeline audio, and failure modes for a 14-parameter write tool.

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

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

The description is two tightly structured sentences with no redundancy. The core action is front-loaded, and the return-value note is secondary.

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

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

With no annotations and no output schema, the description helpfully states the return IDs, but it is thin for a complex 14-parameter mutation tool. It does not provide enough behavioral or usage context for an agent to know when and how to invoke it confidently against alternatives.

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 input schema already explains all 14 parameters. The description adds no parameter-level detail beyond noting that IDs are returned, making the baseline 3 appropriate here.

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

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

The description gives a specific verb and resource: 'Generate AI audio' and 'place it on the edit audio timeline.' The 'immediately place' phrase distinguishes it from siblings like generate_audio and add_audio_track, so an agent can identify its role without opening the schema.

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

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

It implies use when an agent needs generated audio placed directly on the timeline, but it never states when to choose this over generate_audio, generate_video_audio, or add_audio_track, nor does it give exclusions or prerequisites.

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, openWorldHint=true, and non-idempotent behavior, so the safety profile is covered structurally. The description adds the default-model behavior (Nano Banana Pro / google-gemini-3-image) and the default-workspace behavior, but says nothing about cost/credit implications or what happens to existing edits — context the schema carries instead. With annotations doing the heavy lifting, 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?

Front-loaded with the core action and routing rule; the long model enumeration is bulky but each entry is a legitimate disambiguation cue for an agent matching user language. The two fallback defaults are placed at the end where they belong.

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 23-parameter, nested-object tool with an output schema and near-total schema coverage, the description supplies the missing decision layer — when to pick this tool and what defaults apply — without duplicating field documentation. Only the cost/credit aspect of a paid generation is left to the schema.

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

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

Schema description coverage is 96%, so the baseline is 3, but the description adds genuinely new semantics: the concrete default model ID when none is specified, the default workspace fallback, and a pointer to get_model_catalog for alias resolution. That is real value beyond the schema's own field text.

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

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

Starts with a specific verb+resource ("Generate an AI image through Sequencer") and enumerates the exact model families it can target, which cleanly separates it from edit_image, render_image, generate_video, and upscale_image in the sibling list. An agent can identify the tool's job without opening the schema.

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

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

Gives explicit trigger conditions ("whenever the user asks to make, create, or generate an image... or names an image model/provider"), names the alternative to prefer against (built-in image generation), and provides a fallback path (use get_model_catalog when an alias is unclear). This is genuine when/when-not routing.

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

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

With no annotations provided, the description carries the behavioral burden and does disclose meaningful side effects: it uploads to Cloud Storage, writes a report reference to Firestore, and returns a download card marker. That is substantive for a write/mutation-style tool. It still omits permission requirements, idempotency, and failure behavior.

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

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

Two tightly written sentences, front-loaded with what the tool produces and immediately followed by the side effects and return artifact. No filler or restated name/title.

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

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

Given 9 parameters, no annotations, and no output schema, the description usefully discloses the persistence targets and the returned artifact ('report download card marker'), which substitutes for a return-value schema. It is close to complete, though it could state prerequisites and error/rate-limit behavior.

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

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

Schema description coverage is 100% with 9 well-documented parameters (including two enums), so the schema already does the heavy lifting. The description adds no parameter-level detail beyond implicitly pointing at the analyze_export_ip outputs, so the baseline 3 applies.

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

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

States a specific verb+resource ('Generate a formal HTML IP compliance report') and names the upstream data source ('from analyze_export_ip findings'), which cleanly separates it from the sibling analyze_export_ip that only produces findings. An agent can identify this tool without opening its schema.

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

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

The phrase 'from analyze_export_ip findings' implies the tool is used as a follow-up step after analysis, which is useful contextual routing. However, there is no explicit when-to-use/when-not statement, no prerequisite spelled out (e.g. 'call analyze_export_ip first'), and no mention of alternatives or conditions.

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 no annotations, the description carries the full burden and does disclose key behavior: it 'preserves the shot still as the source frame, replaces the prior primary video reference, and keeps the result inside the edit.' This tells the agent about source frame handling, that a prior primary video reference is replaced (mutation side effect), and the scoping. It does not mention rate limits, error conditions, or whether other shot media refs are affected.

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

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

Two sentences, front-loaded with the core action and scope, followed by behavioral effects. No filler words and 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 generation tool with 9 params, full schema coverage, and no output schema, the description covers purpose, usage context, and key side effects. It is slightly short on explicit alternatives to route against siblings like generate_video and generate_video_audio, but overall completeness is strong.

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 9 parameters with semantics (model, prompt, duration, volume, etc.). The description adds no parameter-specific detail beyond what the schema provides, 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+resource ('Generate a video for one existing edit shot') and immediately distinguishes scope ('attach the queued media to that shot immediately'), separating it from standalone video tools like generate_video. The phrase 'inside the edit instead of presenting it as standalone media' explicitly differentiates 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?

The description gives clear context: 'Use this for project and timeline builds,' which guides when to use it versus standalone generation. However, it never names specific alternatives (generate_video, run_video_workflow) or states exclusions, so it lacks the explicit when-not guidance needed for a 5.

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