Valmera — agentic AI video editor

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

Annotations already mark this non-readonly/non-destructive, and the description adds genuinely new behavioral context beyond them: it acts only on the explicit project_id and returns the project identity, it caps flashes for safety, and it adds neither sound nor zoom. It does not disclose reversibility or undo semantics, keeping it below 5.

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

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

It is front-loaded with the project-scoping constraint, which is good, but the rest is a dense run-on wall of jargon-heavy clauses with inconsistent structure. Most clauses carry information, but readability suffers and some (e.g. re-listing kind values already in the enum) partially duplicate structured data.

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 16-param, nested-object, no-output-schema mutation, the description covers scoping, placement, density, and safety but leaves more than half the parameters undocumented. An agent could place accents correctly but could not confidently set intensity, count, or seed without guessing.

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

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

Schema coverage is only 13% across 16 params, so the description must compensate, and it does explain at (program seconds), on (beat|downbeat|onset restricted to user-supplied tracks), density (sparse = strongest, >=2s gaps), scope='all', and region {shape:'card'}. However many params — intensity, count, seed, bands, colour, frames, decay_f, start/end — get no explanation anywhere, leaving substantial 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 states a specific verb+resource ('1-N-frame punctuation on the speech') and enumerates concrete accent kinds, and it distinguishes itself from siblings by declaring 'Adds no sound or zoom' (vs add_sfx/add_zoom/add_strobe). The heavy jargon makes the core action slightly opaque on first read, but the resource and effect family are identifiable.

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 actionable when/when-not rules: 'One punctuation family per section; never inside a payoff hold', 'beat|downbeat|onset only on a track the USER supplied', and 'Flash safety keeps <=3 full-frame flashes a second unless the user asked for strobing'. It does not name sibling alternatives to route between, so it stops short of a 5.

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

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

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?

Annotations already declare write (readOnlyHint=false), non-destructive, and non-idempotent, so the safety profile is covered. The description adds two genuinely useful behavioral facts: the call is strictly project-scoped and it returns the project identity with the result. It still doesn't say what the operation mutates or whether a project must be open, so it earns only partial credit.

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 front-loaded 'PROJECT-SCOPED' clause is well-placed, but the remaining two sentences are opaque metaphor ('a meta beat', 'explaining itself') that consume space without conveying actionable 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?

A non-idempotent write tool with 7 undocumented parameters and no output schema needs the description to carry meaning, and it largely doesn't — parameter behavior, target of the edit, and result shape beyond 'project identity' are all unstated.

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?

Seven parameters with 14% schema coverage; only project_id is described. The prose ('cut, graphics, devices, world, camera, sound lanes, true names') gives no meaning to start, end, title, follow, id, or the position enum. The description does not compensate for the schema gap at all.

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 tool name and title say 'Add breakdown', but the description never states plainly what is added or where — it instead riffs on what a breakdown conceptually is ('the edit explaining itself', 'a meta beat'). Against siblings like add_title_card or add_captions, an agent cannot tell what asset this creates or how it differs. The 'PROJECT-SCOPED' prefix is the only concrete framing.

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

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

There is no when-to-use or when-not-to-use guidance relative to the many add_* siblings, nor prerequisites beyond the project scoping note. The scoping directive ('acts only on the explicit project_id... never used to guess') is useful but is about parameter mechanics, not tool 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 only declare the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the description usefully adds that the call is project-scoped and returns project identity, that it deterministically auto-selects a treatment when style is omitted, and that position/anchor_y 'lock' placement for the whole video. It does not state what happens to pre-existing captions or whether repeated calls stack, which is a real gap for a non-idempotent mutation.

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

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

This is a ~600-word wall of prose with no bullets, paragraphs or line breaks, forcing an agent to parse dense run-on sentences to find anything actionable. Capitalized section markers (PROJECT-SCOPED, PREMIUM PRESETS, MOTION LOOKS, PLACEMENT, SAFE DEFAULTS) give some structure, but the sheer length and lack of scannability are a serious usability defect for a tool description.

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

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

Given a complex tool with 8 parameters and a ~22-field nested style object plus no output schema, the description covers an unusually complete surface: modes, preset catalog, motion looks, default-selection behavior, placement rules, emphasis auto-selection, production controls, and two worked examples. Nothing an agent needs in order to invoke it correctly appears to be missing, even if the presentation is unwieldy.

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 enums carry no descriptions, so the description must compensate — and it largely does, explaining mode values, items shape, the meaning of every major preset and motion_look, plus style fields like highlight_color, uppercase, single_line, size_scale, animation and max_words_per_caption. Coverage is broad but not exhaustive (e.g. outline_color/outline_width/shadow/background_* are only name-dropped), and it does not cover min_words_per_caption or motion_motif beyond the schema text.

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

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

The description states a specific verb and resource — 'Burned captions' — and pins the scope ('acts only on the explicit project_id and returns the project identity with its result'). An agent can tell it produces burned-in captions, but the purpose sentence is buried under a torrent of preset/motion detail rather than front-loaded, and it never explicitly distinguishes itself from siblings like add_text, set_caption_style or audit_captions.

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

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

There is substantial usage guidance: mode='from_transcript' is marked recommended, emphasis_words should be passed verbatim 'only when specific words are required, or [] to explicitly disable hierarchy', and multi-word presets 'default to the BOTTOM... do not move them to middle'. It lacks explicit when-to-use-this-vs-alternative-tool guidance and any exclusion conditions, so it stops short of a 5.

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

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

Annotations already declare the mutation/safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the bar is lower, and the description adds real context on top: the PROJECT-SCOPED constraint (acts only on explicit project_id, never the active-project pointer), a hard 'Up to 64' tile cap, and the fact that the project identity is returned with the result. It does not say what happens to existing elements or the required permissions, but multiple concrete behaviors beyond the annotations 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 PROJECT-SCOPED constraint is front-loaded, which is good, but the body is dense marketing prose ('A living wall of REAL footage', 'tiles pop on ... breathe, collapse tile by tile') and ends with the cryptic fragment 'video plays'. Some of the descriptive language does carry information, but the structure buries concrete parameter guidance inside it.

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

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

For a 13-parameter mutation tool with 8% schema coverage and no output schema, the description is not complete enough: most parameters are undocumented, return behavior is only hinted at ('returns the project identity'), and effects on existing timeline content are unstated. It covers the highest-value fields (kind, tiles) but leaves clear gaps.

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

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

Schema description coverage is only 8% (just project_id), so the description must carry the load and only partially does. It documents the critical 'tiles' syntax ('asset:<key> | source:<seconds> | <storage key>'), the 64-tile limit, and the three 'kind' enum meanings, and hints at 'at' (beats) and 'hero' (hero tile) — but 8 of 13 parameters (id, start, end, title, kicker, layout, backdrop, collapse_at) go unexplained in both schema and 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 conveys the resource (a collage of 'REAL footage') and enumerates the three modes (mosaic, scroll_wall, flatlay), so an agent knows roughly what gets created. However, it never states the core act plainly — that a collage element is added to the timeline between 'start' and 'end' — instead leading with the impressionistic 'A living wall of REAL footage'. There is no differentiation from the many sibling add_* 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?

No when-to-use or when-not-to-use guidance is given, and no alternatives are named despite dozens of sibling add_* tools (add_overlay, add_motion_graphic, compose_panels, etc.) that a user might confuse this with. Usage is only implied by the description of the visual effect, leaving the agent to infer when a collage is the right choice.

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

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

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

Annotations only cover the safety profile (not read-only, not destructive, not idempotent); the description goes well beyond by disclosing no generation cost, always-available synthesis, no image/video generation, project-scoped return of project identity, silent-by-default with optional library SFX selection logic, and that captions never land on it. These are exactly the operational facts an agent needs that annotations cannot express.

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

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

Front-loaded with the project-scoped constraint and the core action, and nearly every clause carries real information (enum meanings, defaults, cost, timing). It is long for a single paragraph and some clauses could tighten, but little is wasted.

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

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

No output schema exists, yet the description notes the return carries the project identity, and it fully covers timing semantics, defaults, cost, and caption behavior for a non-destructive insertion tool. An agent has everything required 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 schema coverage at 17%, the description carries the burden and does: it defines all three style enum values, intensity's 0-1 range and 0.7 default, the SHORT duration guidance, at_output_s as PROGRAM seconds with downstream shift behavior, sound's default and its glitch_1/glitch_2 selection rule, and reiterates project_id's scoping immutability. This is richer than the schema itself.

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

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

States a specific verb and resource ("Cut to a full-frame CORRUPT / glitch screen for a beat") and distinguishes it from lookalikes by naming the analogue ("Synthesized locally like the colour cards") and by clarifying it is a transition BETWEEN sections rather than a section replacement. An agent can separate it from add_color_screen, add_strobe, or add_screen_takeover without opening a schema.

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

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

Gives concrete when-to-use context ("a datamosh-style transition BETWEEN sections (e.g. podcast -> CORRUPT -> the next scene)") and practical constraints ("Keep it SHORT (0.3-1s reads as a hit)", sound optional). It does not, however, explicitly route the agent to or away from a named sibling tool, so it stops short of full alternative-selection 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 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?

Annotations already carry the safety profile (not read-only, non-destructive, non-idempotent, closed-world), and the description adds substantial context beyond them: the PROJECT-SCOPED immutability of project_id, that the project identity is returned with the result, and temporal behavior (word binding, held frames starting at word end, allow_speech override). No return format detail or rate limits, but the added context is meaningful.

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 scope statement is front-loaded, which is good, but the body is a single dense run-on paragraph of stacked parentheticals with no grouping by device or parameter. It contains no filler, yet the density and lack of structure make it harder to parse than the information warrants.

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

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

For a 22-param mutation tool with low schema coverage and no output schema, the description covers scope, returned value, device semantics and temporal rules, which is solid. It still omits many parameter meanings and any sibling differentiation, so it is adequate rather than complete.

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

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

Schema description coverage is only 23% on 22 params, so the description must compensate and it does for the semantically hard ones: it glosses kind's enum values, asset_key, src_t, word, focus_from/focus and allow_speech. Many parameters remain unexplained in both schema and description (blur, move, rack_at, density, strength, backdrop, stage, threshold-like numerics), leaving the coverage gap only partially closed.

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

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

States a specific verb+resource ('add depth effect') and enumerates the distinct devices it produces (parallax 2.5D move, ken_burns 2D move, dof, rack_focus, point_cloud, push_through), which lets an agent distinguish variants internally. However it never names or contrasts a sibling tool (e.g. add_zoom, animate_still, add_subject_effect), so the boundary against neighbours is left for the agent to infer.

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

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

Gives real when-to-use conditionals per device: push_through 'only when the user asked for a push', held frames 'start as the word ENDS and never sit over speech', and the editorial rule 'one per moment that earns it'. It is missing explicit when-NOT/exclusion guidance naming an alternative tool, so it stops short of a 5.

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

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

Annotations already declare readOnly=false, destructive=false, idempotent=false, openWorld=false, so the safety profile is covered. The description does add genuine non-annotation context — the call is project-scoped on an explicit project_id and returns project identity with the result — but it says nothing about the mutation semantics that idempotent=false implies (does each call stack a new stage? does it replace?) or about timeline 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?

Only two sentences, but they are dense run-ons loaded with inline syntax notation, and the front-loaded content is a scope caveat rather than the action. The reader must parse past 'PROJECT-SCOPED' and a list of device nouns to grasp what the tool even does.

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

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

For a 10-parameter, low-coverage, annotation-only tool with no output schema, the description should carry more weight. It omits the required 'start' parameter, ignores id/title/end, and gives no guidance on how this stage relates to or replaces existing device stages, so an agent cannot call it confidently.

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

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

Schema description coverage is only 10% with 10 parameters, so the description is expected to compensate, and it does explain the non-obvious ones: screen source syntax (asset:<key> | source:<seconds> | <storage key>), breakout as [x0,y0,x1,y1] screen fractions, and breakout_element with breakout_at. However, required parameter 'start' and the id/title/end parameters are left entirely unexplained, leaving real 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 gestures at the resource — a screen recording placed inside a drawn laptop/phone/tablet/monitor mockup — but never states the verb plainly and wraps the core idea in poetic phrasing ('its light spilling on the stage'). An agent can roughly infer 'add a device-framed screen,' yet nothing crisply distinguishes it from siblings like add_screen_frame, set_screen_frame, or suggest_devices.

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

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

There is no when-to-use, when-not-to-use, sequencing, or prerequisite guidance. The alternative flows (e.g. suggest_devices for choosing a frame, set_screen_frame for adjusting an existing one) are never referenced, so selection between device-related siblings is left entirely to inference.

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

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

With annotations present, the description still adds real behavioral context beyond them: it declares the call is PROJECT-SCOPED, acts only on the explicit project_id (never the active-project pointer), and returns the project identity with its result. It also explains attach semantics ('rides it on the world') and clarifies that light composites as light. It does not discuss reversibility or failure modes, but the annotation-covered mutation profile plus this added scope/return detail is solid.

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 PROJECT-SCOPED constraint is correctly front-loaded, and the dense kind catalogue is reasonably compact for 19 parameters. But the body is a semicolon-chained run-on laden with project-specific jargon ('one family verb', 'embers off its edge'), which makes it harder to parse than its length warrants.

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 19-parameter mutation tool with no output schema and near-zero schema descriptions, the definition covers scope, return identity, the kind taxonomy, key modifier semantics, and exclusions. It still omits units/defaults for timing parameters and the meaning of several secondary parameters, so it is close to but not fully sufficient on its own.

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 5% (1 of 19 params documented), so the description must compensate and largely does: it explains emit targets (edge|point|box|frame), 'at = burst times', 'box = from x0,y0 to x1,y1' for lightning, and attach values ('head', 'hand.index_tip', 'track:tr1', or natural-language phrases). Several parameters (start, end, count, intensity, colour, palette, style, text, images, id) remain unexplained and units for start/end are unstated, so it is strong but not complete.

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 the tool adds a 'procedural element or a light device' and enumerates the concrete kind families (light effects, particle emitters, doodles, lightning, orbit, shapes, pictogram, sprites), so an agent can tell what gets created. It also separates itself from siblings by declaring it adds no sound and no zoom. The opening phrase 'one family verb' is cryptic, but the resource and scope are otherwise clear.

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

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

It gives usable selection context by describing what each kind does (e.g. 'light_dissolve (the figure turns to light)', 'lightning (box = from x0,y0 to x1,y1; at = strikes)') and an implicit exclusion ('nothing here adds a sound or a zoom'), which routes agents away from add_sfx/add_zoom. However it never names an alternative tool or states a when-to-use/when-not condition explicitly, leaving the agent to infer.

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?

Adds real context beyond annotations: the call is PROJECT-SCOPED and returns the project identity with its result, matte_weighted alters the subject in thermal/xray, stage=over_type also finishes the type, and 'short luminance flips count as flashes' warns of a flashing safety constraint. Annotations only declare non-readonly, non-destructive, non-idempotent; the description usefully extends this, though it omits permission/auth needs and mutation-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?

Front-loads the important PROJECT-SCOPED constraint, which is good structure. However the middle is dense jargon, and sentences like 'Variants are metaphors (mechanism, inside the body, data), never decoration' and the trailing flash note are cryptic rather than crisp, so it neither wastes fully nor earns every line.

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

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

For a 15-parameter, nested-region effect tool with no output schema and only 40% param coverage, the description establishes scope and a few key behaviors but leaves many parameters and the return shape unexplained. It is adequate but leaves clear gaps an agent would need filled.

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

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

With 15 params at 40% schema coverage, the description carries some of the burden: it explains matte_weighted and stage=over_type, and implies start/end range semantics. But the kind list merely restates the schema enum, and id, scale, origin, region, palette, strength, direction, ramp_in_f and ramp_out_f remain undocumented in both places, so it only partially compensates.

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: it applies a 'picture finish' over a [start, end) range and enumerates the finish kinds (lcd/crt/led, halftone, film, thermal, etc.). An agent can tell it adds a named finish effect. However, it never contrasts itself with near-neighbours like add_stylize, add_custom_filter, or apply_look, so sibling differentiation is left implicit.

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

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

No explicit when-to-use or when-not-to-use guidance appears. There is no mention of alternatives (add_stylize, apply_look) or prerequisites beyond the project-scoping note. The claim that variants are 'metaphors ... never decoration' is stylistic doctrine, not routing guidance.

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

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

With annotations only covering the safety profile (not read-only, not destructive, not idempotent), the description carries the load and delivers: it states that 'pause' is a real cut that shifts everything after it, that 'continue' keeps speech/music/timeline intact while covering only the picture, that text/subtitle are burned and bound to the frozen frame, and that project scope is never guessed from the active pointer. These are non-obvious, consequential behaviors that go well 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?

Front-loads the project-scope guarantee and the core action well, and most sentences carry real information. However it is a single dense ~200-word paragraph with editorializing flourishes ('the pearl / power-phrase move') and repeated restatement of the audio_mode semantics, making it harder to scan than it needs to be.

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 mutation with no output schema, the description covers the effect, all three audio modes, numeric ranges, and the binding behavior of text. The notable gap is the entire typography sub-system (font, template, color, accent_color) and any indication of how the inserted freeze frame is identified or removed later.

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 8% across 13 parameters, so the description must compensate, and it largely does: it defines at_output_s as the moment in the edited video, gives duration_s ranges and defaults (2-4s, default 1.0, 0.8-1.5 for a laugh), constrains blur to 0-1 and darken to 0-0.85 with classic values, enumerates motion behaviors, and explains all three audio_mode values. It leaves font, template, color, and accent_color entirely undescribed, which prevents a 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 a specific verb and effect ('FREEZE the picture and hold it') and immediately scopes it as project-bound. An agent knows this creates a held-frame moment with optional burned text. It does not explicitly distinguish itself from close siblings like add_time_effect, add_zoom, or add_title_card, which keeps it from a 5.

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

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

Gives real conditional guidance inside the parameter prose: audio_mode='continue' is for holding over an ongoing phrase without desyncing audio, audio_mode='hold' is the end-of-programme payoff, and it explicitly says to use 'hold' only when the source has no natural tail and to run restore_range first. The strongest exclusion/alternative pairing exists, though it is buried rather than framed as tool 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 mark this as a non-idempotent, non-destructive mutation. The description adds genuinely useful context beyond the annotations: that the call is strictly project-scoped via explicit project_id and that it returns the project identity with the result (helpful since there is no output schema). It stops short of saying what is modified when re-invoked or how the added furniture interacts with existing overlays.

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?

Reasonably short, but the scope statement is front-loaded while the actual purpose sentence is buried in stylized phrasing ('small, steady, in the brand colour, clear of the corner mark'). That stylistic clause costs space without adding callable 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 15-parameter mutation with 7% schema coverage and no output schema, the description covers a good share of the boolean furniture flags and discloses both the project scope and the return shape. It leaves several string parameters (id, accent) and the start/end range semantics unexplained, so an agent still cannot configure the call confidently.

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

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

Schema description coverage is only 7%, so the description must carry the load and it partially does: it maps tl/tr/bl/br, rec, timecode, brackets, crosshair, grid, and colour (brand colour) to their intent. However it says nothing about id, accent, or start/end, and gives no format guidance for the corner-label or colour strings.

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 never states a plain verb+resource ('adds an HUD overlay'), instead using framing jargon like 'Frame furniture through the piece'. The enumerated elements (corner labels, REC dot, timecode, brackets, crosshair, grid) do let an agent infer the resource, but only after parsing. No differentiation from siblings such as add_overlay, add_title_card, or set_screen_frame.

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 only scope guidance is 'Defaults to the whole program', which implies a range default but not when to reach for this tool versus add_overlay/add_screen_frame. There are no stated prerequisites, exclusions, or 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 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 declare non-readonly, non-idempotent, non-destructive, closed-world, but the description adds real behavioral substance: the track is copied once and registered with its licence, it is project-scoped and returns project identity, placement mirrors add_music (whole program by default, ducked under speech, looped to fill), and default gains are disclosed (-18 dB ducked, -4 dB as lead). It does not clarify what happens on an invalid/duplicate slug, which is the one gap for a non-idempotent mutation.

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

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

Front-loads the critical PROJECT-SCOPED constraint, then routing, then behavior, with essentially no filler sentences. It is dense and slightly long for a single paragraph, but each clause carries a distinct constraint or default.

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

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

For a 12-parameter, no-output-schema mutation tool with only 33% schema coverage, the description covers scope, provenance, agent workflow, placement semantics and audio defaults well. It is not fully complete because several numeric placement/fade parameters remain unexplained outside the schema.

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

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

Schema coverage is only 33%, so the description must carry more weight. It explains slug provenance, the gain_db default of -18 dB, duck semantics, and loop-to-fill, but leaves start, end, purpose, fade_in_s and fade_out_s undocumented in both places. Baseline 3 is appropriate given partial compensation 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?

States a specific verb+resource (place a CC0 library track by slug) and immediately differentiates itself from siblings by naming list_music_library as the source and add_music as the placement analogue. An agent can tell this apart from add_music, swap_music, or list_music_library without opening any schema.

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

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

Explicit routing rules: get the slug from list_music_library, never choose music yourself, offer 2-4 tracks via ask_user and place the one the user picks, with a concrete exclusion ('a mood or some music is not a pick'). This is a genuine when/when-not with a named alternative tool.

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

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

Annotations only declare the basic safety profile; the description adds substantial non-obvious behavior: project-scoped return identity, write rejection when the composition errors or draws nothing, caption-drop behavior, face keep-out moves, NUMBER LANDED/CUT-SNAP replies, and headline-band yielding. None of this contradicts 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 uppercase section labels provide structure, and the core purpose is front-loaded, but the description is extremely long and dense. Several points, especially mute_captions semantics, are repeated from the schema, and the sheer volume of edge cases makes it far from concise.

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

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

Given the tool's complexity and lack of an output schema, the description is highly complete: it explains return reporting, caption interactions, face keep-out, number landing, cut snapping, tiers, headline bands, and cover behavior. An agent has enough context to invoke it without surprises.

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 46%, but the description compensates for most critical parameters: start/end are program seconds, end defaults to template duration, layer values are explained, mute_captions has detailed semantics, and sfx/html/headline/cover parameters are covered. It still leaves id and purpose unexplained, and box is handled only by the schema.

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

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

States a specific verb and resource: "Place a browser-rendered, After-Effects-grade motion graphic on the PROGRAM clock." It also clarifies project scoping and output identity, but does not clearly differentiate itself from sibling graphic tools such as add_vector_graphic or add_kinetic_text; it only references add_text_behind as a behavioral analogue.

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 rich in-tool guidance: sfx=true only for a moment that earns sound, layer defaults, 1-2 hero moments per short, and cover usage for some shorts but never every one. It lacks explicit tool-level alternatives among the many graphic siblings, so an agent still has to infer when to use this rather than add_vector_graphic/add_kinetic_text.

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

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

Annotations already mark this as a non-read-only, non-destructive, non-idempotent, closed-world tool. Beyond that, the description discloses context-aware audio defaults (-18dB bed with ducking vs -4dB lead with no ducking), default fades, default looping, default smooth sidechain ducking, and the set_music_fit alternative. These are meaningful behavioral traits an agent needs in order to predict the edit.

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

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

The description is dense but appropriately sized for an 11-parameter editing tool with low schema coverage. It front-loads scope and purpose, then layers defaults, overrides, and routing constraints without wasting sentences. Every clause contributes to correct invocation.

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

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

Given the tool's complexity, low schema description coverage, and lack of an output schema, the description supplies the missing scope, default behavior, override rules, prerequisite asset sourcing, and sibling routing. It even notes that the result includes project identity. An agent has enough context 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 18%, so the description must carry parameter meaning, and it does. It explains start/end as output-timeline seconds defaulting to the whole video, loop and offset_s behavior, gain_db/duck override semantics, storage_key provenance, and default fades. It adds substantial meaning beyond the bare parameter names.

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

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

The description gives a specific verb and resource: 'Mix music into the edit.' It also clearly distinguishes add_music from the sibling add_library_music by stating that library tracks are placed only by add_library_music after the user picks them. The PROJECT-SCOPED framing further clarifies 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 explicitly says when defaults apply, when to override with gain_db/duck, where storage_key must come from, and that agents must never choose music themselves. It also names add_library_music as the alternative for library selections. Omission guidance for start/end is given directly: omit them for 'add some music'.

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 cover mutation/safety flags, and the description goes well beyond them with a dedicated 'HONEST LIMITS' block: video overlay audio is silent, overlays render above footage but BELOW captions, and they do not track objects. It also discloses project scoping and that the project identity is returned, plus asset reuse rules.

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

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

Front-loads the scoping rule and core action, and each sentence carries distinct information (no filler). It is nonetheless a dense block of capped emphasis that an agent must parse carefully; slightly more structure would help, but nothing is wasted.

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

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

For a 13-parameter mutation tool with no output schema, the description covers behavior, limits, defaults, and most parameters, and notes the project identity comes back with the result. The main gap is motion_motif, which is unexplained despite being a non-trivial parameter.

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 15% schema description coverage across 13 parameters, the description carries the burden and delivers: fit semantics and frame.picture interaction, duration defaults per asset type, x/y as center fractions plus the [{t,v}] keyframe format, scale/opacity ranges and defaults, entrance/exit values, and source_start_s. Only motion_motif and the exact meaning of `start` are left unaddressed.

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 — 'Draw an image or video clip OVER the program picture for a window of PROGRAM time' — and immediately names concrete instantiations (picture-in-picture, corner logo, full-frame b-roll cutaway). An agent can distinguish it from add_screen_takeover or insert_media without opening any schema.

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

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

Explicitly names the alternative and the deciding condition: 'insert_media PAUSES the talk and adds time; fit=cover does not — pick by whether the speech should continue.' It also frames the tool's raison d'etre ('THE way to show what the speaker is talking about without touching the timing') and where asset_key comes from.

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 only declaring the safety profile (not read-only, not idempotent, not destructive), the description adds real context: the call is PROJECT-SCOPED, acts only on the explicit project_id (never the active-project pointer), returns the project identity with the result, and leaves everything outside the region untouched. This bounded, non-guessing mutation behavior is valuable beyond annotations. It still omits overlap/interaction behavior with existing 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 scoping constraint is front-loaded in caps, and the sentence is dense with parameter-to-effect mappings rather than filler. It is somewhat run-on in the effect list, but every clause carries 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 non-idempotent mutation with 11 parameters, 18% schema coverage, and no output schema, the description covers scope, affected area, and effect-parameter pairings but omits defaults for non-required parameters, behavior on repeated/invalid regions, and interaction with existing region effects. Adequate but with clear gaps.

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

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

Schema coverage is only 18% over 11 parameters, so the description must carry more weight. It does map key parameters to effects (colour for solarise/tint, ev for exposure, scale for heat) and gives the stage default plus the glyph:<id> region form, but strength, id, and the exact start/end semantics are left unexplained. Partial compensation, not full.

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 adds exactly one effect inside a region over a start-end span, and it enumerates the supported effect values, which tells an agent precisely what this tool produces. It does not explicitly differentiate itself from near-neighbours like blur_region, isolate_colour or add_stylize, so it falls short of a 5.

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

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

There is no when-to-use guidance and no named alternative. The only conditional content is scoping behavior ('outside the region the picture is untouched', 'stage defaults to pre_captions'), which is a behavioral trait, not a routing rule. An agent must infer when this beats siblings like blur_region or add_stylize.

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?

Goes far beyond the annotations (which only cover safety flags) by disclosing behavior an agent could not otherwise predict: the tool pre-rolls a library recording to land its measured peak on `at`, skips into the file near 0s, auto-measures voice loudness and sets gain by sound role unless gain_db is given, adds a short fade for dur_s, and reports CHECK/MIX lines plus NUDGE behavior on payoff-word onsets. Idempotency and side effects are consistent with the non-readonly 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 opening PROJECT-SCOPED clause and the core purpose are front-loaded, and nearly every sentence carries operational detail. It is nonetheless a dense ~350-word block; a few enforcement clauses (pun, bright-sound-on-payoff rule) are restated in both the setup and the CHECK sentence, which costs some 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 7-parameter mutation with no output schema, the description covers input semantics, the auto-gain/peak-alignment behavior, and what the result reports (CHECK lines, MIX line, peak position and played span), so an agent can call it and interpret the response without further 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 coverage is only 14% (only project_id is described), so the description carries the burden and does: storage_key's two valid forms ('sound:<id>' vs. list_assets(kind='music') key) with an explicit 'never invent one', `at` as an OUTPUT-timeline seconds value distinct from source time, offset_s as source-internal offset, purpose's review role, dur_s's fade semantics, and gain_db's unset/default behavior.

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 — 'Punctuate a MOMENT with a one-shot sound effect' — and immediately distinguishes itself from the nearest sibling by declaring 'This is NOT background music: it plays once and never ducks,' which separates it from add_music/add_library_music. The examples (whoosh into a turn, click on a button press) make the intent concrete.

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 frames the tool as OPTIONAL and never a rule, gives quantitative guidance ('a podcast or talking short carries zero by default and at most 1-2'), and states the visual-partner precondition, so an agent knows both when and when not to call it. It also directs the agent to list_sound_library / list_assets for the storage_key and names remove_sfx/move_sfx territory implicitly through scoping.

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?

Annotations only carry the safety profile (not readOnly, not destructive, not idempotent). The description adds genuinely non-structured traits: project scoping ('acts only on the explicit project_id and returns the project identity'), timeline-neutrality ('sound and timing untouched'), and a flash-safety policy requiring the user's consent above 3 changes/second.

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 scoping constraint is front-loaded and every clause carries information (frames formats, enums, safety). It is dense and slightly packed, but there is little 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 10-parameter tool with nested objects and no output schema, the description covers the effect model, most parameter formats, scoping, and the safety policy. Remaining gaps are start/end time units and as_insert behavior.

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

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

At 10% schema coverage the description must compensate, and it largely does: it explains frames entry types (media keys, 'src:<seconds>', 'program', colours, {source, hold_f, negate}), hold range, pattern cycling, negate values, fit including 'register', and that variant_set uses make_variant_set. Gaps remain: start/end units are ambiguous and as_insert is 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?

States a specific verb+resource ('A frame-exact strobe over start-end') and defines the effect precisely (images held hold frames, cycled by pattern). It does not explicitly differentiate itself from the many add_* effect siblings (add_finish, add_stylize, add_corrupt_screen), so sibling disambiguation is left to inference.

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

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

Usage is implied by the effect semantics and one constraint is given ('More than 3 changes a second needs the user's ask'), but there is no explicit when-to-use vs alternatives guidance or which sibling to prefer. An agent can infer the context but is not routed.

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

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

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

Annotations only give readOnly=false/destructive=false/idempotent=false, so the description earns credit for disclosing project scoping, that the project identity is returned, and the non-obvious fallback that without a measured matte the preview shows a stand-in. It does not address repeat-call behavior or permissions, so it is strong but not exhaustive.

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

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

Front-loads the project-scoping constraint and the matte boundary before the dense kind list; every clause carries information. It is one long run-on paragraph of terse shorthand, which costs some scanability for an agent, but there is little 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 15-param, nested-object, no-output-schema mutation tool, the description covers scoping, effect taxonomy, timing/trigger model, and matte prerequisites. Remaining gaps are secondary params (region, intensity, echo/style subfields) and whether it stacks with or replaces an existing subject effect.

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 40% schema coverage across 15 params, the description compensates heavily: it defines each kind's visual semantics (fill decays in 1-2 frames, poster colour=field, isolate keeps colour on scope with mono elsewhere, echo clones k frames back), the three timing forms, the on= trigger taxonomy split into speech clock vs added track, and count/per='shot'. This is meaning the schema enum labels alone cannot convey.

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 (adds an effect bounded by the person cut-out / subject matte) and enumerates the eight effect kinds it can produce, so an agent knows exactly what family of operation this is. It differentiates from siblings by scoping ('bounded by the person cut-out') and by explicit exclusions ('No sound, no zoom'), pointing away from add_sfx/add_zoom.

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?

"Earns its place on payoffs, structural beats and section changes, never decoration" gives an explicit when-to-use and when-not-to-use rule, and 'No sound, no zoom' rules out adjacent tools. It stops short of naming an alternative tool (e.g. add_region_effect) for non-matte effects, so it is clear context rather than full routing.

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

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

Annotations already declare this is a non-read-only, non-idempotent, non-destructive, non-open-world write. The description still adds real behavioral context beyond them: project scoping, the caption-suppression ownership rule and its automatic restoration on removal, and the instant 'none' entrance/exit semantics. It stops short of describing rendering cost, auth/permission needs, or failure modes, so it is useful but not exhaustive.

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

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

It is dense and long, but for a 22-parameter tool the length is largely earned, and it front-loads the project-scoping constraint and core purpose. A few clauses (e.g. the full template glossary) are verbose, keeping it just under top marks.

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 22 parameters, no output schema, and very low schema coverage, the description covers nearly everything an agent needs: scoping, template choices, geometry, styling, animation, and the motion-vs-preset tradeoff. It notes the call returns the project identity with its result, but is thin on error/verification behavior, which is the remaining gap.

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

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

Schema description coverage is only 14% across 22 parameters, so the description must carry the load — and it does, documenting x/y as frame fractions, size_scale range, color/accent_color hex format, font_size and max_width ranges, bundled font families, outline/shadow overrides, entrance/exit presets, uppercase and box behavior, and the motion curve primitive. Some params (motion_motif, project_id) are only covered by their schema descriptions, leaving a small 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 — burning a motion-graphics TEXT template over a program-time window — and explicitly carves itself out from captions (spoken words) and overlays (media). The template enumeration and the 'use for text the user dictates' framing let an agent distinguish it from siblings like add_captions, add_title_card, and add_typeset without opening their 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?

Gives explicit routing: dictated titles/labels/stats go here while spoken-word captions stay with add_captions, and it warns to omit entrance/exit when motion is present. It also spells out the mute_captions decision (false for an independent headline so dialogue captions remain visible), which is precisely the kind of when/when-not guidance that prevents 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?

With only generic write annotations (readOnlyHint=false, destructiveHint=false), the description carries the burden and delivers: project scoping, the temporal matting behavior, refusal conditions, occlusion semantics for people vs static objects, defaults (size_scale 2.4), the zoom/stabilize prohibition, and cleanup path. This is far 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?

Long but front-loaded with the project scope and the core composite concept, and most sentences carry distinct rules (refusals, occlusion, defaults). It leans narrative in the middle, which costs a little density, but little is pure padding.

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 creative tool with no output schema and near-zero schema descriptions, the definition covers requirements, failure modes, defaults, alternatives, and removal. An agent has everything needed to call it correctly or decline.

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 7% across 15 params, so the description must compensate, and it does for most: it maps styling args (template/x/y/size_scale/color/font/entrance/exit), defines at_output_s/duration_s as positions in the EDITED video, and states the size_scale default. It leaves box, uppercase, and accent_color unexplained.

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

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

Names the exact operation ('put words BEHIND the moving subject') and contrasts it with the plain title behavior of add_text when no person is present. It is unambiguously distinguishable from siblings like add_text and add_kinetic_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?

Gives explicit when-to-use (a person must be visible in the window), when-it-refuses ('a PERSON must be visible... I say so and you offer add_text instead'), and prerequisites (follow crops/cuts/speed ramps are fine). It also routes to the sibling add_text and to remove_text for cleanup.

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

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

Annotations only declare the generic mutation profile (readOnly=false, destructive=false, idempotent=false), and the description adds substantial context beyond that: project scoping, that the result echoes project identity, that most kinds never move sound/length while ramp re-anchors every later item, and that reverse/remap/stutter/ramp refuse spoken words without allow_speech. Error behavior and reversibility are not covered, keeping it from a 5.

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

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

It is a single dense paragraph, but it is front-loaded with the most important constraint (PROJECT-SCOPED) and every clause carries concrete information rather than filler. Readability suffers slightly from the run-on structure.

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

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

For a 12-parameter tool with a nested echo object, two enums, and no output schema, the description covers the critical operational facts: scoping, kind semantics, sound-handling differences, and speech-refusal rules. It omits the timing parameters and exact return shape, but it is largely sufficient to call the tool correctly.

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

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

Schema coverage is only 33%, so the description must compensate. It usefully documents kind semantics, factor range (0.25-0.9), posterize frames 2-8, stutter frames x repeats, remap curve values, and allow_speech, but leaves start, end, id, and word entirely unexplained. Partial compensation lands at the baseline.

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

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

The description names a concrete verb+resource (add time effect) and enumerates the seven kinds (reverse, echo, posterize, stutter, interpolate, remap, ramp) with a gloss of each, so the agent understands the tool's domain well. It does not explicitly differentiate itself from siblings like set_speed_ramp or add_freeze_frame, which limits it to a 4.

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

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

It implies when each kind applies (e.g., 'ramp is a real speed change' vs 'picture-only devices') and states the allow_speech condition, but it never says when to pick this tool over alternatives such as set_speed or set_speed_ramp. Usage is inferable rather than stated.

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

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

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 give the safety profile (non-destructive mutation, non-idempotent), and the description adds traits beyond that: project-only scoping with an echoed project identity, a side effect ('replaces the captions for its words'), a stateful 'never the same voice twice running' constraint, and depth layering. It does not cover return payload detail or failure behavior, but it meaningfully exceeds the annotations.

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

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

Front-loads the critical PROJECT-SCOPED constraint, then gives purpose, behavior, and usage in tight order. Some phrasing is adjective-heavy ('solved for this frame', 'in the free space around the face'), but each sentence carries actionable content rather than filler.

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

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

No output schema, 19 params at 42% coverage, and a mutation tool — the description covers scope, side effects, and usage well but does not explain the majority of parameters or the render/return behavior. Adequate for calling it at a basic level, incomplete for full configuration.

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 42% with 19 params, so the description should compensate. It adds real meaning for depth ('depth=behind sets it behind the subject'), voice (chosen per story beat), layout ('free space around the face'), and text timing ('each word landing on its spoken onset'), but leaves most of the 19 params (exit, verb, material, region, orbit, flip_at, etc.) undocumented, so the coverage gap is only partly closed.

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 ('poster-scale type for one spoken phrase') and scopes it to a spoken phrase that replaces captions. It differentiates somewhat from dense-text siblings by contrasting with 'dense explanations', but never names a concrete alternative (e.g. add_text), leaving the agent to infer the boundary.

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

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

Gives both a positive condition ('Use it for a hook, a turn or a payoff') and an explicit exclusion ('not for dense explanations'), which is real routing guidance. It stops short of naming the sibling to use instead, so the agent must find the alternative itself.

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

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

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=false), so the lower bar applies. The description adds real non-annotation context: it is PROJECT-SCOPED, acts only on the explicit project_id, and 'returns the project identity with its result.' It still doesn't say whether repeated calls are cumulative or what happens to an existing item, so it's not a 5.

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

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

The scoping constraint is front-loaded and every sentence conveys a distinct behavior (scope, template, fill semantics, reveal modes, intended use). The prose is dense and jargon-laden but does not pad or repeat itself.

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

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

For a 12-parameter mutation with no output schema and low schema coverage, the description covers the creation intent, project scoping, return-identity note, and the primary visual enums. Missing details are the coordinate/timing parameters and behavior on repeated or conflicting calls, so it is strong but not fully complete.

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

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

Schema description coverage is only 17% (just project_id and fill_source), so the description must carry the load, and it does explain the meaningful enums with effect semantics: reveal values (hold, words one word per hard cut, open a letter grows to full frame eased, words_open), fill_mode outside making letters windows onto the picture, and field='black' setting footage-in-letters on black. It leaves y, end, start, font, id, and open_at entirely unexplained, so it is not complete.

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 resource effect ('Giant condensed letters that are windows', tied to template type_window + its composite, one item) rather than restating the tool name, so an agent understands this is a typography-as-window element distinct from plain text additions. It does not explicitly compare itself to close siblings like add_text, add_kinetic_text, or add_title_card, which keeps it short of a 5.

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

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

'Use for a title or a scene change, never as decoration' gives both a positive use context and an explicit exclusion. It stops short of naming an alternative tool to pick when the goal is, say, plain text or a kinetic rather than window treatment.

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

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

Annotations already declare this as a non-read-only, non-idempotent write with no open-world access. Beyond that, the description adds real behavioral context: it is project-scoped to an explicit project_id and echoes back project identity, and it discloses morphing semantics (same id across scenes = one morphing object, from=<id> iris transitions) and data-provenance rules. 'WRITE:' merely restates readOnlyHint=false.

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 scope and write nature are correctly front-loaded, but the bulk is a dense wall of bracketed DSL tokens (scenes=[{...}], objects:[{...}], media={...}) that is hard to parse and mixes syntax, behavior, and constraints. Every clause is informative, yet the packing costs 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 10-param nested write tool with no output schema, the description covers the core scenes/media structures and the required project scoping. It is silent on time framing (start/end), theming (theme/accent, id), and any failure/validation behavior, leaving meaningful gaps for an agent composing a call.

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 30% across 10 params, so the description must compensate, and it does explain the scenes DSL, layout values, object kinds, bind/state, media slot format, and the backdrop enum. However, it leaves several top-level params (start, end, theme, accent, id) and many nested object fields (title, body, value, delta, rows, etc.) to the schema, so the compensation is partial.

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

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

The description states a specific purpose — building an 'explainer told through interface' — and the object kinds (card, pill, comment, metric, bars, window, media, text) make concrete what a UI scene contains. It does not name the sibling it contrasts with (e.g. add_title_card, add_typeset, set_typography_scene), so sibling differentiation is left to the reader.

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

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

There is a hard constraint ('numbers come only from data... never invented') and a scope note, but no statement of when to choose this tool over the many adjacent add_* / set_* typographic tools. An agent must infer the 'explainer-through-interface' niche on its own.

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

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

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false) but not scoping or side effects. The description adds that the call is PROJECT-SCOPED, acts only on the explicit project_id, and returns the project identity with its result — genuinely useful behavior beyond the annotations. It does not mention auth requirements, undo semantics, or what happens on invalid geometry, so it is strong but not exhaustive.

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 scoping constraint is front-loaded and each subsequent sentence adds parameter or usage information rather than filler. It is dense and long, but the length is justified by the 17-parameter surface; a slightly tighter phrasing of the kind semantics could shave words without losing meaning.

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

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

For a mutation tool with 17 parameters, nested motion objects, low schema coverage, and no output schema, the description covers geometry units, color formats, rounding bounds, progress range, motion keyframe model, and project scoping. Missing pieces such as start/end timing semantics and how motion_motif interacts with the Blueprint motif system keep it from being fully complete.

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

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

Schema description coverage is only 18% (17 params, effectively two documented), so the description must carry the load — and it largely does: it defines x/y as frame-fraction centres, width/height as frame fractions, color/stroke_color/background_color as #RRGGBB, stroke_width as a fraction of the short frame edge, rounding as 0-0.5, progress value as 0-1, and motion as LOCAL x/y/scale/rotation/opacity keyframes. It still leaves start/end window semantics and opacity/motion_motif partially implicit, so it compensates well but not completely.

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

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

States a specific verb and resource ('Add a renderer-native VECTOR graphic over a PROGRAM-time window') and enumerates the six supported kinds with their intended semantic roles (panel/highlight, underline/connector, etc.). This is enough to distinguish it from siblings like add_motion_graphic, add_ui_scene, and add_custom_filter without opening their 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?

Gives real when-to-use guidance per kind ('use a panel to support hierarchy, a line to connect, and arrows/rings only when the frame contains the thing they identify') plus the workflow caveat 'Preview the whole path before accepting it.' It stops short of naming sibling alternatives (set_vector_graphic, remove_vector_graphic, add_motion_graphic) to route between them, so it is clear context rather than full when/when-not/alternatives 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 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?

Annotations only declare non-readonly/non-destructive/non-idempotent. The description adds substantial context beyond that: the hard 3x total-enlargement cap, conflict resolution ('if both arrive the rect wins and the call still succeeds'), the frame-center fallback with a quality advisory, and what the result reports. It also confirms behavior on edge cases without contradicting the annotations.

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

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

Front-loaded correctly with scope then core behaviour, and most sentences carry real information, but the block is far larger than a typical tool description and reads partly as an editorial style guide (metronome punches, childish edits, overshoot for a 'slam'). It is dense and hard to scan; a leaner version would serve tool selection better.

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 17-parameter mutation tool with no output schema, it is very complete on invocation: aiming modalities, mode semantics, caps and failure/fallback behaviour are all covered. It only gestures at the response ('the result says when', 'its result reports where the region lands') without describing the return shape, leaving a small gap.

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

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

With only 18% schema coverage across 17 params, the description compensates heavily: it defines every mode value (punch, landing, push_in, pull_out, ease, pulse, shake) with duration and strength guidance, gives strength ranges/defaults, ramp_s semantics, overshoot/rotate/shake ranges, and the mutually exclusive rect vs cx/cy aiming model and their distinct behaviours. Only purpose, motion_motif and target_evidence_ids are left to the schema, and two of those carry schema descriptions.

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

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

States a specific verb and resource ('Camera move ... on a time range of the FINAL edited video, in output seconds') and immediately scopes it ('PROJECT-SCOPED: this call acts only on the explicit project_id'). It also distinguishes itself from siblings add_zoom_path, punch_in_on_emphasis, remove_zoom and remove_zoom_path with explicit routing rules.

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 and when-NOT-to-use guidance ('OPTIONAL, never a rule ... never one on every cut, sentence or hold'), details the editorial conditions that earn a zoom, and names the alternatives ('that is ONE add_zoom_path, never a chain of static zooms'; 'punch_in_on_emphasis places punches on the measured vocal stress peaks in one call').

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

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

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 already cover the safety profile (readOnly, non-destructive, closed-world). The description adds real behavioral context beyond them: the call is strictly project-scoped to the explicit project_id, it returns the project identity alongside the result, and it presupposes separate_music has run. It does not explain why idempotentHint is false, which is the one noteworthy trait left undisclosed.

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, both front-loaded with the highest-value information (scope first, then what is read and its prerequisite). The uppercase labels are terse and functional rather than wasteful, though slightly telegraphic.

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 convey returns, and it does say the result comes back with the project identity. However, it never states what the aligned output actually contains or whether alignment is persisted to the project, and it leaves the required lyrics parameter's expected shape unexplained.

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

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

Schema description coverage is only 33%: project_id is well documented in the schema, but the required 'lyrics' parameter and optional 'music_id' have no type, format, or usage detail in either place. The description says only 'the user's lyrics text', which leaves the critical question of expected lyric format (plain lines, timestamps, syllable breaks) unanswered.

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 (align) and resource (the user's lyrics text) and states the alignment target (the singer's timing on their track). The parenthetical 'after separate_music' links it to a specific sibling and workflow stage, though it doesn't contrast with near-neighbours like get_syllables, get_words, or beat_align_cuts.

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

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

Usage is only implied through the 'READ' label and the 'after separate_music' ordering prerequisite, which is genuinely useful sequencing information. There is no explicit statement of when to prefer this over alternatives such as get_syllables or get_words, nor any when-not 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 cover the safety profile (readOnlyHint, destructiveHint=false, openWorldHint=false), so the bar is lower. The description nonetheless adds real behavior: the project scoping constraint, that the result carries the project identity, and an explicit refusal path when no track was supplied — none of which the annotations convey. It does not explain pagination or result granularity, keeping it out of 5 territory.

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

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

Front-loads the two operative labels (PROJECT-SCOPED, READ) so the agent can triage scope and operation type immediately. Dense but each clause carries information; the em-dash enumeration is long yet specific. No filler 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 read-only analysis tool with no output schema, the description takes on the return-value burden and does so by enumerating the structural elements returned with program positions. Safety is covered by annotations and the refusal rule is stated. The remaining hole is music_id semantics, which is left entirely unexplained.

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

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

With 50% schema coverage, the description needs to compensate. It reinforces the project_id scope ('acts only on the explicit project_id'), which the schema already documents, but the second parameter music_id is undocumented in both the schema and the description — an agent gets no guidance on when or how to supply it. Partial compensation only.

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

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

States a specific verb and resource — 'READ: the structure of the user's track' — and enumerates the returned elements (tempo, beats, bars, sections, drops, gaps, drum hits, 808s, filter openings). This is far more than a tautology. It does not, however, explicitly differentiate itself from sibling get_audio_analysis, which an agent would plausibly confuse it with.

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

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

'Refuses when the user supplied no track (never choose music; the speech prosody grid is the clock then)' gives a concrete when-not condition and names the fallback clock instead of leaving the agent to guess. It stops short of pointing at the actual sibling tool (e.g. get_audio_analysis) to call when a track does exist, so it is clear context with an exclusion rather than full alternative routing.

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

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

Annotations already carry the read-only safety profile, so the description earns credit by adding the project-scope constraint and explicit scope exclusions ('never its text, logos or footage'), which tell the agent what the analysis will and won't capture. It does not explain the non-idempotent hint, leaving one annotation trait unexplained.

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

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

Front-loaded with the two most decision-relevant markers (PROJECT-SCOPED, READ) followed by the scope exclusions. The parenthetical device-class list is dense but each item conveys a concrete visual pattern, so it largely earns its place.

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

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

There is no output schema, so the description must carry the return burden, yet 'returns the project identity with its result' is vague about what the result contains. For an analysis tool feeding downstream edits, the description should say more about the returned mapping.

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 50% (asset_key is undocumented), and the description only implicitly identifies asset_key as the uploaded reel. project_id is already well documented in the schema. It adds marginal, informal meaning rather than compensating for the coverage gap.

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

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

States a specific verb (READ) and resource (an uploaded reference reel) and specifies what it extracts: device classes mapped onto the edit's moments. It distinguishes itself from the nearest sibling analyze_music by being about visual devices, though the 'device classes' vocabulary is idiosyncratic.

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 trigger phrase 'make it like this' gives an implicit usage context, and PROJECT-SCOPED frames the scope. However, it never explicitly says when to prefer this over look_at_asset, analyze_music, or compare_uploaded_media, so routing 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 declare readOnlyHint=false and the description consistently states WRITE, so no contradiction. Beyond annotations it adds genuinely useful behavioral context: the call is project-scoped, acts only on the explicit project_id, and returns the project identity with its result. It stops short of disclosing reversibility or what happens to pre-existing motion on re-aim.

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

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

Front-loads the two constraints that matter (PROJECT-SCOPED, WRITE) before the effect narrative, and packs the media/effect detail into a single dense sentence. Slightly run-on, but every clause carries 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 9-param write tool with no output schema and sparse schema descriptions, the definition covers scope, operation type, and return identity but leaves most tuning parameters (fit, ease, amount, focus coordinates, treatment) unexplained. Adequate to understand intent, insufficient to invoke confidently with non-default parameters.

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 11% across 9 params, so the description must carry the load. It does map several path behaviors (push/pull toward a detected face, pan a panorama, rise a tall scan, drift), which gives semantic meaning to the path enum, but fit, ease, amount, focus_x, focus_y, and treatment remain entirely undocumented in both schema and 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?

States a specific verb+resource: a still photo (cover image overlay, image insert, moving still) gets motion via push/pull, pan, rise, or drift. It is concrete enough to separate from generic siblings like set_overlay_motion or add_zoom by naming the input media type and effects, but it never names an alternative tool, so the differentiation is implicit rather than explicit.

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 describes what gets animated (a photo sitting dead still, a cover overlay, an image insert) but gives no when-to-use vs alternative guidance, no prerequisites, and no exclusions. A sibling set containing set_overlay_motion, add_zoom, add_zoom_path, and add_kinetic_text demands explicit routing that is absent here.

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 covering the safety profile, the description adds substantial behavior beyond them: atomic all-or-nothing semantics, no render wait, that unknown fields or invalid media reject the entire batch, that operation_id is a retry id to be reused on transport failure, that times describe the RESULTING timeline, and that motion graphics placed here are silent and cannot sit behind the subject. It even sets expectations honestly ('saves an edit; it does not certify picture/audio quality') and points to read_skill('devices') for layer fx shapes.

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

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

It is front-loaded with the scope constraint and the core action, and every sentence carries information relevant to calling the tool correctly. It is dense and long, with several heavily parenthesized clauses, but for a tool with four interlocking required parameters and 18 layers the length is largely earned rather than padded.

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

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

For a complex atomic-mutation tool with no output schema and thin schema descriptions, the definition covers scope, prerequisite read, retry semantics, failure mode, action semantics, layer set, timeline-coordinate convention, and the fact that project identity is returned. It deliberately defers exact value shapes to get_edl and read_skill, which is the right place for that detail, leaving no operationally necessary gap.

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

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

With schema description coverage at only 25%, the description carries the burden and does so well: it specifies operation_id's character class and 16-80 length, that base_version must be current, the {action,layer,value?,id?} operation shape, the meaning of each action (set replaces one complete layer; upsert patches or adds by id; remove deletes by id; reorder takes all insert ids), and enumerates the layers with anchor semantics (motion by id, fx by id). This goes well beyond what the schema itself documents.

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 ('Apply a complete group of ordinary edits atomically, with no render wait') and scopes it explicitly to the project (PROJECT-SCOPED, acts only on project_id). It is clear what the tool does, but it never names its closest sibling 'apply_short_edit_batches', leaving the agent to infer the boundary between the two batch 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 real prerequisites ('Read get_edl first; base_version must be current') and routes one specific case to an alternative ('graphics placed this way are silent and cannot sit behind the subject - use add_motion_graphic for those'). However, it offers no guidance on when to choose this over the per-layer siblings (set_text, add_music, etc.) or over apply_short_edit_batches, so the primary selection decision is left implicit.

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

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

Annotations only declare write/non-idempotent/non-destructive; the description adds real behavioral context beyond them: it is project-scoped to the explicit project_id (no active-project guessing), it mutates the frame unless aspect=true, it returns the project identity, and it explicitly does NOT pick music, zoom, or sound. Those exclusions materially shape expectations for a batch WRITE.

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

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

Front-loads the two most important tags (PROJECT-SCOPED, WRITE), which is good, but the middle is a run-on enumeration of A–J and nested clauses that is genuinely hard to parse in one read. It is information-dense rather than concise.

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 5 parameters, no output schema, and low coverage, the description should carry more burden. It conveys scoping and write behavior and hints at the return (project identity plus result), but without an output schema it never describes the returned frame/brief/proposals structure, and it leaves intensity and two pack enum values unexplained.

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

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

Schema coverage is only 20% (project_id documented), so the description must compensate. It explains picks and aspect behavior and the pack letters, but omits the intensity enum values (calm/designed/charged) and the meaning of pack='auto' and pack='none', leaving half the parameters under-specified.

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 (apply) and resource (a genre/format pack) and enumerates the pack options A–J with their intent, and routes the agent to suggest_story for picks. The dense jargon ('edit about the edit', 'craft brief') makes it harder to gist than it needs to be, but an agent can distinguish it from siblings like suggest_story or set_frame.

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

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

It implies a workflow: use picks=[numbers] from suggest_story, and E–J without picks return items for you to pick. But it never states when to choose this tool over apply_look, apply_recipe, suggest_story, or apply_edit_batch, leaving the selection decision largely inferred.

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 only declaring the non-read-only/non-destructive profile, the description carries the real behavioral burden and delivers: it REPLACES the earlier look's custom grade and whole-video texture, places no sound unless transition_sounds=true, ducks music to -18 to -22 dB, never puts a fade from black on a vertical short, and preserves existing emphasis_words. These are exactly the side-effect details an agent needs before invoking.

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

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

It is front-loaded with the PROJECT-SCOPED constraint and the core purpose before the long look catalog, and each block does real work. It is nonetheless a very dense, run-on block of prose whose length is only partly justified, so it is efficient without being tight.

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 composite, mutating 4-param tool with no output schema, the description covers the return shape ('returns the project identity with its result', hero-moment templates), the mutation scope, sound behavior, and music rules. Nothing an agent needs to invoke it correctly appears to be missing.

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

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

The single enum param has ten values and the description characterizes each one concretely ('editorial': ivory sans captions turning gold serif italic, matte filmic grade; 'meme': impact xl captions, flash cuts, grain), which is far beyond the bare enum strings. It also adds music semantics (exact library slug, ducked CC0 bed levels, never 'auto') and transition_sounds semantics (opt-in, false removes earlier ones) on top of the ~75% 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 gives a crisp verb+resource: 'One call sets a whole premium look: captions, grade, texture, transitions and optional music.' That clearly distinguishes it from the many single-component siblings (add_captions, set_color_grade, set_transitions). It stops short of naming the nearest analogs (apply_recipe, apply_format_pack), so there is no explicit sibling routing.

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