Valmera — agentic AI video editor

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

Annotations are minimal (readOnlyHint false, destructiveHint false), so the description carries the full burden. It discloses the morph mechanism, single-resolution constraint, audio/caption safety, zoom behavior, default duration, and the return of project identity – far beyond annotation coverage.

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

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

Dense but well-structured, front-loaded with project scope and core action. Every sentence adds value – no fluff, efficient use of space for the complexity.

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

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

Complete for a complex tool: explains behavior, parameters, alternatives, removal, and return value. No output schema, but description covers everything an agent needs to invoke it correctly.

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

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

Schema covers only 29% of parameters (project_id and motion_motif). The description explains at_output_s, ratio, duration_s (with range and default), zoom (default and effect), color, and motion_motif's purpose, comprehensively filling 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?

States a specific verb and resource: changes aspect ratio mid-video. Clearly describes the morph effect and distinguishes from whole-video tools (set_frame, auto_reframe) and the removal tool (remove_aspect_shift). 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?

Explicitly says when to use (mid-video aspect shifts) and names alternatives for whole-video changes and removal. Provides clear routing criteria, leaving no ambiguity about 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?

With no read-only/idempotent/destructive hints from annotations, the description carries the behavioral burden. It openly states captions are burned, scope is limited to the explicit project_id, and that style omission triggers deterministic preset selection. It does not explicitly mention reversibility or side effects on the source transcript, so a small gap remains against the ideal.

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 very long but well-organized with clear section markers for modes, presets, placement, emphasis, and production controls. Examples are concrete and useful. Minor redundancy around preset casing and placement rules slightly reduces conciseness, but every sentence contributes meaningful guidance for a complex tool.

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

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

Given the tool's complexity, the description is remarkably complete, covering mode selection, preset defaults, placement, emphasis, animation, and example payloads. It explicitly states the return value is project identity. It does not describe any error cases or output schema, but the absence of an output schema lowers the burden and the stated return value is adequate for a call-level understanding.

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 only 38% and several parameters have minimal schema descriptions, but the prose compensates thoroughly by explaining mode, items, style preset behavior, placement fields, emphasis handling, animation options, and production controls. Every major schema parameter is effectively documented in the description, even where the schema itself is sparse.

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

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

The description clearly states the tool adds/burns captions onto a project, with explicit modes for transcript-derived or dictated text. It distinguishes itself by emphasizing project-scoped behavior and returning project identity, making the primary purpose unmistakable relative to siblings like set_caption_style.

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

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

The description gives explicit guidance on when to use each mode, recommends 'from_transcript', explains default preset selection when style is omitted, and provides concrete examples for modern reels and dictated title cards. It also clarifies placement rules and when to supply emphasis_words or disable them, leaving little ambiguity.

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

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

Annotations provide no safety hints (readOnlyHint false, destructiveHint false), so the description carries the burden. It discloses 'built instantly', returns project identity, and describes motion behavior ('slow Ken Burns push'). It does not detail side effects on existing footage, but it adds useful behavioral context beyond the schema and does not contradict annotations.

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

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

The description is detailed but efficiently structured: scoping note first, then core behavior, use cases, parameter details, and alternatives. Each sentence adds value; however, it is somewhat long, but the density of information justifies the length.

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

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

With 7 parameters, no output schema, and minimal annotations, the description covers all parameter semantics, return behavior, scope, and alternatives. It also gives timing details and color syntax, making it complete for an agent to invoke correctly.

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

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

Schema description coverage is only 14% (only project_id described), yet the description explains every parameter: color format and default, color2 for gradient, direction enum, at_output_s as program seconds, duration_s shift, and motion effect. This fully compensates for the sparse schema, adding meaning to all parameters.

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

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

The description clearly states the tool's purpose: cutting to a solid or gradient color screen, with explicit exclusions ('NO text, NO image generation'). It distinguishes from siblings by naming add_title_card and add_text as alternatives for different needs. The verb 'cut' and resource 'colour screen' are specific.

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 use cases ('plain white/black flash, a coloured interstitial, or a gradient backdrop') and names alternatives with conditions ('For a card WITH a word on it use add_title_card'). Also clarifies scope ('acts only on the explicit project_id'), giving clear guidance on when to use versus 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?

With no meaningful annotation coverage (all hints false, no details), the description carries the behavioral burden and largely delivers. It discloses that the effect is 'Synthesized locally like the colour cards: NO image or video generation, always available, costs no generation credits', explains timing side effects ('everything after shifts later by duration_s'), and notes a non-obvious interaction ('No captions ever land on it (inserted media)'). No contradiction with the false annotations, which are consistent with a mutating effect.

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

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

The description is dense but every clause earns its place — scope, effect, cost profile, style enum, timing semantics, intensity, sound, and caption interaction are all covered with no repetition. It front-loads the core purpose and scope before parameter details. Slightly long, but the density is justified given the 6-parameter, low-coverage 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 6-parameter mutation tool with no output schema and 17% schema coverage, the description is nearly complete: it covers project scoping, style semantics, timing, duration, intensity, sound, and returns ('returns the project identity with its result'). The only minor gaps are default for duration_s and exact return shape beyond identity, which are acceptable given the absence of an output schema.

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

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

Schema coverage is only 17% (just project_id is described), so the description must compensate and does thoroughly: it defines all three style enum values ('digital' vivid datamosh macroblocks + horizontal tearing, 'vhs' tracking band + scanlines + chroma bleed, 'static' TV snow/no-signal), clarifies at_output_s is 'PROGRAM seconds', specifies intensity 0-1 with default 0.7, and sound default true. This adds real meaning beyond the bare schema.

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

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

The description uses a specific verb+resource (add + corrupt screen) and immediately explains the effect: 'Cut to a full-frame CORRUPT / glitch screen for a beat, then return to the footage — a datamosh-style transition BETWEEN sections.' This clearly distinguishes it from siblings like add_color_screen, add_freeze_frame, and add_screen_takeover by specifying its role as a transition between sections rather than a static insert.

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

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

The description gives clear usage context: it's a datamosh-style transition BETWEEN sections (e.g. 'podcast -> CORRUPT -> the next scene'), and offers timing guidance ('Keep it SHORT (0.3-1s reads as a hit; longer feels genuinely broken)'). It doesn't explicitly name sibling alternatives or state when NOT to use it, but the between-sections positioning provides strong contextual routing.

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

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

Annotations are minimal (all false flags), so the description carries the full burden of behavioral disclosure. It comprehensively reveals: project-scoping, return of project identity, dry-run behavior, error responses (ffmpeg's own error, measured cost for heavy chains), the requirement to preserve frame size/rate, and the caution to visually inspect the result. This is exceptionally transparent, going far beyond basic 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?

The description is dense but efficiently structured. It front-loads the scoping constraint, states purpose, provides presets routing, and then enumerates rules, parameter semantics, an example, and a post-action caution. Every sentence serves a distinct purpose; nothing is redundant. The length is justified by the tool's complexity.

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

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

For a complex, write-oriented tool with no output schema and low schema coverage, the description is complete. It covers purpose, constraints, error behavior, parameter meanings, and a follow-up verification step. An agent can correctly invoke the tool and anticipate outcomes without additional information.

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

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

Schema description coverage is only 33% (2/6 parameters have descriptions). The description compensates richly by explaining start/end (program seconds, omit for whole video), label (short human name shown in diffs), chain (syntax rules, example), and project_id context (explicit scope). It adds meaning beyond the schema for all key parameters, making the tool effectively usable.

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

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

The description clearly states the tool's function: 'WRITE YOUR OWN ffmpeg video filter chain and apply it to the program picture.' It explicitly differentiates from sibling tools by naming presets (apply_look, add_stylize, set_color_grade, enhance_video) and specifying when to use this custom filter instead. The purpose is unambiguous and distinct.

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

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

The description provides explicit guidance on when to use this tool vs alternatives: 'Presets FIRST... reach here when the user wants something none of them says.' It also gives concrete examples of custom looks and detailed rules for constructing the filter chain, including syntax constraints, error handling, and parameter semantics (start/end, label). This fully equips the agent with selection and invocation guidance.

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

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

The description discloses the exact visual behavior (frame stops, blurs, darkens, text burned and bound) and the two audio modes with their timeline effects. It also specifies that text and subtitle are burned centred, and provides parameter ranges, going well beyond the minimal annotation hints (which only indicate non-read-only). No contradiction with annotations.

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

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

The description is long but every sentence adds value, covering scoping, visual effect, parameter ranges, and audio behavior. It front-loads the project scoping constraint and then logically walks through the effect and options, making it dense yet efficient.

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

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

Given 13 parameters, no output schema, and no annotation details beyond non-read-only, the description covers the return value (project identity), the primary effect, all relevant parameter semantics, and both audio modes. It leaves little ambiguity for an agent to invoke it correctly, making it remarkably complete for its 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?

With only 8% schema description coverage, the description compensates by explaining at_output_s, duration_s, blur, darken, motion, text, subtitle, and audio_mode with concrete values and effects. It does not cover font, color, template, or accent_color in detail, but these are either enums or straightforward strings; the description adds significant meaning for the most impactful parameters.

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

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

The description clearly states a specific verb and resource: it freezes a frame, holds it, and optionally adds text. It distinguishes itself from other add_* tools by describing the unique 'pearl' move with blur, darken, and motion effects on the held frame, making its purpose unambiguous.

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

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

It gives explicit guidance on when to use each audio_mode: 'pause' for a real cut that shifts subsequent content, and 'continue' to hold the visual while audio continues. It also recommends duration_s 2-4s and provides typical blur/darken values, effectively telling the agent how to invoke it appropriately.

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 are all false (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), so the description carries the full burden. It discloses that the tool is project-scoped (only acts on explicit project_id), that it mutes bottom captions over its window to avoid duplication, that each phrase becomes a normal text item (inspectable via get_edl, removable via remove_text), and that motion_style has three distinct behaviors (composed, preset, still). It even warns that the agent should visually verify the zone after rendering and re-run if needed. This is exemplary transparency 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 long but well-structured, starting with the core purpose, then usage context, then parameter behavior, then post-render workflow. Every sentence adds value; there is no filler. It is not concise in word count, but it is efficiently organized and front-loaded with the most critical information. The length is justified by the tool's complexity (11 parameters).

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

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

For a tool with 11 parameters, no output schema, and no nested objects, the description is remarkably complete. It covers purpose, usage conditions, parameter semantics, behavioral side effects (caption muting, text item creation), and even the verification workflow (look at frames, re-run with another zone). It also explains how to inspect or remove the generated text items. Nothing essential for correct invocation or post-call evaluation 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 only 18%, so the description must compensate. It does explain the semantics of start/end (program seconds, default whole program), emphasis_words (accent color, size bump, pop), zone (upper default, lower, sides), and motion_style (composed, preset, still). It does not detail font, color, size_scale, accent_color, or motion_motif, but the most impactful parameters are covered. For the low schema coverage, this is a strong effort, though not exhaustive.

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

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

The description opens with a clear verb-resource statement: 'CHOREOGRAPH THE SPOKEN WORDS onto the screen in ONE pass.' It explicitly contrasts with the alternative of dozens of add_text calls and specifies the use cases (talking-head footage, promo/educator reels, speech-carried typography). This sharply distinguishes it from sibling tools like add_text, add_captions, and set_text_motion.

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

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

It states precisely when to use the tool (for speech-synced typography over talking-head footage, promo/educator reels) and when not to (instead of dozens of add_text calls). It also provides post-render guidance: inspect frames, and if the zone is wrong, re-run with another zone. The description names alternatives and the conditions that select this tool, leaving nothing to inference.

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

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

Annotations only say readOnlyHint=false, openWorldHint=false, idempotentHint=false, destructiveHint=false, which tells the agent this is a mutating, non-idempotent, closed-world operation. The description goes far beyond that: it discloses default ducking behavior (-18dB bed vs -4dB lead), the context-aware switching logic, default loop behavior, default fades, offset_s semantics, and the smooth vs step ducking distinction. It also warns that storage_key must be an exact key and never invented. This is rich behavioral context that the annotations do not provide.

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

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

The description is dense and information-rich, with front-loaded scope and a clear 'Mix music into the edit' statement. It uses capitalization and dashes to emphasize key terms (PROJECT-SCOPED, CONTEXT-AWARE, OUTPUT-timeline, SMOOTH). It is longer than a typical description, but every sentence adds operational value. It loses one point for being somewhat sprawling and for burying the 'Fades in/out by default' detail in the middle rather than grouping all defaults 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?

For an 11-parameter tool with no output schema, the description covers the critical decision points: how to choose music, how to handle defaults, how to override them, how to source storage_key, and how ducking behaves. It also references sibling tools for follow-up (set_music_fit) and evidence gathering (get_audio_analysis). The only minor gap is that it doesn't describe the return value, but the opening line says 'returns the project identity with its result,' which is sufficient for an agent to know what to expect.

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

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

Schema description coverage is only 18%, so the description must compensate. It does: it explains gain_db/duck as overrides, start/end as output-timeline seconds defaulting to the whole video, loop=true repeating a short track, offset_s starting partway into the track, and storage_key as an exact key from list_assets. However, it does not explicitly explain fade_in_s/fade_out_s or purpose beyond the schema's own description, and it doesn't enumerate all 11 parameters. Still, the most behaviorally important parameters are well covered.

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

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

The description opens with a clear project-scoped statement: 'this call acts only on the explicit project_id and returns the project identity with its result. Mix music into the edit.' It names the resource (music into the edit) and the verb (mix/add), and distinguishes itself from siblings like remove_music, swap_music, set_music_fit, and separate_music by focusing on adding music with ducking behavior. The description also clarifies scope (explicit project_id only), which differentiates it from tools that might use an active-project pointer.

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

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

The description gives explicit when-to-use guidance: 'Choose from the user's direction, metadata, context and measured get_audio_analysis evidence.' It also tells the agent when to omit parameters ('omit them for 'add some music''), when to override defaults ('Pass gain_db/duck only to override that'), and how to source storage_key ('exact key from list_assets(kind='music')... never invent one'). It even references sibling tools (list_assets, get_audio_analysis, set_music_fit) for alternatives and follow-up actions. This is strong 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?

The description goes well beyond the annotations (which only say readOnlyHint=false, destructiveHint=false, etc.) by disclosing honest limits: video overlay audio does NOT play (silent), overlays render above footage but BELOW captions, and they do NOT track objects. It also explains the behavioral difference between fit='cover' and insert_media regarding program timing. This is rich behavioral context that an agent needs to set expectations correctly.

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

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

The description is dense and information-rich, with clear section markers (PROJECT-SCOPED, HONEST LIMITS). It front-loads the most important scoping constraint and the primary use case. It is long, but every sentence adds operational value—defaults, ranges, exclusions, and behavioral caveats. Slightly over-long for a quick scan, but the structure (caps for key phrases, bullet-like clauses) helps navigation.

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 13-parameter tool with no output schema and only 15% schema coverage, the description is remarkably complete. It covers parameter semantics, defaults, ranges, behavioral limits, and the key sibling distinction (insert_media). It even addresses asset sourcing (list_assets) and reuse policy. Nothing an agent needs to invoke this tool correctly is missing.

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

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

Schema description coverage is only 15%, so the description carries the burden of explaining parameters. It does this thoroughly: duration_s defaults (image 4s, video clip's length bounded by program end), x/y as CENTER fractions (ignored with fit='cover'), keyframe list format [{t,v}] for drift/slide, scale as fraction of frame width with range and default, opacity range, entrance/exit enums, source_start_s for seeking. This is far beyond what the schema provides.

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

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

The description clearly states the tool's function: drawing an image or video clip over the program picture for a window of PROGRAM time, with specific use cases (picture-in-picture, corner logo, b-roll cutaway). It distinguishes itself from insert_media by explicitly noting that insert_media PAUSES the talk and adds time, while fit='cover' does not. The verb 'draw' and resource 'overlay' are specific and unambiguous.

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

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

The description provides explicit when-to-use guidance: 'THE way to show what the speaker is talking about without touching the timing.' It also gives a clear exclusion: 'insert_media PAUSES the talk and adds time; fit='cover' does not — pick by whether the speech should continue.' This directly helps an agent choose between add_overlay and insert_media. It also mentions asset_key from list_assets, providing a source for valid inputs.

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 are all false, so the description carries full burden and delivers extensively: it discloses the refusal conditions (cannot measure screen, screen under 8% of frame), the replacement semantics (REPLACES existing takeover, inherits omitted params, reuses pin corners), the momentum/settle behavior, and the three-way corner detection order. The description's write semantics ('replaces... in one write') are consistent with readOnlyHint=false — no contradiction.

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

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

The description is a ~700-word wall of text that is front-loaded well but poorly structured: ALL-CAPS emphasis, long parenthetical asides, and repeated explanations (corner matching is covered in a ~150-word digression with redundant phrases like 'living on the glass from the window's start' and 'fully there before the picture lands'). The same operational facts could be delivered in roughly half the length; the verbosity taxes the agent's context window despite the valuable content.

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

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

Given the complexity (11 params, 18% schema coverage, no output schema, all-false annotations), the description is exhaustive: every parameter is explained, refusal and replacement behavior is stated, corner-detection strategy is documented, and the distinction from remove_screen_takeover is drawn. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is only 18%, so the description must compensate and does so thoroughly: it defines at_output_s (where the takeover FINISHES), duration_s (0.4-5, default 1.2, recommended 1.0-1.5), corners (8 fractions in top-left, top-right, BOTTOM-LEFT, bottom-right order or a rect), clip_start_s, hold_s (default rest of asset), push (0-1, 1=all the way), ease (three values), and settle. This far exceeds what the sparse schema provides.

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

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

The description names a specific verb+resource ('camera travels INTO a device and the content takes over') and gives concrete user-phrase examples ('zoom into the laptop and continue with the other scene'). It explicitly differentiates from siblings add_zoom and insert_media, explaining that an overlay drawn ABOVE the zoom makes the content sit flat while the shot pushes past. An agent can unambiguously select this tool for device-screen takeover transitions.

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-to-use ('every request that describes the camera travelling INTO a device'), an explicit when-NOT-to-use ('Do NOT build this out of add_zoom + insert_media' with the failure reason), and the alternative for removal ('remove_screen_takeover is only for taking the transition OUT'). It also documents the idempotent-replacement pattern (call again at the same arrival to change an existing takeover). Nothing about selection 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?

Annotations provide no behavioral hints (all false), so the description carries full responsibility. It discloses project scoping ('PROJECT-SCOPED: this call acts only on the explicit project_id'), return behavior ('returns the project identity with its result'), audio behavior ('plays once, for as long as the sound is, and never ducks'), and timing semantics. This is comprehensive given the absence of annotation support.

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 lengthy but every sentence adds value: scoping, usage, exclusions, parameter guidance, and default. It is front-loaded with project scoping and maintains a logical flow. While dense, it avoids redundancy and each sentence earns its place, making it appropriately structured for the tool's complexity.

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

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

With no output schema, the description explains the return value ('returns the project identity with its result'). It covers all parameters, usage context, prerequisites, and exclusions. It also addresses potential uncertainty ('uncertainty is something to judge rather than a reason the tool becomes unavailable'). This is a complete and self-sufficient description for a complex tool.

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

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

Schema coverage is only 17% (only project_id has a description). The description compensates by explaining storage_key (exact key from fetch_sfx or list_assets), at (output-timeline second), offset_s (starts inside source audio), purpose (records event for review), and the default -6dB gain. This covers all parameters meaningfully, far exceeding schema 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?

The description clearly states the tool's purpose: 'Punctuate a MOMENT with a one-shot sound effect' and gives concrete examples (whoosh, click, impact). It explicitly differentiates from background music, aligning with sibling tools like add_music and add_voiceover. The verb 'add' combined with the resource 'sfx' is specific and unambiguous.

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

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

Provides explicit usage conditions: 'Choose it when the brief, format, timing, or your editorial judgment says sound design improves the cut.' It also states a clear exclusion: 'This is NOT background music: it plays once, for as long as the sound is, and never ducks.' Additionally, it specifies the source for storage_key, guiding the agent on valid inputs and 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?

The description adds significant behavioral context beyond the annotations: the clip is SILENT, not yet in the video, representative frames from the actual downloaded rendition are attached, and handles survive later turns and MCP worker processes. It does not contradict the annotations (readOnlyHint=false, destructiveHint=false, etc.), and actually reinforces them by describing a non-destructive, additive operation.

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

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

The description is moderately long but each sentence contributes essential information. It front-loads the project-scoped warning and uses clear directives (DOWNLOAD, place it, inspect, tell the user). It could be slightly more compact, but the structure is logical and easy to scan.

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

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

With no output schema, the description gives a hint of the result ('returns the project identity with its result') and mentions attached frames. It covers all critical call requirements: id matching, project_id sourcing, placement guidance, and user notification. Minor details like error handling are absent but not essential for correct invocation.

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

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

Despite the schema having only 50% coverage (id lacks description), the description thoroughly explains both parameters: id must exactly match a project result and handles persist, while project_id is a required immutable scope copied from project state, not guessed from the active pointer. This compensates fully for the schema's gaps.

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

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

The description clearly states the action: 'DOWNLOAD one saved search_stock or research_broll result and save it as a project asset.' It specifies the resource (stock media) and the verb (add), and distinguishes itself from other add_* tools by focusing on downloading and saving stock media. The project-scoped warning further clarifies its specific scope.

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

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

The description explicitly states when to use this tool and how to use it correctly: it is project-scoped, requires an exact id match, and provides placement guidance by naming alternatives like add_overlay(fit='cover') and insert_media. It also advises inspecting frames before placement, giving clear conditional usage instructions.

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 minimal annotations, the description carries the burden and does so thoroughly. It discloses content-anchoring ('a stylized moment follows its footage through later cuts'), explains effect limitations (motion_blur 'only reads on movement, does nothing on a static shot'), and warns about layer stacking ('five read as a broken TV'). It also notes the return behavior ('returns the project identity with its result'). No contradiction with annotations.

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

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

The description is a single dense paragraph, but every sentence earns its place. It front-loads the project scope, then lists effects with inline clarifications. While long, the semicolon-separated list keeps it readable. It could be split into clearer sections, but it remains efficient for the information conveyed.

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

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

For a tool with 13 effect variants and subtle caveats, the description is remarkably complete. It explains the whole-video vs. program-seconds behavior, intensity constraints, effect-specific limitations, and the content-anchored nature. It also gives an alternative (enhance_video) and sets expectations about layered effects. An agent has all the information needed to decide and invoke correctly.

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

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

Schema description coverage is only 33%, but the description adds significant meaning: it explains start/end as program seconds, intensity range and default, and describes each effect kind. project_id and motion_motif are already described in the schema. The description does not explicitly tie parameter names to their explanations, but it covers the critical ones. It compensates well for the coverage gap, though a few parameters like motion_motif are left to the schema.

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

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

The description clearly states the verb ('Layer'), resource ('program picture'), and scope ('PROJECT-SCOPED: acts only on the explicit project_id'). It enumerates all effect kinds and distinguishes from siblings like remove_stylize and enhance_video. An agent can immediately understand what this tool does and how it differs from alternatives.

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

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

Explicit guidance is provided for when to use this tool versus others: 'sharpen'/'denoise' → 'prefer enhance_video, which orders them correctly'; 'stabilize' is 'whole-video only' and cannot fix a whip, walk, or rolling shutter. It also clarifies start/end semantics ('PROGRAM seconds — omit both for the whole video') and intensity range, so the agent knows how to invoke correctly.

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

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

The description discloses a non-obvious side effect: this text item owns caption suppression for its live window, preventing stacked word layers and automatically restoring captions when removed. This goes beyond the minimal annotations and gives the agent a clear mental model of the tool's impact.

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

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

The description is dense and information-rich, using lists and semicolons to organize options. It is longer than average, but every sentence adds value (e.g., explaining coordinate systems, edge cases, and the motion vs. preset decision). The structure is coherent and front-loaded with the core purpose.

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

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

Given the complexity (17 parameters, nested objects, no output schema), the description is largely complete: it covers the main behaviors, constraints, and relationships with sibling tools. It lacks some details like return value structure, but since no output schema is provided, this is acceptable. The description effectively sets the tool in 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?

The schema description coverage is low (18%), but the tool description compensates by explaining many parameters: x/y override position, size_scale range (0.4–3.0), color/accent_color format, font families, entrance/exit presets, and the motion curve semantics (units, coordinate system). A few parameters (e.g., 'motion_motif') are only described in the schema and not in the description, but the overall coverage is strong.

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

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

The description clearly states that this tool burns a motion-graphics text template into a video window, explicitly distinguishing it from captions and overlays. It also specifies the intended use cases (dictated text like titles, labels, stats) in a concise way.

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

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

The description provides explicit guidance on when to use this tool versus alternatives (add_captions for spoken words, add_overlay for media) and explains the relationship between 'motion' and preset entrance/exit animations. It also clarifies that 'motion' should be used instead of named presets when authoring custom curves.

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

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

With only generic annotations (readOnlyHint=false, destructiveHint=false), the description carries the full burden. It discloses scope (project-scoped only), temporal-state matting behavior, refusal criteria listed as 'REQUIREMENTS I check and refuse on', reporting of overlap, and the recommendation not to zoom or stabilize. It adds substantive behavioral detail beyond annotations and contradicts none.

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

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

The description is long but earns its length: it is organized, front-loaded with project scope, then semantics, then usage prohibitions, then style guidance. Some sentences are redundant for choosing a tool ('PUT WORDS BEHIND THE MOVING SUBJECT' repeated), but no unsourced marketing filler.

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

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

Given 15 parameters, no output schema, and minimal annotations, the description is nearly complete: it covers the depth semantics, parameter meaning, expected failure conditions, fallback behavior, and how to remove the effect. It goes beyond the minimum needed for correct invocation.

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

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

Only 7% of parameters have schema descriptions, so the description must compensate. It does by identifying arg groups: 'Same styling arguments as add_text (template/x/y/size_scale/color/font/entrance/exit)' and explains at_output_s + duration_s and the special default for size_scale. However, at least four properties (box, uppercase, accent_color, gap between x/y) remain unaddressed, and it depends on the agent already knowing add_ with sibling's arguments, so not a full 5.

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

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

States the exact operation with specific verb and resource: put text behind the subject, a real depth composite. It explicitly differentiates from add_text and explains when words read as an ordinary title, so an agent can tell this apart 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 explicit when-to-use and when-not-to-use guidance: requires a visible person, refuses if no person and tells agent to offer add_text instead. It also names sibling tools as alternatives for using add_text and remove_text, leaving no inference required.

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

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

Annotations are all false (readOnly=false, destructive=false, etc.), so the description carries the full burden and does a good job: it discloses that the card is a real cut (not overlay), that spoken-word captions never appear on it, that it shifts subsequent content, and that it returns the project identity. Minor gaps remain—it doesn't discuss reversibility or effects on other tracks—but the disclosed behavior is substantial.

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

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

The description is dense but efficiently organized: it front-loads the critical scope, then explains the behavior, then parameter hints, then the alternative. Every sentence adds value—no filler—though it could be tightened slightly by moving the explicit alternative to the end, which it already does. It's appropriately sized for the complexity.

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

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

With 13 parameters, 4 enums, and no output schema, the description is not complete. It doesn't explain the enum options (entrance, exit, template, font) or their effects, doesn't specify defaults for duration_s or size_scale, and doesn't detail the return value beyond 'project identity'. The description covers only the core behavior and a couple of params, leaving too much for an agent to guess or investigate.

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 only 8%, and the description compensates for only a few parameters: at_output_s (program seconds), bg_color (default '#000000'), subtitle (adds a second line), and text (implied as the main text). The remaining 10 parameters (exit, font, color, entrance, template, duration_s, size_scale, accent_color, project_id, etc.) are unexplained, leaving the agent to infer or open the schema for each. This is insufficient for a low-coverage schema.

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

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

The description opens with a precise verb+resource ('add_title_card' builds a standalone full-frame card with text) and immediately scopes it as project-limited. It also distinguishes itself from the sibling add_text by explaining the difference (card replaces footage vs. text overlays on it), so an agent can tell them apart without inspecting schemas.

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

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

Explicitly states when to use it ('when the text should sit OVER the footage rather than replace it' is the exclusion for add_text) and clarifies the timing semantics (at_output_s is program seconds, everything shifts later by duration_s). It also notes the project_id is immutable and copied from specific sources, giving clear invocation guidance.

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

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

Annotations are all false, so the description carries the full burden. It discloses that the call is project-scoped, returns the project identity, uses program-time windows, and advises previewing the whole path before accepting. This gives the agent a clear sense of side effects and scope, though it doesn't state whether it replaces or adds to existing graphics or detail error conditions.

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

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

The description is a single dense paragraph, but every sentence adds value: scope, action, kinds, coordinate system, formatting rules, motion, and usage philosophy. It is front-loaded with the project-scoping caveat and avoids filler. Slightly long but efficient for the parameter complexity.

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

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

Given 17 parameters, nested motion objects, and no output schema, the description covers most parameter semantics and usage context. It lacks explicit units for start/end (seconds vs frames) and does not explain motion_motif or the top-level opacity (though motion includes it). These are minor gaps given the richness of the rest, so it is nearly complete.

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

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

With schema coverage at only 18%, the description compensates well: it explains x/y as frame-fraction centres, width/height as fractions, color formats (#RRGGBB), stroke_width as a fraction of the short edge, rounding as 0-0.5 of the short side, and progress value as 0-1. It also explains motion uses the same keyframe structure as designed text. It does not explicitly describe start/end units or the motion_motif parameter, but most critical semantics are covered.

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

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

The description clearly states it adds a renderer-native VECTOR graphic over a program-time window, enumerates the supported kinds (rectangle, ellipse, line, arrow, ring, progress) and distinguishes them by purpose. This is a specific verb+resource with enough detail to separate it from sibling add_* tools like add_text or add_overlay.

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

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

It provides explicit guidance on when to use each shape ('use a panel to support hierarchy, a line to connect, and arrows/rings only when the frame contains the thing they identify') and notes the project-scoped nature. However, it does not explicitly name alternatives or state when not to use this tool (e.g., versus set_vector_graphic), so the exclusion context is only implicit.

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

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

Annotations are minimal (no readOnly, destructive, etc.), so the description carries the burden. It discloses key behaviors: project-scoped, duck_others lowers other audio by 12dB, source_offset_s seeks into the file, and it returns the project identity. No contradictions found with annotations.

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

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

The description is dense but well-structured: it opens with the critical scope note, then explains each parameter with examples and use cases. While it is longer than a typical description, every sentence serves a purpose and it is logically organized.

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

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

For a tool with 7 parameters and no output schema, the description covers all essential aspects: what it does, how to use it, parameter meanings, and even the return value. It lacks explicit details on edge cases (e.g., what happens if duration_s is omitted), but overall it is complete enough for an agent to invoke it correctly.

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

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

Schema coverage is only 14% (only project_id is described), but the description compensates by explaining start_output_s, duck_others, source_offset_s, duration_s, and asset_key in detail. gain_db is not explicitly explained but is self-explanatory from its name. Overall, it adds substantial meaning beyond the schema.

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

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

The description clearly states the tool's function: lay an uploaded audio file over the whole program, with parameters for timing and ducking. It distinguishes itself from siblings like add_music and add_sfx by focusing on voiceover and the explicit project-scoped behavior, and it even describes a specific reuse case for main-source dialogue.

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

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

It provides clear guidance on when to use the tool, including a specific scenario for reusing dialogue and an explicit instruction to use storage_key from list_assets(kind='music') for music. It also advises against external trimming workarounds. It doesn't explicitly list exclusions vs. alternatives, but the context is sufficient.

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

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

Beyond the annotations, it discloses project scoping, the download-and-compare workflow, the default 'keep this moment dry' decision behavior, exact timeline placement, and source/license reporting. It does not address what happens if the call is repeated or whether placement overwrites an existing effect, which would be useful to know.

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

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

The description is dense but every sentence adds information: scope, workflow, defaults, exceptions, and examples. It front-loads the project-scoping constraint and keeps the reader oriented, though the uppercase emphasis is slightly noisy in an otherwise well-structured definition.

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

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

For a 6-parameter tool with no output schema, the description is fairly complete: it covers purpose, sourcing, placement, licensing, defaults, and result contents. It still omits explicit error behavior and exact return shape, so an agent must infer some handling from the schema and examples.

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 only 17% schema description coverage, the description carries most parameter meaning: gain_db defaults to -6, max_seconds to 15, allow_none=false is reserved for explicit user requests, and 'at' refers to an exact output-timeline second. It adds meaning via examples but leaves max_seconds' precise effect and allowable ranges undocumented.

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: it searches real Openverse/Freesound recordings, acoustically compares candidates, and places a match at an exact timeline position. The PROJECT-SCOPED note and concrete examples like 'add a cinematic whoosh at 3.2s' make its behavior unmistakable and distinguish it from related sfx sibling tools.

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

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

It gives explicit use cases ('add a cinematic whoosh at 3.2s', 'put a shutter on this cut') and explains when to set allow_none=false (only when the user explicitly requires an effect). It does not explicitly contrast with nearby alternatives like add_sfx or audition_sfx_candidates, so some routing judgment remains.

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

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

Annotations only say not read-only and not destructive, so the description carries the burden. It details behavioral nuances: rect vs cx/cy semantics, precedence rules ('if both arrive the rect wins'), default behavior when targets are omitted, and result reporting ('returns the project identity... reports where the region lands on screen'). No contradiction with annotations.

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

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

The description is long but every sentence adds value. It is front-loaded with the scope constraint and structured logically: when, how (strength/mode), aiming (rect/cx/cy), precedence, fallback, and routing to add_zoom_path. No redundant or fluff sentences; density is appropriate for the tool's complexity.

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

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

The description covers all necessary decision points: when to use, how to choose between rect and cx/cy, strength semantics, mode selection, edge cases (edge points), default behavior, and when to defer to add_zoom_path. With no output schema, it even describes the result content. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is only 27%, so the description must compensate. It thoroughly explains rect, cx/cy, strength (with value ranges and effects), mode (with per-mode behavior), and start/end implicitly. It does not explain motion_motif or target_evidence_ids, but these are peripheral to core usage; the main parameters are richly documented 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 the exact verb and resource ('Zoom on a time range of the FINAL edited video') and immediately clarifies scope ('PROJECT-SCOPED'). It explicitly distinguishes itself from the sibling add_zoom_path ('that is ONE add_zoom_path, never a chain of static zooms'), so an agent can tell them apart without inspecting schemas.

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

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

Provides explicit when-to-use conditions ('only when a named event needs the camera to move: a reveal, a UI target, a punchline'), negative guidance ('A talking-head already in frame does NOT need a punch-in'), and strong direction on when not to use it ('Zero zooms is often correct'). It names the alternative tool (add_zoom_path) for moving zooms, leaving no ambiguity.

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

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

Annotations indicate a write operation (readOnlyHint false) with no destructive hint, and the description aligns by describing a mutating effect. It discloses key behaviors: acts only on explicit project_id, interpolates between keyframes, holds by repeating keyframes, adds no ramp at edges, and re-anchors across cuts. No contradiction with annotations.

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

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

The description is long but densely packed with necessary details. It front-loads the purpose and usage guidance, then systematically explains parameters and edge cases. While it could be trimmed, every sentence contributes to correct usage for a complex tool. It earns a 4 rather than 5 due to 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 tool with six parameters, no output schema, and complex keyframe semantics, the description is remarkably complete. It covers parameter formats, interpolation behavior, hold strategies, easing options, edge-case handling, and even cleanup (remove_zoom_path). An agent has enough to call it correctly without further lookup.

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

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

Schema coverage is only 33%, so the description must compensate. It thoroughly explains keyframes (structure, t, rect/cx/cy, strength semantics, hold behavior) and ease values. It also clarifies project_id as explicit scope. However, it does not explain purpose, motion_motif, or target_evidence_ids, which remain underdocumented. Given the critical parameters are covered, a 4 is appropriate.

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

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

The description states a specific verb-resource pair and clearly defines the tool's niche: moving a single zoom across multiple subjects in sequence, contrasted with static add_zoom calls. It even gives example phrasings ('make the zoom follow the cursor') and differentiates from add_zoom and remove_zoom_path.

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

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

Explicitly states when to use (one zoom that holds, travels, or visits several subjects) and when not (never a chain of static add_zoom calls). It also names the removal counterpart (remove_zoom_path). This gives the agent clear decision criteria without opening other tool schemas.

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

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

Annotations only mark readOnlyHint=false, destructiveHint=false, idempotentHint=false. The description adds substantial behavior: it preserves existing emphasis_words or picks them from the transcript, never touches cuts/music/sfx, and reports every component it set. It also discloses the return behavior (project identity with result). This is far beyond annotation coverage.

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

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

The description is dense but every sentence earns its place. It front-loads the critical scoping and one-call nature, then enumerates looks, states constraints, and gives adjustability guidance. 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?

With no output schema, the description explains what the result contains (project identity, reported components). It covers all inputs, lists the exact enum values with behavior, notes the immutable scope, and clarifies what the tool does NOT do. An agent has everything needed to call it correctly.

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

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

Schema coverage is 50% (only project_id has a description). The description adds semantic meaning to the 'name' parameter by explaining exactly what each look does (e.g., 'hype' = beast xl captions, vibrant grade, zoom_punch cuts, closing fade). It also reinforces project_id's scope. This compensates well for the schema gap, though it doesn't enumerate parameter syntax explicitly.

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

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

The description states a specific verb ('apply') and resource ('look'), and immediately clarifies project scoping. It lists five distinct looks (hype, clean, cinematic, luxury, meme) with concrete effects, making the purpose unmistakable and easily distinguishable from sibling tools like add_stylize or set_color_grade.

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 states when to use this tool: for a one-call aesthetic composition across captions, grade, transitions, fades, and stylize. It also gives a clear exclusion: 'Never touches cuts, music or sfx — place accents with add_sfx.' This is direct when/when-not guidance with a named alternative.

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

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

Annotations provide no hints (all false), so the description carries the burden. It discloses that the call is blocking ('wait for their reply') and ends the current turn, which is critical behavioral context. It also states the project scoping ('acts only on the explicit project_id') and that it returns project identity, giving a clear picture of side effects and interaction.

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 tight sentences, front-loaded with the critical scoping note and the turn-ending behavior. No filler words; every clause adds value. The structure makes the key constraints immediately visible.

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 tool, the description covers the essential aspects: scope, action, blocking behavior, and usage context. The schema covers project_id. It doesn't mention timeout or response format, but those are not necessary given the simple interactive nature. It's complete enough for an agent to invoke correctly.

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

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

Schema coverage is 50% – only project_id has a description, which is detailed. The question parameter has no schema description, but the tool description says 'Ask the user a specific question', which directly maps to the question field. However, it doesn't elaborate on question format or constraints, so the description only partially compensates for the missing schema 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?

The description clearly states the verb 'ask' and the resource 'user', and it distinguishes this tool from all editing siblings by emphasizing it's the only one that interacts with the user. The phrase 'Use whenever a material choice genuinely belongs to the user' further clarifies the exact purpose.

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

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

The description provides a clear condition for use ('whenever a material choice genuinely belongs to the user') and implicitly advises against using it when the decision is not the user's. It doesn't explicitly state alternatives, but no sibling offers this capability, so the guidance is sufficient.

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

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

The description implies a read-only, side-effect-free audit ('deterministic audit', 'ground truth', 'returns'), but annotations set readOnlyHint=false. This is a direct contradiction, and the description provides no clarification about any potential side effects.

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

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

The description is dense but well-structured, front-loading the PROJECT-SCOPED constraint and then listing the audit components. Every sentence adds value, though it is slightly long.

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

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

With no output schema, the description thoroughly explains what is returned (roles, files, provenance, SHA-256, null/unknown handling, duplicate/misfile detection). It is sufficient for an agent to understand the result, though exact formatting is not specified.

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

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

The schema documents project_id, but the description adds crucial guidance: it must be copied from list_projects/open_project/project_state and the active-project pointer is never used. This prevents misuse and goes beyond the schema's generic description.

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

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

The description clearly states the tool audits the audio mix (music, voiceover, SFX) of the current EDL and enumerates specific attributes (roles, files, windows, offsets, gains, ducking, mastering) plus detection capabilities. It distinguishes itself from sibling audit tools like audit_captions by focusing on the audio mix.

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 notes the tool is project-scoped and returns ground truth, and mentions an alternative (deterministic preview AUDIO CHECK) for measuring rendered mix without relabeling roles. However, it does not explicitly name the alternative tool or provide clear when-to-use versus when-not-to-use conditions.

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

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

With annotations all false, the description carries the burden, and it delivers useful behavioral details: it is project-scoped, uses the exact ASS artifact that ffmpeg burns, returns project identity with the result, and lists exact metrics and output times. It does not explicitly state whether state is modified, but the audit semantics and output framing make the behavior reasonably clear.

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 mostly high-value, front-loading the critical project-scoped constraint. The long mid-sentence list of metrics is packed with useful information, though it would be easier to parse if broken into shorter sentences.

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

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

For a tool with no output schema, the description does well by enumerating the reported metrics, event pages, and output times. The only notable gap is the lack of any guidance on limit and offset, which leaves the pagination behavior ambiguous.

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 only 33%, with limit and offset completely undocumented in the schema. The description clarifies project_id's required immutable scope and how to source it, but it does not explain limit or offset at all, so 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?

The description uses a specific verb and resource: it audits the current caption track, and is explicitly marked PROJECT-SCOPED. It also distinguishes itself by naming what it reports and by comparing itself to a visual critic, making it easy to differentiate from siblings like audit_audio_mix.

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

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

It explicitly tells the agent when to call this tool: after adding or restyling captions and after render_preview. It also provides a exclusionary reason by stating it is stronger timing evidence than a visual critic, which helps select the correct tool among alternatives.

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

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

Annotations are minimal (readOnlyHint false, etc.) but the description adds important context: it is project-scoped, returns the project identity, measures specific audio attributes, and does not hear audio. It discloses that it is an analysis/ranking operation without claiming mutation. No contradiction with annotations; the description enriches beyond them.

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

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

The description is moderately long but information-dense. It is front-loaded with the project-scoping note and the core comparison purpose, then adds measurement details and usage advice. Every sentence contributes value; it is not overly verbose for the complexity.

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

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

There is no output schema, but the description tells what the tool returns (project identity and ranking evidence) and what it measures. It also explains the post-selection workflow. This is sufficient for an agent to invoke it correctly, though exact output format is unspecified.

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

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

Schema coverage is only 33% (only project_id has a description), but the description compensates by explaining the purpose of 'ids' (candidates from search_sfx) and 'purpose' (named physical/editorial purpose for ranking). It adds meaning beyond the bare schema, though it does not detail exact formats.

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

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

The description clearly states the tool's purpose: compare multiple SFX candidates using actual waveform data. It specifies the exact resource (SFX candidates), the action (audition/compare), and the outcome (ranking against a purpose). It distinguishes itself from siblings like search_sfx (searching) and fetch_sfx (fetching) by focusing on the audition/ranking step.

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

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

The description gives clear context on when to use: 'Compare multiple search_sfx candidates using their ACTUAL waveform before choosing.' It also advises what to do after (fetch and place the winner) and acknowledges the LM's limitation. It does not explicitly state when NOT to use it, but the intended usage is well implied.

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

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

The description discloses internal behavior: it samples frames, measures subject location and detail survival, and decides between crop and fit (with blurred backdrop). It mentions 'writing the frame' indicating a mutation, and notes it returns the project identity. While annotations provide no hints (all false), the description carries the burden and does so well, though it doesn't cover side effects 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?

The description is long but front-loaded with scope and purpose ('PROJECT-SCOPED', 'THE tool'). Every sentence adds value—explaining the measurement logic, mode behavior, and the truncation complaint. It could be trimmed slightly, but the structure is logical and efficient.

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

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

With no output schema, the description should clarify the return value. It says 'returns the project identity with its result' and 'Read what it reports and repeat THAT,' but the 'result' and 'THAT' are vague. It doesn't specify the output format or error conditions, leaving an agent uncertain about how to interpret and act on the result.

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

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

Schema coverage is only 33% (project_id has a description), but the description compensates by explaining mode's behavior ('auto' default, crop vs pad) and implicitly clarifies ratio via the title. It adds meaning beyond the enum for mode, and reinforces project_id's immutability. Ratio is not directly explained but is obvious from context.

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 explicitly states it is 'THE tool for make it 9:16 / vertical / for TikTok' and emphasizes 'PROJECT-SCOPED', clearly distinguishing it from siblings like add_aspect_shift or set_frame. It names the specific verb (reframe) and the resource (project video), leaving no ambiguity about its function.

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

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

It gives explicit usage guidance: 'Pass mode explicitly to force one' and instructs the agent to 'Read what it reports and repeat THAT.' It positions itself as the definitive tool for vertical/square conversion, implying when to use it, though it doesn't explicitly list alternatives or when not to use it. The context is sufficient for an agent to select it correctly.

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

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

Despite minimal annotations, the description fully discloses behavior: it moves boundaries, skips word-interior moves, refuses to sync to noise, never invents a tempo, returns project identity plus moved/skipped counts, and notes it operates on a single EDL version. No contradiction with annotations (destructiveHint=false aligns with 'moves boundaries, does not create').

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

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

The description is long but every sentence carries necessary information. It is front-loaded with scope and core behavior, then covers edge cases and workflow. Slightly verbose in phrasing, but justified by the tool's complexity and the absence of an 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?

With no output schema, the description covers the return (project identity, moved/skipped counts) and behavior in edge cases. It also integrates with sibling tools (get_audio_analysis, keep_segments) to give a complete workflow. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is only 20% (only project_id described), but the description explains every parameter: tolerance_s default (0.35s), source enum meaning (video forces footage audio), every_s and bpm as tempo hints that skip the confidence gate, and project_id as immutable scope. This fully compensates for the sparse 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 ('slides each INTERNAL cut') and resource (cuts), and explicitly frames itself as 'THE tool for cut to the beat'. It distinguishes from siblings by noting it does not create cuts and skips moves that would land inside a word, making it clear vs. keep_segments and cut_silences.

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-to-use guidance: describes when to pass tempo hints, when it refuses (no music/tempo/pulse), and gives a workflow with keep_segments and get_audio_analysis for cutting on every beat. It also states it only moves existing cuts, not creates them.

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

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

Annotations indicate readOnlyHint=false and destructiveHint=false, and the description aligns by stating it records provenance without creating an effect. It adds valuable context: project-scoped side effects, return of project identity, rejection of 'hold' and static targets. No contradiction found, and it discloses the key non-creation behavior.

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

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

The description is dense but every sentence earns its place. It front-loads the project-scoped constraint, then quickly states the core purpose, clarifies target semantics, and ends with clear rejections. No redundant wording or filler.

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

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

For a tool with no output schema, the description covers all essential details: required parameters, scoping, valid target types, special values, and rejection rules. It also states the return includes project identity, which addresses the output gap. An agent has enough to call it correctly.

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

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

With 50% schema coverage, the description compensates substantially. It explains that target_type values map to specific domains (transition/captions are track-level, id is for item targets), clarifies motion_motif can be 'clear' and that 'hold' is rejected, and emphasizes project_id is an immutable scope that must be copied from a source, never guessed. These go well 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 ('bind'), a precise resource (an existing renderer-visible movement to a motif id), and distinguishes it from creation tools by clarifying it records provenance rather than creating an effect. It also enumerates target types and explicitly rejects static targets and 'hold', leaving no ambiguity about scope.

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

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

It clearly scopes the call to a project_id, explains it acts on EXISTING movements, and differentiates track-level vs item targets. It does not explicitly name alternative sibling tools, but the behavioral constraints (e.g., 'does not create an effect') make the usage context clear. The 'clear' option and rejection rules further guide correct invocation.

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

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

No annotations provide behavioral hints (all false), so the description carries full burden. It discloses the coordinate system (fractions of source frame), the non-tracking nature, that spliced clips are never censored, optional timing, and the project-scoped behavior. This goes well beyond what annotations offer.

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

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

The description is long but each sentence adds essential context: scope, purpose, usage alternatives, coordinate system, example, workflow, mode, and limitation. It's front-loaded with the project scope and purpose, and while lengthy, it's structured with bold labels and an example, so it's not wasteful. Slightly over-wordy but justified for the complexity.

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

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

Given 8 parameters, no output schema, and no annotation hints, the description covers all necessary details: how to specify the region, coordinate system, modes, timing, verification workflow, and edge cases (motion, spliced clips). It even includes a concrete example. Nothing critical is missing for an agent to call this correctly.

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

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

Schema coverage is only 13% (only project_id described). The description explains x/y/w/h as fractions, start/end as output seconds, mode meanings, and project_id scoping. It adds substantial meaning for every parameter, fully compensating for the sparse 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?

Clearly states the tool's function: placing a visible censor (blur, mosaic, black bar) over a fixed rectangle of the original footage. It distinguishes itself from siblings (erase_region/erase_burned_text) by contrasting visible covering vs removal.

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 specifies when to use it (user wants covering to show) and when not (when removal is desired, pointing to erase tools). Provides a step-by-step workflow (look_at, blur_region, render_preview, check, adjust) and notes the limitation about motion tracking.

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 are all false, so the description carries the burden. It discloses that the call acts only on the explicit project_id, does not rank by upload order, does not silently shortlist, and explicitly allows leaving weak/redundant assets unused. It also mentions dynamically built labeled pages and returned evidence_ids. It doesn't detail side effects or performance, but the key behavioral traits are disclosed.

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

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

The description is dense and somewhat disorganized, with unusual capitalization and run-on phrasing ('YOUR OWN EYES on SEVERAL uploaded clips/images in ONE story-wide comparison'). It front-loads the project-scope constraint but buries the key usage guidance mid-paragraph. It could be tightened into clearer, shorter sentences without losing 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 comparison tool with no output schema, the description covers the main operational needs: what to pass, how it behaves, and what to do with the result ('use source_asset_key + the returned evidence_ids in sequence_map'). It doesn't explain the 'question' or 'samples_per_asset' parameters, which is a gap, but the core workflow is complete enough for an agent to invoke it correctly.

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

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

Schema description coverage is only 25%, so the description must compensate. It explains asset_keys ('Pass every relevant exact storage_key together') and project_id ('Required immutable scope... Copy the id from list_projects/open_project/project_state'), but it does not explain the 'question' or 'samples_per_asset' parameters. The description adds meaning for two of four parameters, which is partial compensation 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?

The description states a specific verb ('Compare') and resource ('uploaded media'), and clarifies it operates on multiple assets at once. It distinguishes itself from serial look_at_asset calls, though the name 'compare_uploaded_media' is somewhat generic and the description's unusual formatting makes the core purpose less crisp than it could be.

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

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

The description explicitly says to use this instead of serial look_at_asset calls when choosing/order-casting a reel, montage, B-roll library, or multi-clip story. It also states what it does not do ('does not rank by upload order, does not silently shortlist'), giving clear when-to-use and when-not-to-use guidance.

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

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

Beyond the bare annotations, the description discloses meaningful behavior: it is project-scoped to the explicit project_id, saves a video_clip, does not place it in the program until insert_media, omits audio, and caps duration at 1-20s. This gives the agent clear expectations about side effects.

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

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

The description is dense but every sentence serves a purpose: scope, core behavior, anti-pattern warning, parameter semantics, and post-processing notes. It is front-loaded with project-scoping, though the repeated 'PROJECT-SCOPED' phrasing is somewhat redundant.

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

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

The description covers composition rules, duration limits, file persistence, insertion status, and audio behavior. However, with no output schema, it only vaguely says 'returns the project identity with its result'—it does not specify the exact response shape or whether the operation is synchronous or asynchronous, leaving some uncertainty for an agent invoking 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?

The schema only lists `columns` as a bare array and `duration_s` as a number, with 33% description coverage. The description compensates by explaining the two valid formats for columns (list of asset_keys or list of column clip-lists) and defining each clip's structure as {asset_key, start, duration}, plus the valid range/default for duration_s.

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 precisely what the tool does: 'build ONE 16:9 clip that shows 2 or 3 independent videos side-by-side on a solid BLACK canvas'. It also distinguishes itself from the naive approach ('Do NOT fake this with pad_blur inserts plus small PIP overlays'), making its unique purpose clear relative to sibling tools.

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

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

It gives strong context for when to use the tool—creating the signature multi-panel athlete/action wall—and explicitly warns against faking it with pad_blur inserts and PIP overlays. It also points to follow-up steps: insert_media with fit='pad' and add_music for audio. It doesn't name specific alternative tool names, but the guidance is usable.

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 are all false, so the description carries the full burden. It discloses that the tool selects the new project for navigation, returns a project_id that must be copied into later calls, and that selection does not start automatically for shorts. It also explains the required explicit story arcs for make_shorts. This is exceptionally transparent about side effects and workflow 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?

The description is a single paragraph with multiple sentences, but each sentence earns its place by covering a distinct aspect: creation, side effect, usage options, and the shorts workflow. It front-loads the primary purpose and then adds necessary detail. It is concise relative to the complexity of the tool.

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

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

For a tool with significant behavioral nuance (selection, shorts workflow, required project_id usage), the description covers the main points thoroughly. It does not explicitly mention the default kind ('edit') or error/edge cases, but the schema covers the default and the description provides enough to call the tool correctly in typical scenarios. Given the absence of an output schema, the mention of the returned project_id is helpful.

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 50% (only kind has a description). The tool description adds context for kind ('shorts' creates a Podcast to Shorts intake project) but this largely repeats the schema's own description. For title, no additional meaning is provided beyond the schema's bare string type. The description adds some value for kind but does not compensate for the missing title semantics, so a baseline 3 is appropriate.

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

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

The description states a specific verb ('create'), resource ('empty project'), and a side effect ('select it for navigation'). It clearly differentiates from siblings like open_project and list_projects by focusing on creation and selection, and it also explains the special 'shorts' kind. This is a precise, non-tautological purpose statement.

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

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

It gives explicit usage context: after creation, upload with upload_start or build a canvas program; for shorts, it outlines the post-analysis workflow with make_shorts. It does not explicitly say 'use this instead of open_project', but the creation vs. existing distinction is implicit and clear enough for an agent to decide.

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 are all false, so the description carries the full burden. It discloses that the call is project-scoped, that it splits inserts it crosses, removes footage fully covered, and re-anchors everything in one version write. This goes well beyond the minimal annotations and gives the agent a precise mental model of the operation.

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

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

The description is long but every sentence adds value: scope, behavior, insert handling, use cases, and warnings. It is front-loaded with the project-scoped note and structured logically. It could be slightly tighter but remains efficient.

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

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

For a complex operation with no output schema, the description covers the essential aspects: what it does, how it handles overlapping inserts, when to use it, and what it returns (project identity). It even addresses a common misconception (that cutting inside an insert is impossible). Nothing critical is missing.

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

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

With only 33% schema coverage, the description compensates by explaining that start and end are in OUTPUT seconds and that the range applies to the assembled program. It also clarifies project_id is required and immutable, and that one range per call is allowed. This adds meaning the schema lacks.

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

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

The description clearly states it cuts a span of the ASSEMBLED program in OUTPUT seconds, distinguishing from source-time cuts and explicitly contrasting with set_insert_window. The verb 'cut' and resource 'output range' are specific, and the mention of 'the clock the viewer and the scene map use' adds precision.

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 names the alternative set_insert_window and explains why it is inappropriate ('that changes WHICH part plays, it cannot remove a middle'). It also provides example user requests ('cut 12-15 of the video') and advises batching multiple calls for multiple ranges, leaving no ambiguity about when to use it.

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

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

Despite annotations (readOnlyHint=false), the description adds substantial context beyond them: project-scoping ('PROJECT-SCOPED: this call acts only on the explicit project_id'), the side-effect boundary ('a local edit — the rest of the edit is untouched'), the state change ('Creates a new EDL version'), and the return format ('returns the project identity with its result'). No contradiction with annotations.

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

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

Dense and front-loaded — the critical scoping constraint leads, followed by the operation, side-effect boundary, snap behavior, and sibling routing. Every sentence carries information with no filler, though it packs multiple clauses into long sentences that could be split for readability.

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

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

For a mutation tool with no output schema, the description covers everything an agent needs: scope, one-operation behavior, side-effect guarantee, EDL versioning, snap semantics, return value, and the source-vs-output routing rule. Nothing required to call it correctly is missing.

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

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

Schema coverage is only 25%, so the description must compensate and does: it clarifies that start/end are SOURCE-seconds of the main video (resolving the timeline ambiguity), and explains snap_to_words ('keeps neighbouring words whole'). project_id is already well-described in the schema, and the description reinforces the explicit-scope requirement. Minor gap: snap_to_words is explained but its default is not stated.

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 says 'Remove ONE source-time range from the current keep set' — a specific verb (remove), resource (source-time range in keep set), and operation scope. It explicitly names cut_output_range as the sibling it is not, telling the agent apart from the edited-output sibling without opening either schema. This is precise and unambiguous.

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

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

It gives explicit when/when-not guidance: 'SOURCE seconds of the main video ONLY — when the user gives times of the EDITED video... use cut_output_range.' It names the specific alternative and the exact condition that selects it, which is the gold standard for usage routing.

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

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

Despite annotations being sparse (all false), the description fully discloses behavior: trimming mechanics (min_silence_s, padding_s), word-edge snapping to avoid clipping, refusal logic (>=50% audible gaps and 25%+ removal), and the requirement to set allow_nonquiet only with user permission. No contradiction with annotations.

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

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

Every sentence earns its place. Key scoping and single-call positioning are front-loaded, defaults are given inline, and the safety guardrails are stated without redundancy. Dense but efficiently organized.

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

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

For a tool with 4 params, no output schema, and important failure/refusal behavior, the description covers everything an agent needs: scope, defaults, edge-case refusal, and the recommended verification step. Nothing critical is missing.

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

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

Schema coverage is only 25% (only project_id described), but the description compensates by explaining min_silence_s (default 0.5s), padding_s (default 0.12s), and allow_nonquiet (permission gating). It adds semantic meaning beyond the raw schema, which is exactly what's needed at low 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?

Clearly states it cuts silences in a project with a specific verb+resource. Explicitly distinguishes itself from cut_range ('Do this in one call instead of many cut_range calls') and identifies itself as 'THE tool' for silence trimming, making it unmistakable among siblings.

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

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

Provides explicit when-to-use guidance: the intended use case ('cut the silences', 'tighten this up'), the alternative (cut_range) to avoid, and the follow-up verification tool (get_kept_transcript). Also specifies the condition for allow_nonquiet and the refusal conditions. No guesswork needed.

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?

ReadOnly annotation is reinforced and expanded: URL is temporary, receipt is durable, and the tool cannot create exports. This tells the agent about side-effect-free retrieval and a capability limit.

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

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

Three dense sentences lead with the core purpose, then clarify parameter semantics and limitations. No filler.

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

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

Covers the return behavior (temporary URL, durable receipt) and main kind values, but omits edl_version, response shape, and any conditions/errors. Adequate but not complete.

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

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

Schema coverage is 0%, so all meaning must come from the description. It explains kind and asset_id well, but says nothing about edl_version and only implies project_id. Partial compensation.

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 ('temporary URL for downloading a render') and differentiates itself by clarifying it cannot create a final export, which sets it apart from render/export-style 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?

Implies when to call it — when you need a download link for a render — and notes a negative boundary (cannot create final export), but gives no explicit guidance on when to prefer this over sibling tools or when not to use it.

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

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

Annotations only say not read-only and not destructive, so the description carries the burden. It discloses that it bakes into the source copy, reports fraction of frames found, refuses on no-visible-cursor, and cannot detect clicks in pixels. This is rich, accurate behavior disclosure 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?

Every sentence adds value: scope, purpose, mechanics, parameter meanings, limitations, and side effects. It is dense but efficiently organized, with the most critical constraints (project-scoped, don't guess clicks) front-loaded.

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

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

Given no output schema and low schema coverage, the description covers everything needed: what it does, when to use, parameter semantics, side effects, undo path, and failure conditions. An agent can call it correctly without ambiguity.

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 only 20% (only project_id has a description). The description explains scale (1-4, 2 usual), smoothing (0-1, hand tremor), click_times (source-video seconds, must be provided or asked), and click_highlight (skip ripples). It fully compensates for the sparse 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 action (enhance cursor), the target (small/jittery pointer on screen recording), and differentiates from the undo sibling remove_cursor_enhance. It names the exact problem it solves, making selection 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?

Explicitly says when to use (for small/jittery cursor on recordings) and when it refuses (no visible cursor). It instructs on click_times (pass from record_website_demo or ask user, never guess) and mentions undo via remove_cursor_enhance. Lacks a direct 'use X instead' but 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 are all false, so the description carries the burden of behavioral disclosure. It adds useful context: the call is project-scoped, returns the project identity with the result, and cannot add resolution. However, it does not disclose whether the operation is asynchronous (e.g., requiring wait_for_job), side effects on existing media, or reversibility. Given the mutation nature (readOnlyHint=false), more disclosure would be beneficial.

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

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

The description is dense and front-loads the critical scope and purpose. It is a single block but effectively organized: scope, purpose, parameter details, and limitations. No wasted sentences, though the lack of formatting makes it slightly harder to parse.

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 tool with no output schema, it covers the essential usage, parameter semantics, and key limitations. The main gap is the absence of information about asynchronous behavior or the exact shape of the result beyond 'project identity with its result'. This is a minor omission given the overall richness.

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 only 20% schema coverage, the description compensates fully. It explains sharpen (0-1, default 0.5, purpose), denoise (0-1, default 0, purpose and ordering relative to sharpen), and start/end (program seconds, omit both for whole video). project_id is already described in the schema. All parameters gain meaning beyond the raw schema.

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

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

The description clearly states the tool's function: enhancing picture quality via sharpening and denoising. It explicitly distinguishes itself from look-based tools ('PICTURE QUALITY, not a look') and names the exact user intents it addresses ('make it clearer / sharper / better quality / HD / enhance this'). It also states it is project-scoped, which is a precise scope.

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

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

It provides explicit when-to-use guidance by mapping to user phrases and warns against using it for resolution increases or colour grading. It also gives operational advice like raising denoise before sharpen on noisy footage. It does not name specific sibling tools as alternatives, but the differentiation is clear enough for an agent to select it.

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

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

Annotations only provide readOnlyHint=false, so the description carries the full burden. It discloses that it repaints pixels, reconstructs the original picture, is real removal (not blur), and that other elements (cuts, timings, transcript, captions) remain unaffected. It also mentions the scope default and project identity return. No contradictions with annotations.

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

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

The description is dense and front-loaded with the key distinction (real removal vs blur) and project-scoping. It's slightly verbose with emphatic caps ('TRULY REMOVE', 'REPAINTS THE PIXELS') but each sentence contributes purpose, usage, or behavior. It could be trimmed without losing value, but it's well-structured.

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

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

For a mutation tool with no output schema, it covers purpose, usage, behavior, side effects, and return (project identity with result). It mentions scope default. The main gap is lack of explanation for start/end parameters, but they are likely self-explanatory. Overall, it gives sufficient context for an agent to decide and call correctly.

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

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

Schema description coverage is only 25% (only project_id has a description). The description adds meaning to scope ('scope defaults to captions') and reinforces project_id as explicit scope. However, start and end parameters are not mentioned in the description, leaving their semantics undocumented. It partially compensates for the low schema coverage but not fully.

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 ('TRULY REMOVE') and resource ('burned-in captions or watermarks'), and clarifies it repaints pixels rather than blurring or barring. It explicitly distinguishes from add_captions and implies it's for text burned into footage, making it distinct from siblings like erase_region or remove_text.

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 lists when to use: for 'remove the captions' / 'take the subtitles off' / 'get rid of the watermark' on burned-in text, and before add_captions to avoid stacking. It also states exclusions ('Cuts, timings, transcript and captions are unaffected') and mentions the project-scoped requirement. However, it doesn't explicitly say when NOT to use alternatives like remove_text or erase_region, so it's clear but not exhaustive.

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

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

The description claims the tool 'TRULY REMOVE[s]' content, which is a destructive operation, but the annotations declare destructiveHint: false. This directly contradicts the annotation. Since the description contradicts the structured metadata, it scores 1 per the rules, even though the description is otherwise rich with behavioral detail (repaint, reconstruction, performance, return of project identity). The contradiction is flagged.

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

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

The description is long but every sentence serves a purpose—scoping, behavior, use cases, parameter details, performance, and limitations. It is front-loaded with the most critical information ('PROJECT-SCOPED' and 'TRULY REMOVE'). It is well-structured with clear punctuation and logical flow. It is slightly verbose but not wasteful, so a 4 rather than 5.

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

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

For a complex tool with 9 parameters, no output schema, and low schema coverage, the description is remarkably complete. It covers all parameters, explains performance trade-offs, advises on coordinate sourcing, discloses limitations, and notes that the result is measured and reported back. An agent has everything needed to decide when to use it and how to invoke it correctly.

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

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

Schema description coverage is only 11% (only project_id has a description), so the description must carry the burden of parameter semantics. It does so excellently: x,y,w,h are defined as top-left corner and fractions of the source frame; fill is explained with 'text' vs 'box' meanings; start/end are described as source-second windows; and the regions array is explained. It even tells the agent to get coordinates from find_burned_text. This fully compensates for the sparse 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 explicitly states the tool 'TRULY REMOVE whatever is inside a rectangle — repaints those pixels and reconstructs the background, so the thing is GONE, not covered.' It names specific use cases (word, sign, sticker, logo, person's name) and distinguishes itself from siblings like blur_region or erase_burned_text by emphasizing true removal rather than covering. This is a clear, specific verb+resource with strong differentiation.

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

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

The description provides clear usage context: 'Use it for a word, a sign, a sticker, a logo, a person's name on screen, or any object the user wants taken out.' It also advises getting coordinates from find_burned_text rather than estimating, and explains that multiple marks go in one call. It mentions limitations (large objects on moving backgrounds may leave a soft patch) but does not explicitly name alternative tools or say 'do not use for X', 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?

Beyond the annotations (all false), the description discloses critical behavior: it is project-scoped, acts only on the explicit project_id, returns the project identity, changes no media or EDL, and is not a tool limit. This adds valuable context about side effects and scope that annotations do not provide.

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

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

The description is a single dense sentence with several clauses, but it is front-loaded with the most critical scoping note. Every sentence earns its place—no filler—though a slightly more structured format (e.g., separating usage condition from side-effect disclosure) would improve readability.

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

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

For a simple schema-expansion tool, the description covers scope, side effects, usage trigger, and immediate next steps. It does not specify the exact return format beyond 'project identity with its result', and does not mention error handling or what happens with invalid domains, but these are minor gaps given the tool's simplicity and the lack of an output schema.

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

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

Schema coverage is 50% (project_id has description, domains does not). The description adds context that 'domains' are the capabilities to load, but does not explain how to select them or what each domain maps to. The enum values are in the schema, so the description partially compensates but could be more explicit about the domains parameter's 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?

The description explicitly states the tool loads additional tool schemas for the next reasoning step when the current catalog lacks a needed capability. The verb 'load' and resource 'tool schemas' are specific, and the tool is clearly distinct from all siblings (none of which perform this function).

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 explicit condition for use: when the compact catalog does not expose a capability you need. It also instructs to 'request any relevant domains, then continue immediately', making the usage scenario concrete. No alternative tool is named, but none exists—this is a unique capability.

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

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

Annotations provide no hints (all false), so the description carries the burden. It discloses project-scoping ('acts only on the explicit project_id and returns the project identity'), that the picture is never shown, and that silent clips are reported rather than claiming sound was added. These are valuable behavioral traits beyond the schema. It does not explicitly mention side effects like file creation, but the description implies saving an audio file, and destructiveHint=false covers safety.

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 longer than average but every sentence adds value: project-scoping note, purpose, examples, usage guidance, and edge-case behavior. It is front-loaded with the critical scope constraint and remains focused without redundancy. Slightly verbose but justified by the tool's complexity.

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

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

For a tool with no output schema, the description provides everything needed: how to obtain the asset_key, what the return value is (a new storage_key), how to use that key, when to use this tool vs. direct placement, and handling of silent clips. It fully equips the agent to call this tool correctly without additional lookup.

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

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

The schema describes project_id in detail, but asset_key is only a bare string. The description compensates by stating 'asset_key is a [video_clip] storage_key from list_assets,' which is essential for correct invocation. Since schema coverage is 50%, this added meaning raises the score from baseline 3 to 4.

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

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

The description explicitly states the action: 'Take ONLY the sound out of an uploaded VIDEO and save it as an audio file,' with concrete user-phrase examples ('use the song from this clip'). It clearly distinguishes from sibling tools like add_music by explaining that this tool returns a storage_key for later placement, so the agent knows exactly what this tool does and what it does not.

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

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

The description gives explicit usage guidance: 'call this when you want the file first (e.g. to get_audio_analysis its beats)' and contrasts with the alternative of passing the clip key directly to add_music/add_sfx/add_voiceover, which achieves the same in one step. It also notes that nothing enters the edit until placed, preventing misuse.

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

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

Annotations are all false, so the description must carry the behavioral burden. It discloses that the call is project-scoped, returns the project identity, downloads a single result, and returns a storage_key. It also notes the license handling. It does not state idempotency or side effects, but for a fetch/download operation the provided details are reasonably transparent.

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 project-scoping note. Each clause adds value: scope, operation, return value, and license instruction. No filler words or redundancy.

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

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

With no output schema, the description must explain the return value, which it does (storage_key for add_sfx, plus project identity). It covers the core workflow and the license obligation. It does not describe error cases or confirmation of download, but for a simple fetch the essentials are present.

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

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

Schema coverage is 50%: project_id has a descriptive note, id has none. The description clarifies that 'id' is the search_sfx result id (by its id), adding some meaning. It does not elaborate on id's format or provenance, so the description partially compensates but leaves room for more 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?

The description clearly states the verb 'Download' and the resource: a search_sfx result identified by its id, scoped to a project. It also mentions the return value (storage_key for add_sfx), distinguishing it from search_sfx (searching) and add_sfx (adding), and is explicit about the project-scoping.

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

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

The description implies when to use it: after search_sfx has returned results, to fetch one into the project for later addition via add_sfx. It also gives a specific guideline about repeating the license line when there is an obligation. However, it does not explicitly state when not to use it or name alternatives beyond the implicit add_sfx dependency.

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

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

Goes well beyond annotations. Annotations indicate mutation (readOnly=false) and non-idempotency, but the description adds critical details: it saves the asset but does not add it to the video until later, it returns a RIGHTS CHECK that must be relayed, and it verifies neither ownership nor license. Also clarifies the project_id scoping behavior.

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

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

The description is dense but efficiently organized. It leads with the scope, then the purpose, supported link types, usage rule, as_kind behavior, next steps, and rights caveat. Every sentence adds value, though it could be slightly tighter by trimming redundancy (e.g., the phrase 'download media' appears twice).

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 essential operational context: what it does, what it doesn't do (not added to video), what to do next, and the rights caveat. Lacks details on return structure beyond 'project identity' and 'RIGHTS CHECK', and no error handling or rate-limit info, but these are minor for a fetch tool. The output schema is absent, so description must carry this weight, which it does adequately.

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 only 33% (only project_id has a description), but the description compensates fully. It explains what URL formats are accepted (direct links vs page links), clarifies that as_kind is optional and only for forcing audio extraction, and reinforces project_id immutability. This adds meaning beyond the schema.

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

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

The description clearly states the verb (download media from a LINK), the resource (URL) and the action (save as project asset). It also specifies the project scope. However, it does not explicitly differentiate from the sibling tool download_url, which could overlap in purpose. The phrase 'for something they want in the edit' narrows it to project assets, but a direct comparison is missing.

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-to-use guidance: 'Use this whenever the user pastes a URL for something they want in the edit; never tell them to upload a file you could have fetched.' It also explains when to use as_kind ('only to force audio-only from a video page') and what to do next (insert_media/add_music). This is clear and actionable.

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

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

The description reveals that it reads actual frames, returns exact rectangles as frame fractions, and includes visibility times. It also notes project-scoping and that the project identity is returned. Annotations already declare readOnlyHint=true and destructiveHint=false, so the description adds valuable detail about output format and scope without contradicting them.

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

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

The description is a single dense paragraph where each sentence contributes: scoping, purpose, behavioral detail, alternative usage, read-only note, and parameter explanations. No filler or redundancy; it is appropriately front-loaded with the most critical scoping constraint.

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

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

The description covers purpose, usage alternatives, behavioral expectations, and parameter semantics. It even specifies the return format (exact rectangles as frame fractions, visibility times) despite having no output schema. The only minor gap is that start/end units are not explicitly stated, but 'source-time window' strongly implies seconds, so the tool is sufficiently complete for correct invocation.

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

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

With only 25% schema description coverage, the description compensates by explaining the scope enum values (captions, watermark, text, all) with their meanings, describes start/end as a source-time window, and gives specific guidance for project_id (copy from list_projects/open_project/project_state, never guess from active pointer). This adds meaning beyond the bare 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 action (measure where text is burned into footage), lists concrete examples (subtitle bands, watermarks, handles, on-screen labels), and explicitly contrasts with look_at for estimating rectangles, making the tool's purpose unambiguous and distinct from siblings.

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

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

It directly instructs 'Use this INSTEAD of estimating a rectangle from look_at' and explains the consequence of using the alternative. It also defines each scope value (captions, watermark, text, all) with behavioral distinctions, providing clear when-to-use guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds valuable behavioral context beyond annotations: the call is project-scoped (acts only on explicit project_id), returns project identity with the result, and returns candidate links 'best-guess first'. This enriches the agent's understanding of the tool's scope and output ordering.

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 most critical constraint (project-scoped), then moves to the core purpose, usage pattern, and output handling. Each sentence earns its place: it differentiates from siblings, gives concrete query guidance, and specifies the follow-up actions. 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?

Given the tool's complexity (a search tool with specific usage pattern), the annotations cover read-only safety, and there is no output schema, the description is remarkably complete. It explains what it returns (candidate links best-guess first), the intended workflow (fetch_url, look_at_asset, cutaway), how to handle the results, and what to tell the user. Nothing essential is missing for correct invocation.

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

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

Schema description coverage is only 50% (query has no schema description), but the description fully compensates by explaining that query must be a concrete named thing (e.g., 'spacex starship launch') and not a mood, with explicit examples. It also reinforces project_id's role as an immutable scope, which aligns with the schema's description. The description adds meaning beyond the bare schema.

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

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

The description clearly states a specific verb ('find'), a resource ('real footage of a NAMED topic on the web'), and the project-scoped nature. It explicitly contrasts with search_stock, which covers generic visuals, so an agent can distinguish this from siblings without opening schemas.

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

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

It provides explicit when-to-use vs when-not-to-use guidance: 'search_stock covers generic visuals... THIS covers named people, companies, products, events.' It also outlines the downstream workflow (fetch_url, look_at_asset, cutaway) and how to report usage, leaving nothing to inference.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds behavioral context: it returns the project identity with the result and notes that cut points should snap to midpoints/word boundaries. This goes beyond the annotations without contradicting them.

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

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

The description is two sentences, front-loaded with the most critical scope constraint (PROJECT-SCOPED), and every phrase earns its place. It's efficient 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 simple read-only find operation with no output schema, the description covers the key aspects: scope, parameter semantics, and the expected result behavior (snapping cut points). It doesn't detail the output format, but given the tool's simplicity and the presence of annotations, this is acceptable.

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 50%: only project_id has a description. The description explicitly explains min_seconds ('Silences of at least min_seconds'), adding meaning beyond the bare type in the schema. It partially compensates for the missing schema description, though it could be more detailed (e.g., units).

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

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

The description clearly states a specific verb ('find') and resource ('silences' within a project), and explicitly differentiates the scope (project-scoped) and result (returns project identity and silences). This distinguishes it from siblings like cut_silences, which perform a mutating action.

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 highlights that it operates only on an explicit project_id, implying it should be used when a project is known and silences need to be identified. It doesn't explicitly mention alternatives, but the existence of cut_silences suggests a natural separation, so the usage context is implied rather than fully 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?

Beyond annotations (readOnlyHint=true), the description discloses project-scoped behavior, returns project identity with result, candidate link ordering, version-selection criteria (artist's own/'- Topic' channel, no covers), and the need to disclose licensing limitations. This is rich context not in annotations.

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

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

The description is long but every sentence adds value: scoping, purpose, selection rules, follow-up steps, and caveats. It is front-loaded with PROJECT-SCOPED and then the core purpose. Some redundancy exists but it remains organized and purposeful.

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 no output schema, the description explains that it returns candidate links best-guess first and describes the pick criteria, but it does not specify the exact structure of the result (e.g., fields or error handling). Overall it is quite complete for agent use, but a little more on return format would make it fully self-contained.

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 covers project_id well with a detailed description, but query has no schema description (50% coverage). The description compensates by explaining query is the named song, adding meaning beyond the bare schema. However, it could be more explicit about query format.

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

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

The description clearly states the tool finds web links for a specific named song, with an example ('add Blinding Lights by The Weeknd'), and explicitly contrasts it with generic catalog scenarios. This distinguishes it from siblings like add_music or fetch_url.

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

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

The description explicitly states when to use it (named songs), when not to (genre/vibe requests should ask for user-supplied file/link), and what to do after (fetch_url with as_kind='music'). It also warns about licensing verification, giving clear decision guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering safety. The description adds behavioral detail: it 'returns the project identity with its result', 'scans all tiles in parallel', and produces 'coarse SOURCE timestamps' – useful expectations not implied by the schema. It also frames the query as naming 'one concrete visible event', clarifying the semantic requirement. No contradiction with annotations; the description enriches beyond them.

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

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

The description is dense but front-loaded with key markers 'PROJECT-SCOPED' and 'READ'. Every sentence adds value: scope, behavior, usage, output, and verification steps. It is slightly long but not wasteful; the use of caps and semicolons aids scanning. It earns a high score for structure and 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?

For a tool with 5 parameters, no output schema, and no nested objects, the description covers purpose, usage, output format (coarse timestamps), and a verification workflow. It does not specify how start/end or max_results affect results, nor error handling, but the essential operational details are present. The absence of an output schema is mitigated by the mention of 'returns the project identity with its result' and 'coarse SOURCE timestamps'. Overall, it is sufficiently complete for an agent to call it correctly.

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

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

Schema description coverage is only 20% (only project_id has a description). The description compensates for query by stating it 'names one concrete visible event', and for project_id by emphasizing explicit scope. However, start, end, and max_results receive no semantic clarification in the description, and the schema only provides type and numeric bounds for max_results. Given the low coverage, the description partially addresses parameters but leaves significant gaps.

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

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

The description clearly states the tool performs 'focused semantic search across the COMPLETE indexed main-video filmstrip' and returns 'coarse SOURCE timestamps'. It distinguishes itself from transcript-based search and from sibling tools like look_at by explicitly contrasting with 'serial whole-video look_at probing'. The purpose is unambiguous and tied to a specific resource (the indexed filmstrip).

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

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

It gives explicit when-to-use conditions: 'Use once for a long source when requested highlights are visual rather than transcript-searchable' with concrete examples (gameplay saves/fails, gestures, product appearances). It also provides an exclusion: 'Never replace it with serial whole-video look_at probing' and prescribes a follow-up verification step with 'ONE batched look_at call'. This fully guides an agent on when and how to use it vs. alternatives.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds substantial behavioral context: it's cached after the first call, times are in SOURCE seconds, and it mentions that a confidence below 0.5 makes the pulse unreliable and causes beat_align_cuts to refuse. This goes well beyond the annotations and helps the agent anticipate side effects.

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

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

Every sentence earns its place. The description is front-loaded with 'PROJECT-SCOPED' and 'READ', then delivers precise details without fluff. It's dense but not verbose, and the structure flows logically from purpose to outputs to usage.

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

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

Despite no output schema, the description enumerates all key return values (tempo with confidence, beat count, timestamps, energy sections, stressed words) and ties them to usage. It also addresses the optional asset_key scenario. For a tool with this complexity, nothing essential is missing.

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

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

With only 50% schema coverage, the description compensates thoroughly. It explains project_id as an immutable scope and instructs to copy it from specific tools, explicitly stating the active-project pointer is never used. For asset_key, it clarifies it's an uploaded or fetched music file and gives a concrete use case. This adds significant meaning beyond the schema.

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

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

The description clearly states the tool's purpose: a read-only call that returns musical/energy analysis of the source audio, with specific outputs (tempo, beats, energy sections, stressed words). It differentiates itself by noting it is project-scoped and references sibling tools (beat_align_cuts, punch_in_on_emphasis) and explains how it relates to them. It also mentions the alternative use via asset_key.

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

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

Explicitly states when to use: 'Call before beat_align_cuts / punch_in_on_emphasis, or to answer "what's the tempo".' It also explains the asset_key alternative for analyzing a different asset, with an example. This gives clear context for when this tool is appropriate versus alternatives.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the read-only nature is known. The description adds valuable context: it is project-scoped, requires an explicit project_id (never guesses), and explicitly says it does not prescribe effects, directing the agent to use look_at for visual decisions. This goes beyond annotations without contradicting them.

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

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

The description is dense but efficient, with key info front-loaded (project-scoped, READ, cross-modal timeline). Each sentence earns its place: scope, content, usage guidance, caveat, and parameter notes. It is longer than average but warranted given the tool's complexity. No redundancy or filler.

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

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

The description thoroughly explains the output content (sentences/shots, shot changes, energy/trend, beats, stress, pauses, face/UI evidence) and clarifies what the tool does not do (prescribe effects). It also notes the need for look_at for visual decisions and explains asset_key. With no output schema, this description carries the burden well. The only gap is the lack of detail on start/end/limit parameters, but those are likely self-explanatory time and count ranges.

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 only 17% (only project_id has a description). The description compensates partially: it explains that asset_key is for an indexed uploaded clip and enumerates focus options ('focus can be all, story, visual, energy, faces, ui, quiet or peaks'). However, it does not explain start, end, or limit parameters, which are likely time range and result count. The description adds value but does not fully compensate for the low coverage of all parameters.

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

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

The description clearly states the tool's purpose: it returns a project-scoped, compact cross-modal SOURCE timeline with detailed evidence (sentences/shots, shot changes, energy, beats, stress, pauses, face/UI evidence). It explicitly differentiates from reading transcript, shots, and audio analysis separately, and distinguishes itself from sibling tools like get_shots, get_transcript, and get_audio_analysis.

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-to-use guidance: 'Use this instead of separately re-reading transcript + shots + audio analysis when directing a substantial reel, podcast, montage or B-roll/SFX/motion treatment.' It also states limitations: 'It aligns evidence but does not recognize the full picture or prescribe effects: inspect filmstrips/look_at before visual choices.' This gives the agent clear conditions for 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds meaningful behavioral details: large timelines return a compact index instead of truncated JSON, aliases are accepted without retry, and compact=true returns counts, caption state, and duplicate assets. This goes beyond the annotations.

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

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

The description is dense but well-structured, starting with the scoping constraint and then covering return format, large-timeline behavior, and parameter usage. Each sentence adds value without redundancy, 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?

Without an output schema, the description explains what is returned (current EDL JSON, version, compact index) and how to request specific sections. It covers all five parameters effectively, and for a read-only tool with clear annotations, the information is sufficient for an agent to call it correctly.

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