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?

No annotations are provided, so the description carries the full burden for a 26-parameter mutation. It lists feature areas but says nothing about reversibility, permissions, whether it creates a track (that detail lives only in the schema), or what the operation returns, leaving meaningful behavioral gaps.

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

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

It is a single sentence with the verb and resource front-loaded. The trailing feature list is packed but each item signals a real capability area, so it earns most of its length.

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

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

For a 26-parameter mutation tool with no annotations and no output schema, the description is thin: it omits return behavior, failure modes, and routing to the text/remotion overlay siblings. The extensive schema mitigates this somewhat, making it minimally adequate rather than complete.

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

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

Schema description coverage is 100%, so the schema already documents every parameter, including unit conventions (720p logical pixels, normalized coordinates) and legacy shorthands. The description's feature list loosely maps to parameter groups but adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

The description states a specific verb (Add) and resource (image or video media overlay) and names the target (the edit timeline). The 'image or video' qualifier implicitly distinguishes it from the sibling add_text_overlay and add_remotion_overlay, so an agent can route without opening a schema.

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

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

There is no explicit when-to-use, when-not-to-use, or alternatives guidance. The description never mentions add_text_overlay, add_remotion_overlay, or add_overlay_track, leaving the agent to infer selection from tool 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 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?

Discloses several behavioral traits beyond the annotations: atomic staging, required current SHA-256 hash, oldText matching exactly once, preservation of unrelated source, invalidation of earlier checks (optimistic concurrency), and the explicit non-persistence guarantee. The annotations only cover the safety profile (readOnly=false, destructive=false), so this description carries and adds substantial context.

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

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

Front-loads the core action, then requirements, then the critical 'never saves or publishes' caveat, then the optional asset attachment. Dense but each sentence earns its place; the last sentence is slightly compressed and could be clearer about when attachment applies.

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-param, 0%-coverage, no-output-schema tool this covers the essential mechanics (atomicity, hash, match-once, non-persistence). It does not describe what a staged patch returns or how expectedRevision interacts with the invalidation it mentions, leaving a modest gap.

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

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

With 0% schema description coverage the description must compensate, and it adds real meaning to the core patch fields ('current SHA-256 hash,' 'nonempty oldText matching exactly once,' 'create:true only for a new file') that the schema does not express. It leaves top-level workspaceId/codeWorkspaceId/expectedRevision and the interfaceAssets/previewImageUrl shapes largely unexplained, so compensation is partial.

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 ('Stage exact code replacements atomically') and explicitly carves out scope against the save/publish siblings with 'This never saves or publishes a world.' An agent can distinguish it from save_world_code_workspace and read_world_code_file without opening a schema.

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

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

Gives concrete conditions: 'Use create:true only for a new file,' 'Include context for ambiguous matches,' and attaches interface assets only 'when approved generated images are ready.' It implies the when-not (staging vs saving) but never explicitly names the alternative tool to use for persisting changes, so it stops short of full routing guidance.

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

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

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 full burden and does disclose key non-obvious behavior: character/location/prop prompts trigger reference-image generation while style assets do not, and existingMediaUrl skips generation. It omits permissions, cost, or failure behavior, but the generation-vs-no-generation distinction is valuable side-effect disclosure.

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

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

Three short sentences, front-loaded with the core action and followed by the two behaviorally important qualifications. No filler, though it could be tightened slightly.

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, no-annotation, no-output-schema tool, the description covers the high-risk behavioral points (image generation, style handling, reference-image attachment). It leaves the editId/edit-context requirement entirely to the schema, which is acceptable given 100% coverage but is a notable structural gap.

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

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

Schema description coverage is 100%, so the schema already documents all 12 parameters, making 3 the baseline. The description reinforces existingMediaUrl semantics and the style/prompt interaction, but adds little beyond what the schema already states.

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

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

States a specific verb (create) and resource (asset) and enumerates the asset types it handles (character, location, prop, style). This clearly separates it from siblings like update_asset, list_assets, and create_workspace 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?

Provides explicit when-not guidance by steering routine global visual style to edit.style instead of creating a style asset. However, it offers no routing against neighboring creation tools (create_scene, generate_image, import_media_from_url) or conditions for choosing each asset type.

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 supplied, so the description carries the full burden, and it does disclose meaningful behavior: aspectRatio is required because it governs every generated shot, the default image/video/speech models are named, and the return value (new edit ID) is stated despite there being no output schema. It does not cover permissions, billing/quota impact, or failure modes, which keeps it short of a 5.

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

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

Four sentences, front-loaded with purpose, then the required-parameter rationale, then defaults, then the return value. Every sentence carries information an agent needs and nothing is padded.

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

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

For a create tool with 100% schema coverage and no output schema, the description covers purpose, required input rationale, defaults, and the return value, which is sufficient to invoke correctly. It stops short of mentioning authorization requirements or what happens on invalid input, so it is complete but not exhaustive.

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

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

Schema description coverage is 100%, so the baseline is 3; the schema already documents every parameter, including the model defaults. The description restates the aspect-ratio rule and the model defaults, adding emphasis but little information beyond the schema. It also names a default speech model (cartesia-sonic-3-5) that has no corresponding parameter 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 ('Create a new edit (project) in a workspace') and parenthetically disambiguates 'edit' as a project, which matters given siblings like create_production, create_scene, and create_shot. 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 real guidance on choosing aspectRatio ('use 9:16 for vertical/social films unless the user asks for another format'), but offers no when-to-use guidance relative to alternatives such as create_production or create_workspace. Usage is implied by the 'new edit in a workspace' framing rather than stated.

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

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

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 readOnly=false, destructive=false, idempotent=false, openWorld=false. The description adds meaningful side-effect boundaries beyond that: creation is inert until the site is built and does not trigger paid generation or publishing. It does not mention permissions or what the created world's default state is.

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

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

Two tight sentences, front-loaded with the action and scope, followed by the continuation path. No filler or repetition.

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

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

For a create tool with no output schema, the description covers the key gap: the returned worldId and how to consume it, plus the crucial fact that creation alone publishes nothing. Only the parameter-level detail is thin.

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%, so the description carries the full burden, yet it only loosely names three fields ('title, URL, description') without format, length, or slug rules, and never mentions the required workspaceId. An agent must open the schema to learn that workspaceId/name/slug are required.

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 private hosted World') and scopes it as minimal. The field list ('title, URL and description') roughly maps to the name/slug/description params, though it omits workspaceId and uses different wording than the schema. It is distinguishable from generic create_* siblings but doesn't explicitly contrast with list_hosted_worlds or get_hosted_world.

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 next-step routing: read the returned worldId via get_hosted_world, then build the site and save via save_hosted_world_site. It also states an explicit exclusion ('does not publish or start paid generation'), which is genuine when-not guidance. No alternative creation tool is named, but the workflow context is clear.

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

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

Annotations only declare the non-read-only, non-destructive, non-idempotent profile. The description adds real behavioral context not present in structured fields: creation is private with public embedding disabled, no call is started, and concrete Anima defaults (fast mode, square orientation, visual stability 0.81, motion freedom 0.95) are disclosed. Missing only error/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?

Five short sentences with the purpose front-loaded, followed by defaults, privacy behavior and the next step. Dense and largely waste-free, though the closing 'Prepare the returned character ID next' is slightly clipped in phrasing.

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

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

For an 18-parameter mutating creator with no output schema and an entirely undocumented schema, the description does well on behavior (privacy, no-call, defaults, follow-up) but never addresses how the response is shaped or which required fields demand care. Adequate, with clear 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 0% across 18 parameters, so the description carries the entire burden, and it only partially pays it: it disambiguates image vs voice source and supplies defaults for animaMode, orientation and the animation settings. Required inputs such as name, systemPrompt and workspaceId, plus cerebro, language, openingLines, knowledgeText and maxSessionSeconds, are never explained.

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: 'Save a real live conversational avatar draft' from an image plus a catalog or custom voice. The 'draft' framing and 'Does not start a call' make it distinguishable from session tools. It never names or contrasts with update_live_avatar or prepare_live_avatar, so sibling differentiation is incomplete.

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 sequencing hints ('Does not start a call', 'Prepare the returned character ID next'), which tells the agent where this sits in the avatar flow. However, it does not state when to choose this over prepare_live_avatar or update_live_avatar, and no prerequisites are called out. 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?

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 full burden and does disclose the key behavioral trait: this is non-destructive — it creates a new version and preserves the original. It also names the underlying model. It omits auth/cost/async details, but the destructive-vs-safe distinction is the most important disclosure and it is present.

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

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

Front-loaded with the purpose, then usage constraints, then the non-destructive behavior and model. Every sentence adds information; the trailing model identifier is the only slightly expendable element, but it aids transparency.

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-param tool with no annotations and no output schema, the description covers purpose, usage, and the key behavioral outcome ('new version on the media doc'). It could say more about what the caller receives (e.g., a new media ID) and any async/auth requirements, but it is broadly complete.

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

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

Schema description coverage is 100%, so the schema already documents mediaId, editPrompt, model, and workspaceId. The description references the media ID and text prompt but adds no format or syntax beyond what the schema provides, matching the baseline of 3.

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

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

States a specific verb+resource ('Edit an existing image using AI') and scopes it to existing images, which naturally distinguishes it from generate_image, render_image, and upscale_image. The outcome description ('Creates a new version on the media doc') makes the operation 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?

Provides an explicit when-to-use constraint ('only when the user explicitly asks to modify an existing image') and a frequency warning ('Use sparingly'). It does not name a specific alternative to route to, but the 'existing image' scoping implicitly separates it from generation 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?

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 declare destructive, open-world, and non-idempotent behavior. The description adds valuable operational context: 120-second / 500 MB limits, provider chunk joining, audio restoration, model-specific constraints, and that it returns a tracked task and playable result. It does not discuss idempotency or cost enforcement beyond what the schema provides, but adds substantial behavior beyond annotations.

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

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

The description is dense but front-loads the core operation and constraints. Most sentences carry operational weight (limits, model support, special cases, return behavior). It is appropriately sized for a complex 22-parameter tool, though it could be slightly tightened.

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

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

Given the high parameter count, nested objects, and existing output schema, the description covers the critical operational details: preset behavior, size/duration limits, model-specific rules, and output nature. It does not need to explain return values because an output schema exists, but it leaves some parameters (e.g., idempotencyKey, maxCostUsd) 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 82%, so the baseline is 3. The description adds model-specific parameter meaning: LTX supports specific aspect ratios and should omit the prompt, SwitchFrame requires a workspace image in mediaInputs.reference_image_uri, and model selection should use get_model_catalog. These details help interpret several parameters beyond the schema text.

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

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

The description states a specific verb and resource ('Run the Reframe preset on a complete workspace video'), names concrete operations (outpaint, join chunks, restore audio), and provides size/duration bounds. It distinguishes the tool from generic video generation by emphasizing the Reframe preset and supported reframe models.

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

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

It gives clear context for use: supported models, LTX aspect ratio behavior, SwitchFrame's mediaInputs.reference_image_uri requirement, and the instruction to call once per variant. It also routes to get_model_catalog. It lacks an explicit comparison to sibling tools like edit_video or generate_video, so usage is clear but not fully alternative-aware.

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.