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

Annotations only declare the mutation/safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false); the description goes well beyond that, explaining that text/arrows are anchored to the output frame while a blur anchors to the recording's picture and stays put under zooms or padding. It also discloses the return convention ('the result reads the annotation back as getCurrentDocument reports it') and the projectId/editor-open caveat. It stops short of saying whether annotations can be removed or what permissions are needed.

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

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

Front-loads the action and the type taxonomy before diving into geometry and per-type data. Sentences are long and run together in places, but for a 16-parameter tool with nested objects the density is largely earned.

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 mutation tool with nested objects and no output schema, the description covers type selection, coordinate frames, sizing defaults, styling fields, the projectId fallback, and the return shape. Nothing critical to calling it correctly is missing.

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

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

Schema coverage is 63%, so the description has to carry real weight, and it does: it explains the dual coordinate systems for x/y, gives width/height defaults (30 × 20) and their reference box per type, describes figureData/blurData contents, and notes fontSize defaults. Some of this repeats the schema's own field descriptions, but the placement semantics are added value the schema does not supply.

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

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

States a specific verb (add) and resource (annotation) scoped to 'a span of the edited timeline (virtual seconds)', and enumerates the three annotation types with what each is for. It does not differentiate from the sibling setAnnotation, so an agent cannot tell from the text alone when to add versus update.

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 per-type usage context (blur for hiding an email, token or password field) and one exclusion ('image annotations are not available here: they need a file, added in the editor'). It never names setAnnotation or states a when-not condition relative to any sibling, so routing is only implied.

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

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

Annotations declare readOnlyHint=false, destructiveHint=false, openWorldHint=false, so the safety profile is already known; the description adds that placing on the voiceover lane drives transcription ('the lane is not only cosmetic') and the fade-sharing rule for short tracks. It doesn't discuss permissions or whether the operation is reversible/undoable, but goes 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 core action ('Lay an ALREADY-IMPORTED audio file...'), then sequences prerequisites, then parameter semantics. Dense but nearly every sentence earns its place; the all-caps and em-dash style is a bit informal but readable.

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

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

A 9-param mutation tool with almost no schema descriptions and no output schema; the description compensates with prerequisite routing and per-parameter meaning. It leaves projectId semantics to the schema (which documents it) and doesn't state the return, but that is minor for this operation.

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

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

Schema description coverage is only 11%, so the description must carry parameter meaning – and it does: assetId must be an audio-kind asset, endSec omission plays the whole file, offsetSec is the in-file playback start, gainDb 0/negative meaning, kind picks the lane, fadeInMs/fadeOutMs ranges and default and the short-track sharing behavior. Six of nine parameters get explicit semantics beyond the schema.

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

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

States a specific verb and resource ('Lay an ALREADY-IMPORTED audio file over the recording across a span of the edited timeline'), with the use cases (voiceover, music bed) named. Distinguishes itself from sibling setAudio by requiring an already-imported asset and placing it on a span of the timeline.

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 to use getCurrentDocument to find audio assets, to use importMedia first if none exists, and 'never guess an id'. These are concrete when-to-use and prerequisite instructions that route the agent to the right 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?

Goes well beyond the annotations (readOnlyHint=false, destructiveHint=false) by disclosing the grouping algorithm, exclusions, idempotency ('no zoom lands on one already there'), the result list, telemetry statuses (ok, no-sidecar, unavailable), and the caveat that 'added 0 is an answer, not a failure.'

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

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

The description is dense but front-loaded and well-structured: it moves from purpose to algorithm to usage to results/telemetry to an edge-case caveat. Every sentence adds useful context, though it could be slightly tighter.

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

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

For a mutation tool with no output schema, it describes the return values and telemetry readings, covers edge cases like 'added 0', and gives clear usage context. The only gap is the misleading 'Takes no arguments' claim, which the schema corrects.

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

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

The schema fully documents the optional projectId (100% coverage), but the description falsely says 'Takes no arguments.' This contradicts the schema and could mislead an agent about whether a projectId can be supplied.

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 ('Plan zooms... and add them') and explains the automatic mechanism ('clicks close in time and on screen share one zoom'). The reference to 'Automatic zooms' and the behavioral details distinguish it from manual zoom siblings like addZoom/addZooms.

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 usage contexts: 'Use it after cutting or rearranging a project, or on one whose zooms were removed.' It does not name alternative tools (e.g., addZoom) or state when not to use it, but the automatic-vs-manual distinction is 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 give the generic safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false); the description adds real behavioral detail the annotations cannot: a precondition on asset camera tracks and a refusal-rather-than-partial-write failure mode. That is exactly the extra context the annotations leave uncovered.

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

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

Three sentences, front-loaded with the action and span, followed by the precondition and the failure behavior. No filler or restatement of the name.

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

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

For a three-parameter mutation with no output schema, the description covers the action, the span semantics, the required precondition lookup, and the refusal behavior. An agent has everything needed to call it correctly or explain why it cannot.

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 weight; it does by clarifying that startSec/endSec are virtual seconds bounding the region and that the span must map to non-empty camera footage, which is a semantic constraint absent from the bare numeric minimum:0 schema. projectId semantics live in the schema, so nothing further is needed there.

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

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

States a specific verb (add) plus resource (camera-fullscreen region) and scopes it to a span of the edited timeline in virtual seconds, with the rendered effect made explicit ('webcam fills the frame'). An agent can distinguish it from generic effect tools, though it never names its closest sibling setCameraFullscreen, so no explicit sibling differentiation.

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

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

Explicitly directs the agent to check assets[].hasCameraTrack (or hasAnyCamera) via getCurrentDocument first, and states the when-not case: it does nothing on footage lacking a camera track. It even prescribes the response to refusal ('say so instead of retrying'), which is unusually complete 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?

Far beyond the annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=false), it discloses the purity rule that guarantees preview/export parity, the hard 4096-iteration-per-pixel loop limit, the exact cost-tier breakdown with device timings, and the failure mode ('Code that does not compile is refused with the compiler's error ... fix it and call again'). It also states that the length recommendation is 'never a refusal', which prevents an agent from misreading the guidance as a gate.

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 purpose is front-loaded correctly, and most of the shader-contract detail is genuinely load-bearing given no output schema and near-zero schema coverage. However it is delivered as one very long unbroken paragraph mixing tool usage with WGSL reference material, and items like the per-device millisecond cost tables could be compressed or deferred, so it is bulkier 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?

With no output schema, the description does explain the return ('the cost tier ... with what a 1080p frame pays') and the error path, which is exactly what is needed. It also documents the shader runtime API, target defaults and parameter-declaration constraints. It stops short of defining `values`, the exact meaning of startSec/endSec, and the purpose of effect.name/effect.description in the effect object.

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

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

Schema description coverage is only 14% across 7 parameters, so the description carries most of the burden and does well: it details `effect.code`, the `params` declaration schema (type/name/label/default/min/max), the `target` enum defaults and the 'text or both only when asked' rule, `effectId`, and the timeline span. Gaps remain — `values` (how declared parameter values are applied) is never explained, and startSec/endSec semantics are only implied by 'a span of the edited timeline (virtual seconds)'.

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

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

The opening sentence gives a precise verb+resource ('Write a visual effect as a shader and pose it over a span of the edited timeline') and even covers the second mode ('or pose one of this project's effects again (effectId)'). It is unambiguous what the tool creates, but it never names or contrasts the closely related siblings (setEffect, getEffect, setEffectDefinition), so an agent still has to infer the boundary from tool names alone.

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

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

It gives real selection guidance: 'Use it for a look the settings do not offer', 'use text or both only when asked', 'to combine two looks, write them in one shader', and 'Check the result with getFrames'. There is no explicit when-not or named-alternative routing (e.g. versus setEffect for existing effects), but the conditions for parameter declaration and target choice are concrete.

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-destructive, non-read-only mutation. The description adds range semantics (virtual seconds) and the speed multiplier direction, which is useful context beyond the annotations. It doesn't address what happens to overlapping regions or the return value, so with annotations carrying the safety profile, a 3 is appropriate.

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

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

Two tight sentences front-load the action and scope, then add the multiplier semantics and the use case. Every clause earns its place.

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

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

For a 4-param mutation with a 25%-covered schema and no output schema, the description supplies the critical speed semantics and the timeline scope. It could say more about region boundaries or the omitted projectId fallback, but it's largely complete for correct invocation.

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

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

Schema coverage is only 25% (only projectId is described), so the description must compensate. It successfully explains the speed parameter's semantics (direction, range, clamp values, default), which is exactly the missing meaning. startSec/endSec are half-explained via 'span of the edited timeline (virtual seconds)', but projectId is left to the schema 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 and resource ('Add a speed-change region over a span of the edited timeline') and defines scope in virtual seconds. Clearly distinguishable from siblings like setSpeed and addTrim.

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

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

Gives a concrete use case ('speed through slow stretches without cutting them'), which implies when to reach for this over setSpeed (region vs. whole clip). It doesn't explicitly name the alternative or state when not to use it, so it falls short of a 5.

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

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

Annotations only cover the safety profile (readOnlyHint=false, openWorldHint=false, destructiveHint=false). The description goes far beyond them: it discloses the multi-clip failure mode with its error listing, the zoom 'hold' chaining behavior, the getCurrentDocument source for ids, and the cutTransitions warning shape (which zoom, side, cutSec, time lost, cause). Nothing here contradicts destructiveHint=false — the span is excluded from playback/export but nothing is refused or removed.

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 purpose sentence is correctly front-loaded, but the body is a dense wall of text — the zoom-move duration formula and the numeric table (0.72 s at 1.25x, 0.82 s at 1.50x...) are far more detail than an agent needs to select or invoke this tool, even accepting that zoom interaction and cutTransitions are genuinely relevant. Relevant substance, poorly budgeted.

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 correctly carries the burden of explaining returns and does so for the cutTransitions warning, plus it covers the multi-clip failure mode and zoom interaction edge cases. Gaps remain around assetId/reason and the general shape of a successful return, but the invocation-critical context is present.

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

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

Schema coverage is only 17% (just projectId), so the description must compensate — and it does for the critical ones: startSec/endSec are 'seconds of the asset's source time' and clipId inference rules are fully explained with the failure case. However, assetId and reason are never addressed anywhere, leaving two of six parameters semantically 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?

The very first sentence states a specific verb and resource ('Add ONE trim range: a cut of a span inside a clip') and immediately clarifies the key defining behavior: it does NOT split the clip. It is trivially distinguishable from siblings like addTrims, setTrim, and removeTrim, and even from removeSilences-style intent by naming itself the preferred path. An agent knows exactly what this does without opening the schema.

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

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

Explicit routing rules: use addTrims when you have several cuts to make, and addTrim for a single cut or a later correction; it is also stated as the only way to handle 'remove silences' requests. The clipId ambiguity case is spelled out with the condition under which the call FAILS and what to pass instead. Usage conditions and the alternative are both named.

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 mutation/safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false), and the description adds a lot beyond that: partial-application semantics, 'Nothing is rolled back', per-index refusal reporting, the result shape (requested/appliedCount/refusedCount), the cutTransitions warning, and the zoom-hold/chaining side effects that can break a cut. That is real consequence disclosure an agent cannot get from structured fields.

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

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

Well front-loaded — batch purpose first, failure semantics second — but the back half drifts into extensive zoom timing lore (a full table of durations by scale) that arguably belongs in addZoom's documentation. The warning is relevant, yet the density of detail outweighs what an addTrims caller needs.

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 carries the return contract itself (requested/appliedCount/refusedCount, refused entries with index and reason) and the partial-failure model, so an agent can both call and interpret the result correctly.

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

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

Schema coverage is 50% and the schema barely documents the array item shape; the description compensates by explaining that `ranges` is a list whose entries take exactly addTrim's fields, and that refusals are reported with the entry's index. projectId is covered by the schema itself, so nothing important is left unclear.

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

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

States a specific verb (add) and resource (many trim ranges) with the key differentiator up front: batch versus the singular addTrim. An agent immediately knows this is the bulk variant and that each entry mirrors addTrim's fields.

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 an explicit switching rule — 'Use this whenever you have more than one cut to make' — plus the cost rationale (one round trip per single call). It also names the sibling implication (addTrim for singles) and adds negative guidance: 'leave the windows untrimmed' to avoid export jumps.

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?

Far exceeds the annotation baseline (readOnlyHint=false, destructiveHint=false). It discloses refusal behavior for customScale ('refused with the limit'), mutation semantics for chaining and hold windows, that cursorAnchor never refuses a call, and the exact timing math (0.6s + 0.55s × ln(renderedScale)) that governs animation. This is unusually rich operational disclosure.

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

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

Front-loaded correctly (purpose first, then depth, focus, telemetry, effects), and most sentences carry real information. But the description is enormously long for one tool, with extended asides (cursorAnchor sampling, cutTransitions) that push token cost high; trimming would make it easier to act on.

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, and the description fills that gap by naming return fields (renderedScale, cursorAnchor with its sub-fields, panUntilSec, cutTransitions). For a tool with chained zooms, speed-region interactions, and conditional results, the description is materially complete.

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

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

Schema coverage is only 22%, so the description must carry parameter meaning, and it does: depth is explained as an ordinal 1–6 with the full magnification table, focus as 0–1 frame fractions, focusMode manual-vs-auto behavior, customScale's range/rounding/refusal rule, and each rotationPreset value. It compensates well beyond what the bare schema shows.

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?

Opens with a specific verb+resource+scope: 'Add a zoom-in over a span of the edited timeline (virtual seconds).' That tells an agent exactly what is created and where. It does not, however, distinguish this single-span creation from the sibling tools that also create zooms (addZooms, addAutoZooms) or modify them (setZoom), so an agent must infer the split from other context.

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

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

It offers trigger phrasing ('Use for "zoom in on …" and the smart-zoom pass') and a style caution ('keep it for a reveal or a key moment, not every zoom'). But it names no alternatives and no exclusion condition, even though addZooms, addAutoZooms and setZoom are obvious siblings that an agent could confuse it with.

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 only the generic safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false); the description adds substantial non-obvious behavior: each region is independent and can be refused individually with index and reason, the result leads with requested/appliedCount/refusedCount, applied entries carry renderedScale rather than depth, plus cursorAnchor and cutTransitions. It also discloses timing/hold semantics and chaining rules that materially affect correct invocation.

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

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

Front-loaded with the core batch/independent-failure point, then progressively details timing and chaining. Every sentence carries operational information, but the single dense block on move duration formulas and chaining is heavy and would scan better segmented; no sentence is pure filler, though the duration table is arguably more detail than a selection decision needs.

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 rightfully covers the return shape (requested/appliedCount/refusedCount, renderedScale, cursorAnchor, cutTransitions), the failure mode, and the timing/trim constraints an agent must respect. Given the tool's complexity, nothing needed to call 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?

Schema description coverage is 50%, and the description compensates well for the undocumented parts by spelling out the depth→scale table (1=1.25× … 6=5.00×) and the temporal semantics of startSec/endSec (hold windows, move duration formula in screen time, trim interaction, chaining distance). It does not mention projectId, which the schema does document, so the gap is minor rather than disqualifying.

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

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

States a precise verb+resource+scope: 'Add MANY zooms in one call', and explicitly contrasts with the sibling addZoom by noting each entry takes exactly the fields addZoom takes. An agent can immediately distinguish this batch tool from addZoom/addAutoZooms/setZoom 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 use case ('the smart-zoom pass, where you have decided every zoom before emitting the first one') and the cost trade-off that selects it over per-zoom calls ('sending them one at a time costs one round trip each'). Also states the per-item failure model, which is a usage-relevant guarantee.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false; the description reinforces this with 'Changes nothing' and adds the return value (checkpointId) plus the intended pairing with restoreCheckpoint. It does not cover limits (how many checkpoints can exist, lifetime, whether it persists across sessions), so it stops short of a 5 but is consistent and informative.

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

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

Three short sentences with zero filler, front-loaded with the action and return value, then the non-mutation guarantee, then the workflow reason.

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, and the description compensates by naming the return value (checkpointId). Combined with the schema documenting projectId and annotations covering safety, an agent has what it needs, though checkpoint retention/scope limits remain 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?

Schema description coverage is 100% and the single projectId parameter is already fully documented there, so the description adds nothing about parameter syntax or optionality. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

Specific verb+resource (save project state, return checkpointId) and explicitly names the paired sibling restoreCheckpoint, so an agent can distinguish it from the many mutation tools in the sibling list 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?

States exactly when to call it ('before a series of edits') and why ('so restoreCheckpoint can revert all of them in one step'), which names the alternative tool and the condition that chains them.

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

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

Annotations only cover the safety profile (readOnly=false, destructive=false, openWorld=false), so the description carries real weight here and delivers: it explains style-preset inheritance, the auto-zoom planning side effect from the pointer track, and the two return values (projectId and a checkpointId that restores the project). This goes well beyond what the annotations provide.

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

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

The purpose is front-loaded, but the first sentence is a run-on with deeply nested parentheticals ('in the look new projects start with in OpenScreen (the style preset marked for them, else the last edited project's), as the editor's New does') that is difficult to parse. Content largely earns its place, but the structure and phrasing are needlessly unwieldy.

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 correctly compensates by naming the return values (projectId, checkpointId) and their meaning. It also covers the follow-up action and downstream visibility in the project list. The only gap is the phantom autoZooms parameter, which is neither in the schema nor reconciled with it.

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

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

Schema coverage is 100%, so both title and videoPath are already documented, giving a baseline of 3. The description adds mode context (video laid out as one clip) but then references 'autoZooms says how many' as if it were an input, which does not exist in the schema — a discrepancy that sows confusion rather than adding clarity.

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 ('Create a new project') and distinguishes itself from siblings by explaining the two modes (empty vs. from a video) and by naming importMedia as the follow-on tool. The dense phrasing makes it harder to parse than it should be, but an agent can still tell what this tool does and how it differs from createCheckpoint or importMedia.

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

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

It states the use case ('It is in the OpenScreen app's project list, so the user can open it in its editor') and explicitly names the alternative for the empty case ('Fill an empty one with importMedia'). It stops short of stating when NOT to use it, but the guidance is concrete and actionable.

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

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

Annotations already declare this is a non-destructive, non-readonly, closed-world operation, and the description adds substantial value on top: exactly what gets duplicated (footage, crop, source range, trims, zooms, speed regions, annotations, camera-fullscreen regions), the deep-copy independence property, and the returned clipId. It omits permission/error behavior, 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?

The action and placement are front-loaded in the first clause, followed by the copy semantics and return value. It is dense with detail but nearly every clause earns its place; the long enumeration makes it slightly run-on.

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 correctly states the return value (the copy's clipId). Both parameters are accounted for across description and schema, and the copy semantics are fully explained, leaving only minor gaps like failure modes.

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

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

Schema coverage is 50%: projectId is documented in the schema, but clipId has no schema description. The description confirms clipId is the input (via 'returns the copy's clipId') but adds no format, sourcing, or constraint detail for either parameter, so it only marginally compensates for the 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 precise verb (copy/duplicate) and resource (clip) with placement semantics ('placed right after it'), and distinguishes itself from moveClip, which repositions rather than copies. An agent can differentiate it from siblings like insertClip or moveClip without opening schemas.

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

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

The description makes the use case clear (get an independent copy of a clip and everything on it) and names moveClip as the alternative for repositioning. It stops short of explicit when-not guidance, but the context for choosing duplication over editing is well implied by 'edits to one no longer touch the other.'

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-destructive, closed-world. The description adds that it returns the file's path and that getFrames can verify output at ruler seconds, plus format dependence on setAspectRatio. It doesn't mention permissions or overwrite behavior at the path, leaving a minor gap.

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

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

Three sentences, front-loaded with the core action and output, then format-dependence, then option grouping. Mostly efficient, though the compositor element list is slightly dense.

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

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

Covers output (path), verification (getFrames), shape (setAspectRatio), and option scoping for a mutation tool. With 86% schema coverage and annotations, remaining gaps (overwrite behavior, error cases) are minor.

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 86%, so the schema already documents fps, quality, gifSize, gifLoop, gifFrameRate and path well. The description only restates that quality/fps are MP4-only and gif* are GIF-only, adding marginal value beyond the schema's own 'MP4 only'/'GIF only' labels.

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 (Render) and resources (MP4/GIF) plus the compositor, listing exactly what gets composited (background, cursor, zooms, cuts, speed, annotations). Clearly distinguishable from siblings like addZoom or setAspectRatio.

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?

Explains it renders the edited project and that the video's shape follows setAspectRatio, and that options mirror the Export dialog. It doesn't state when NOT to use it or alternatives for exporting, but context is clear.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuine interpretive context beyond that: the meaning of resolvedLane (recording speech vs voiceover tracks), that language null means the transcript's own words, and that 'warning' fires when captions are on with nothing to show.

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 content is front-loaded with 'Read the captions,' but it is delivered as one very long, dense run-on sentence enumerating many properties. Since there is no output schema, the detail earns its place, but the structure would be more readable if broken into grouped points.

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 carries the burden of describing return values and does so thoroughly: style, position, lane, language, captionedAssets, warning, translations and choices. For a simple read-only tool this is essentially complete, with the only gap being explicit routing guidance to siblings.

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

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

Schema description coverage is 100%, so the single projectId parameter is already fully documented in the schema, including the note about omitting it for the editor-open project. The description text adds nothing further about the parameter, so the baseline 3 applies.

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

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

The description states a clear read operation on a specific resource (caption display configuration) and enumerates exactly what is returned: enabled state, style, positioning, lane, language. It is unambiguous what the tool does, though it never names a sibling alternative (e.g. setCaptionSettings for writes), so sibling differentiation is only 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?

There is no explicit guidance on when to use this tool versus alternatives such as getCaptionTranslationUnits or getTranscript. It mentions that 'choices lists what setCaptionSettings accepts,' which hints at a write counterpart, but gives no condition for choosing getCaptions or when not to call it.

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

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

Beyond the readOnlyHint/destructiveHint=false annotations, it discloses the default filtering behavior (only untranslated units), the resume semantics for batched translation, the unit granularity ('never a single word'), and what fields come back (id, span, text). These are behavioral traits the 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?

One dense paragraph that front-loads what is read and the scoping, then the default behavior, then the downstream call. Every sentence carries information, though the run-on punctuation makes it slightly heavier than necessary.

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

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

With no output schema, the description fully describes the return shape (per asset, phrase units with id, source-second span, text) and the default filtering, leaving nothing an agent needs to call and interpret 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 25%, so the description must compensate: it explains assetId ('or the one assetId names'), includeTranslated ('returns the done ones too, with their translation'), and the default filtering tied to language. projectId is documented in the schema. Language and assetId syntax are only lightly covered, but the semantic meaning of each is clear.

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

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

Specific verb+resource: reads the caption translation units for one language, and it explicitly differentiates itself from getCaptions and getTranscript by describing the phrase-unit grouping and the per-asset scoping. An agent can distinguish it from putCaptionTranslation and getCaptions 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?

It states the workflow explicitly: default returns only units with no text yet so batched translation resumes, includeTranslated returns finished ones, and the downstream step is 'Translate them yourself, then store them with putCaptionTranslation.' This routes the agent to the sibling that consumes the output.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false, and destructiveHint=false, so safety is covered. The description adds substantial behavioral context beyond annotations: it explains the distinction between source-time and virtual edited-timeline time, lists what each region type returns, describes the settings shape, and warns that the AxcutDocument is the single source of truth whose edits should preserve existing clips and timeline state.

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

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

The description is front-loaded with the core action and uses three sentences to cover return content, usage trigger, and editing caution. It is long and dense, but the detail is largely justified because there is no output schema, and no sentence is pure filler.

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

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

With no output schema, the description carries the full burden of explaining return values, and it does so thoroughly: assets, clips, trims, regions, per-region settings, settings, settingsContext, and inactive settings. It also covers calling conditions and the relationship to the source-of-truth document, leaving no major gap for an agent to invoke the tool correctly.

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

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

Schema description coverage is 100%, and the single parameter projectId is documented in the schema with usage guidance. The description does not add syntax, format, or default meaning beyond what the schema already provides, so the baseline of 3 applies.

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

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

The description states a specific verb and resource: reading a compact snapshot of the current project. It enumerates the snapshot's major contents—assets, timeline clips and trim ranges, edit regions, settings, settingsContext, and inactive settings—so the agent can distinguish it from sibling tools that read narrower resources. The scope is clear without opening the schema.

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

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

It gives clear context for when to call: 'Call this before editing if the snapshot in the system prompt may be stale.' That tells the agent the triggering condition. It does not name alternative read tools or state when not to use this tool, which keeps it at a strong 4 rather than a full 5.

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

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

Annotations already cover read-only/non-destructive, and the description goes well beyond them: it discloses downsampling, the per-point field semantics (atSec, virtualSec, cx/cy, shape, kind, trimmed, visible), that these are raw samples not a summary, and two distinct 'available:false' failure reasons that must not be confused. That is unusually rich behavioral disclosure for a read tool.

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

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

Front-loaded with the purpose in the first clause, and every subsequent sentence carries information (field meanings, defaults, failure modes). It is dense and somewhat run-on in the middle, but no sentence is filler.

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

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

With no output schema, the description carries the return-value burden and does so thoroughly, including error semantics. The remaining gap is minor: no guidance on data volume/pagination or how to obtain a valid assetId.

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

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

Schema coverage is 50% — projectId is documented in-schema but assetId is not. The description compensates by specifying the default behavior ('Omit assetId for the primary asset'), which is meaningful semantics beyond the schema, though it never says where assetIds come from (e.g., listSources).

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 recorded pointer track for an asset') plus the shape of the data ('where the cursor was over time, downsampled to a readable rate'). This clearly separates it from siblings like getFrames (rendered frames) and setPointerTrack (mutation).

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 usage context: omit assetId for the primary asset, and virtualSec is explicitly named as the coordinate addZoom takes, which routes the agent to the downstream tool. It lacks explicit when-not-to-use guidance or a named alternative for reading pointer data from other sources.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuine behavioral value by disclosing the full payload shape (code, params, description, cost, regions), which goes beyond the annotations; it does not cover error behavior for a missing/foreign effectId, keeping it out of the top band.

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 fully load-bearing: the first defines the read and its payload, the second handles disambiguation from the sibling. The most decisive content (what is returned) is front-loaded with zero 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?

With no output schema, the description carries the return-value burden and does so by enumerating the fields returned. Annotations cover the read-only profile. The only gap is the absence of any note on failure modes (invalid effectId, missing projectId outside the editor), which the sibling projectId description hints at but this description does not.

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

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

Schema description coverage is 50% – projectId is documented in the schema, but effectId has only a minLength constraint and no description. The description's 'one effect of the project' implies the id scopes to a single effect and that projectId scopes the project, which is mild compensation, but it adds no format, sourcing, or fallback detail for effectId.

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 one effect of the project in full') and then enumerates exactly what is returned: WGSL code, parameters, description, cost, and using regions. It also explicitly distinguishes itself from the sibling getCurrentDocument, so an agent can route without opening either schema.

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

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

The second sentence names the alternative and the condition that separates them: getCurrentDocument lists effects but omits their code, so this tool is the one to call when the code itself is needed. It stops short of an explicit 'use this when...' statement or any exclusion (e.g. batching), so it is strong context but not full when/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?

Beyond the readOnly/non-destructive annotations, it discloses meaningful runtime behavior: with projectId you receive the last export, or, if none exists or it is stale, frames rendered from the project without exporting it — a non-obvious caching/fallback rule. It also surfaces the 12-frame ceiling, which the annotations do not cover.

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 core capability and the 12-frame limit are front-loaded, then the two modes are explained in order. A few clauses (e.g., restating count's default/spread behavior already in the schema) border on redundant, but most sentences carry distinct 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 read-only tool with no output schema and four optional params, the description covers both modes, the return concept (still images), the frame cap, and the export-vs-render fallback. It does not describe the response shape (image format, ordering) or failure behavior, which is a modest gap.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes further by defining atSec's units precisely: ruler seconds mapped through trims and speed regions for projectId versus the file's own seconds for path. That mapping logic is not derivable from the schema alone.

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

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

The opening sentence states a specific verb (look/view) and resource (a video as still images) and adds a hard scope limit (at most 12 per call). It is easily distinguished from siblings like getTranscript, getCursorTrack, and getCaptions, which return other artifacts of the same project.

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

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

It gives a concrete when-to-use prompt ('Ask for the moments you need to check, such as each zoom and each callout') and clearly separates the two invocation modes (projectId for checking an edit, path for any video file). It stops short of naming an alternative tool or an explicit when-not-to-use condition.

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=true, so safety is already covered, and the description goes further by disclosing the exact shape of returned data (speech and silence segments with start/end seconds and text). With no output schema, this return-format disclosure is genuinely valuable. It does not mention scope limits, pagination, or auth.

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

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

Two tight sentences, front-loaded with the core action and immediately followed by the default-parameter rule. No filler.

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

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

No output schema exists, and the description steps in to describe the returned segment format, so an agent knows what comes back. Combined with annotation-covered safety and the assetId default rule, it is close to complete, missing only guidance relative to sibling transcript tools.

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

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

Schema coverage is 50%: projectId is documented in the schema but assetId is not. The description compensates by explaining assetId's omission semantics ('Omit assetId to read the primary asset's transcript'), adding real meaning beyond the bare schema type.

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 ('Read the transcript segments ... for an asset') and even enumerates the returned fields (speech/silence, start/end seconds, text). It does not explicitly distinguish itself from near-siblings like getTranscriptWords or getCaptions, so it falls short of the top tier.

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 one concrete usage rule ('Omit assetId to read the primary asset's transcript'), which clarifies a default behavior. It offers no guidance on when to prefer this over getTranscriptWords or getCaptions, leaving the choice to inference.

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

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

Annotations already declare readOnlyHint/destructiveHint=false, so safety is covered. The description goes further by disclosing the conditional presence of source/originalText fields, the id-namespace distinction between this tool and getTranscript, and the practical constraint that whole transcripts are large so startSec/endSec should be used to narrow the read.

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

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

Purpose is front-loaded in the first clause and every sentence carries information (id namespace, range scoping, assetId default). It is a single dense paragraph with heavy parentheticals, which is slightly taxing but not 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?

With no output schema, the description carries the return-value burden and does so completely (word ids, text, timing, conditional correction fields). Combined with the sibling routing and the range-narrowing advice, an agent has everything needed to call it correctly.

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

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

Schema coverage is only 25% (projectId alone is documented), so the description must compensate, and it does: it explains startSec/endSec as a passage window ('read just the passage you mean to fix') and assetId as omittable for the primary asset. It does not describe endSec/startSec units or ordering beyond the schema's numeric constraints, 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 ('Read the transcript one WORD at a time for an asset') and enumerates the exact fields returned (id, text, start/end seconds, source, originalText). It explicitly distinguishes itself from the sibling getTranscript, so an agent can tell them apart without opening either schema.

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

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

Gives explicit when-to-use and when-not-to-use guidance: 'This is the ONLY read that gives you the ids setWordText and removeWords take' and 'getTranscript answers in segments, whose ids belong to a different namespace and are not accepted there.' It also names the sibling alternatives and the condition selecting them.

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

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

Annotations only state it is a non-destructive, non-open-world write; the description adds the real side effects an agent needs — media is added to the project but not the timeline, and the asset may silently become the project's footage. It also discloses the failure mode (durationSec null when OpenScreen could not read the file). It stops short of covering deduplication or re-import behavior.

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

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

Front-loads the core action and the key non-behavior ('does not place it on the timeline') in the first two sentences. The third is dense with three chained conditions, but each clause carries genuine routing information 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?

With no output schema, the description correctly supplies return values (assetId, durationSec, and the null case), and the schema covers all four parameters. The only gap is guidance on importing the same file twice or replacing existing media, which would matter for a media-mutating tool.

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

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

Schema description coverage is 100%, including the kind enum default and the extension lists for path, so the schema already carries parameter meaning. The description adds no syntax, format, or defaulting detail beyond that, making the baseline 3 appropriate.

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

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

States a specific verb and resource ('Add a video or audio file from disk to the project's media') and immediately bounds the scope with 'It does not place it on the timeline', which separates it from timeline-manipulating siblings like insertClip and replaceTimeline.

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 routes the agent: audio is played later via addAudio, and video only becomes project footage if createProject made one without a video, after which replaceTimeline lays it out. It names the downstream alternatives and the conditions that select them rather than leaving sequencing 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 a non-read-only, non-destructive, closed-world mutation, and the description adds real behavioral context beyond that: clips stay back to back so later clips shift, adjacent same-media clips are joined (joinedIntoNeighbour), and sourceStart/Sec default to the whole asset. It stops short of permissions/error behavior, but the side-effect disclosure is unusually strong for a mutation tool.

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

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

Front-loaded with the core action and insertion point, then defaults, then side effects, then alternatives. Dense and mostly waste-free, but the parenthetical joining sentence ('Its media continuing the clip before it makes the two one clip') is convoluted enough to cost a point.

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

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

For a 5-param mutation with no output schema, the description covers placement, defaults, side effects on neighboring clips, and routing away from `addAudio`/import tools. Only minor gaps remain (e.g., how the join result is surfaced, error cases), which are not enough to block correct invocation.

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

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

Schema description coverage is only 20% (only `projectId` is documented), so the description has to compensate and largely does: `beforeClipId` null/omitted places the clip last, `assetId` accepts any video asset of getCurrentDocument, and `sourceStartSec`/`sourceEndSec` select a stretch in source seconds with whole asset as default. Units and defaults are conveyed, though the exact semantics of inclusive/exclusive end times are left implicit.

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 (place/insert) and resource (a clip of a video asset on the timeline) plus the exact insertion anchor (just before `beforeClipId`). It also distinguishes itself from siblings by naming `addAudio` and ruling out disk imports, so an agent can tell it apart from `importMedia` and `addAudio` without opening either 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 cases (another take, footage already imported in the editor) and an explicit when-not: an audio asset is not footage, use `addAudio`. It also clarifies scope with 'Any video asset of getCurrentDocument works, the primary one too' and negatives the alternative 'Nothing here imports a file from disk.'

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=true, destructiveHint=false, openWorldHint=false), so the bar is lower. The description still adds non-obvious behavior: the `open` flag means edits route through the live editor session and are user-undoable via Ctrl/Cmd+Z, which genuinely informs how results should be interpreted.

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 essential content: the returned fields first, then the chaining convention. No filler or repetition.

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

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

With no output schema, the description must describe the return shape, and it does so completely (five named fields) while also explaining the semantics of the least obvious one. An agent has everything needed to call it and use the results.

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

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

The tool takes zero parameters, so the baseline is 4. The reference to `projectId` pertains to other tools, not this one, and is correctly framed as such.

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 a specific verb (list) and resource (OpenScreen projects) and enumerates exactly what each returned entry contains: id, title, last update, asset count, and the `open` flag. This is unmistakably distinct from siblings like createProject or setProjectInfo.

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?

States the downstream workflow explicitly: pass a project's id as `projectId` to any other tool to read or edit that project, making this the natural discovery entry point. It does not name an alternative or a when-not condition, so it falls short of the top tier despite strong contextual routing.

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

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

Annotations already cover the read-only safety profile, yet the description adds substantial behavior: permission-gated labels (microphoneLabelsUnavailable/cameraLabelsUnavailable and the remediation of asking the user), and the exact conditions under which windows are omitted (minimized, hidden, other desktop/Space, behind full-screen). This is meaningful context beyond structured fields.

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

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

Purpose is front-loaded in the first sentence, followed by usage and edge cases. It is dense across four sentences but each carries distinct information; only minor tightening is possible.

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 fully explains the shape of the return (display indexes, window titles, device names, and the two unavailability booleans) and the listing exclusions. An agent has everything needed to call it and interpret results.

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

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

The tool takes zero parameters, so per the rubric the baseline is 4. The description usefully explains how the returned values (indexes, title substrings, name substrings) are consumed downstream, though there are no parameters to document.

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

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

Specific verb (List) plus concrete resources (displays, windows, microphones, cameras) tied to the OpenScreen product. It implicitly distinguishes itself from siblings like startRecording/stopRecording by framing the output as input to startRecording.

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 routes the agent to the consuming tool ('Pass startRecording a display's index or part of a window's title'), which is clear usage context. It lacks an explicit when-not-to-call statement, but the workflow context is unambiguous.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the safety profile is covered. The description adds real value beyond that by guaranteeing that clip ids, source ranges, trims, zooms, speed regions, and annotations are all preserved — key reassurance for a reordering mutation. It does not disclose failure modes for invalid ids or missing project context.

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

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

The core action and positioning convention are front-loaded in the first sentence. The preservation sentence and the sibling contrast add length but each carries useful information; minor trimming is possible 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?

With no output schema and a simple three-parameter mutation, the definition covers action, id sourcing, positioning semantics, preservation guarantees and sibling routing. Remaining gaps (auth requirements, error behavior) are minor.

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, and it does: it explains that ids come from getCurrentDocument (with `index` and `reason` label), and that `beforeClipId` null/omitted means move last. The third parameter, projectId, is already well documented in the schema.

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

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

States a specific verb and resource: "Reorder a placed clip: move `clipId` so it plays just before `beforeClipId`." It explicitly distinguishes itself from the sibling replaceTimeline, so an agent can route between them without opening either schema.

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

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

Gives explicit use cases ("swap these clips", "put X first", "change the clip order") and names the condition that selects the alternative: "replaceTimeline cannot reorder anything." It also states the null/omit convention for placing a clip last.

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 the generic write/non-destructive/local profile, and the description adds substantial behavior: merge semantics into an existing layer, first-call creation, atomic refusal of the whole call on unknown unit ids, and the guarantee that the transcript is never altered. This is far beyond what the annotations convey.

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

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

It is dense but front-loaded with the core action and structured by parameter, with every sentence contributing a non-obvious constraint. It is slightly long, but no sentence is 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 mutation tool with no output schema and low schema description coverage, the description covers behavior, merge/atomicity semantics, parameter meaning, and the relationship to the caption-switching sibling. Only assetId's precise semantics are left implicit.

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

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

Schema description coverage is only 20%, so the description carries most of the load: it explains the units array shape {id, text}, that the id comes from getCaptionTranslationUnits, what language means (layer code like fr or pt-BR), and that label defaults to the code. assetId remains implicit and projectId's meaning is only in the schema, so it falls just short of full compensation.

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

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

The description opens with a specific verb and resource: storing translation of caption units for one asset into a language layer. It also names the sibling that supplies input ids (getCaptionTranslationUnits) and the sibling that performs the adjacent action (setCaptionSettings), so an agent can place it precisely in the toolset.

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 when to use this versus alternatives: use setCaptionSettings to actually switch captions to the layer, use getCaptionTranslationUnits to source unit ids. It also gives operational guidance (send long transcripts in batches since the first call creates the layer), which is exactly the routing an agent needs.

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

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

Annotations only flag readOnlyHint=false, openWorldHint=false, destructiveHint=false, so the description does real work by disclosing that the transcript is untouched and that captions revert to the transcript's own language. This confirms the non-destructive framing, though it says nothing about permissions, error cases, or whether removal can be undone.

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

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

Two short sentences, front-loaded with the action and scope; the second sentence delivers the non-obvious behavioral consequence. No filler.

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

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

There is no output schema and annotations are thin, so the description appropriately covers the key behavioral outcome (transcript preserved, captions fall back). It is nearly complete for a mutation tool, with the only gap being the unexplained language 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?

Schema description coverage sits at 50%: projectId is documented in the schema ('from listProjects', with the editor-only omission caveat) but the required language parameter carries only a regex pattern and no description. The description mentions no parameter at all, so it fails to compensate for the undocumented required field.

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

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

States a specific verb and resource ('Delete one caption language layer') with scope limited to a single layer, distinguishing it from the sibling putCaptionTranslation which writes that layer. An agent can tell exactly what this does without opening the schema.

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

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

Usage is only implied: the description conveys that this removes a translation layer and restores transcript-native captions, which suggests when to use it, but it names no explicit conditions or alternatives (e.g., 'use putCaptionTranslation to add or update a layer').

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds real consequence detail beyond that: remaining clips close the gap and effects anchored to the clip are dropped. It stops short of saying whether the deletion is recoverable or whether a checkpoint (a sibling tool exists) should be created first, which would fully close the loop for a destructive mutation.

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

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

Two sentences, zero filler, with the destructive effect and the routing rule both front-loaded. 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?

No output schema exists, so the description must convey enough for correct invocation, and it does for the core action plus side effects. The main remaining gap is the source of clipId and whether removal is reversible, neither of which the schema supplies.

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

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

Schema description coverage is 50%: projectId is documented in the schema (including the omit-for-open-project rule), but clipId carries only a minLength constraint. The description says deletion is 'by id' but never says where that id comes from or that it must reference a placed clip in the target project. Partial compensation for a half-documented 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 ('Delete a placed clip by id') and immediately separates itself from the nearest sibling by naming setClipRange as the tool for shortening. An agent can distinguish it from removeMedia, removeWords, removeTrim, and removeClip-adjacent siblings 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 when-to-use ('Use only when the user asks to remove a clip') paired with an explicit alternative and the condition that selects it ('to shorten one, use setClipRange'). This is the exact when/when-not/alternative pattern.

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 destructiveHint=true and readOnlyHint=false, but the description adds the non-obvious nuance that the destructive operation only detaches the media reference while 'the file on disk is left alone', and discloses a hard dependency-based refusal condition. That is material behavior an agent cannot infer from the hints.

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

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

Three short sentences, front-loaded with the action, then the blocking condition, then the non-destructive caveat. No sentence is 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?

There is no output schema and no statement of what the call returns or whether the removal can be undone (e.g. via createCheckpoint/restoreCheckpoint). Otherwise the hazards of a mutation with no return contract are well covered by the refusal rule and the disk-file caveat.

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

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

Schema description coverage is 100% and both parameters document their own source (getCurrentDocument's assets, listProjects) and the projectId omission rule, so the description adds no parameter-level detail. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb and resource ('Remove a file from the project's media') and immediately scopes it against siblings by clarifying that the on-disk file survives. An agent can distinguish this from removeClip/removeModifier without reading any schema.

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

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

Gives an explicit precondition for failure ('Refused while the timeline still uses it') plus the exact prerequisite actions and the sibling tools that perform them (removeClip, removeModifier). This is when-to-use and when-not-to-use in two sentences.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds real behavioral detail beyond them: same-styling 'pill' rows are deleted together, and removedIds must be read to learn the full set removed — important for a destructive operation. It omits any note on permissions, checkpointing, or reversibility, so it falls short of a 5.

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

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

Front-loads the action and the id/kind resolution, then layers consequences and alternatives. Dense and largely waste-free, though the parenthetical kind enumeration and the two-alternative tail make it longer than strictly necessary for a two-parameter tool.

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

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

With no output schema, the description still tells the agent to inspect removedIds for the complete deletion set, and it covers the grouped-deletion behavior, the neutralising pitfall, and sibling routing. Enough for correct invocation.

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

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

Schema coverage is 50%: projectId is documented in the schema (including the OpenScreen editor caveat) while id is not. The description compensates partly by explaining that id is an opaque handle from which the kind is resolved, but it never says where to obtain a valid id.

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

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

States a precise verb (Delete) plus the resource (modifier) and enumerates the five modifier kinds it covers, noting the kind is derived from the id. It is clearly separable from siblings like removeTrim and removeClip.

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 routes the agent: use removeTrim for a trim, removeClip for a clip, and states the anti-pattern to avoid (neutralising with span 0 / 1× speed). This is direct when-to-use and when-not-to-use guidance.

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

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

Annotations already flag destructiveHint=true and readOnlyHint=false, so the safety profile is known. The description adds genuine value beyond that by explaining what the operation reverses ('the cut is undone and that span plays/exports again'), clarifying the semantic effect rather than just the mutation. It doesn't mention reversibility of the removal itself or any confirmation/permission requirements, but the core behavioral effect is well conveyed.

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

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

Two tight clauses, front-loaded with the action and effect, then the usage rule. No filler; every sentence carries distinct 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 destructive single-parameter mutation with annotations covering the safety profile and no output schema, the description is largely complete: it explains the effect and the routing. The one gap is the origin of trimRangeId, which is left implicit.

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

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

Schema coverage is 50%: projectId is well documented in the schema, while trimRangeId has no schema description. The description mentions 'by id' but does not state where trimRangeId comes from, unlike projectId which points to listProjects. It compensates only partially 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 and resource ('Delete a trim range by id') and immediately clarifies the effect ('the cut is undone and that span plays/exports again'), which cleanly distinguishes it from addTrim, addTrims, and setTrim among the siblings.

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

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

Explicitly routes usage: 'This is how you remove a trim' and names the anti-pattern to avoid ('never re-add a trim to undo one'). This tells the agent both when to use this tool and what not to do instead of addTrim, which is exactly the sibling-confusion risk 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?

Annotations only supply readOnlyHint=false, destructiveHint=false and openWorldHint=false; the description adds the atomicity guarantee ('If any ID is missing, invalid, duplicated, already cut or ambiguous, nothing changes'), that the transcript is untouched, that consecutive words collapse into ONE trim including gaps, and the `cutTransitions` warning behavior. This is exactly the context the annotations do not carry.

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 purpose is front-loaded in the first clause and nearly every subsequent sentence adds distinct operational information (source of IDs, atomicity, result contents, warning payload). It is a dense, long run-on paragraph, but there is little pure filler; the length is justified by the absence of an output schema.

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

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

For a complex mutation tool with no output schema, the description covers prerequisites, ID sourcing, failure/atomicity semantics, what the result contains, and the cutTransitions warning in enough detail that an agent can invoke and interpret it without further context.

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

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

Schema description coverage is only 33% (only `projectId` is documented), so the description must compensate and largely does: it defines `wordIds` as IDs from getTranscriptWords numbered independently per asset, and fully explains `assetId` including the omission rule. It stops short of clarifying wordId format or ordering constraints, so it is strong rather than 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?

States a specific verb and resource: 'Cut the spoken words selected by `wordIds` from getTranscriptWords out of the film,' and enumerates the intended cases (fillers, repeated/flubbed phrase, false start, duplicate take). This is clearly distinguishable from siblings like removeTrim or removeClip, which operate on trims and clips rather than transcript words.

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 usage rules: pass the same `assetId` as the read, omit it only when IDs are unique across all transcripts, and choose IDs yourself because 'the executor does not classify speech.' That tells the agent both how to call it and what not to expect, though it does not name an alternative tool for cases this tool cannot serve.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds non-obvious behavior beyond them: intervals are SORTED so reordering is impossible, and the call is refused when it would merge away, shorten or drop an existing clip, with the refusal naming the affected clips and the replacement tool. That is real operational context an agent cannot get from 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 with the core action and its effect, then the ordering guarantee, then the exclusions and alternatives. Dense and mostly waste-free, though the phrasing around the two sibling tools is slightly repetitive and could be tightened.

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

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

No output schema exists and none is needed for a mutation, but the description does cover the important failure mode (refusal naming clips) and the input semantics. Minor gap: it says nothing about the optional 'reason' parameter or any prerequisite like a checkpoint, which siblings such as createCheckpoint imply may matter.

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% (projectId documented, reason and intervals structures undocumented). The description compensates substantially for the key parameter by defining what the intervals mean — source-time ranges of the primary asset where everything outside becomes a trim — which the schema does not say. 'reason' remains unexplained, keeping this below 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+resource ('Replace the whole timeline') plus the exact scope of the input ('kept intervals of the primary asset's source time') and the consequence ('Everything outside the intervals becomes a trim'). It also distinguishes itself from siblings by name, so an agent can pick it over moveClip/insertClip 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?

Explicit when-to-use ('ONLY when the user explicitly asks you to rebuild the timeline from scratch'), when-not ('DO NOT use this for cut silences or remove pauses'), and two named alternatives with their triggering conditions (moveClip for reordering, insertClip for other assets). This is a complete routing instruction set.

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 destructiveHint=true, but the description adds far more: it discloses that all edits since the checkpoint are discarded including the user's, that the setPointerTrack pointer is reverted, and that on the open editor project it lands as a single undoable step. These are concrete behavioral consequences an agent cannot infer from annotations alone.

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

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

Three sentences, none wasted: the destructive scope is front-loaded, then the parameter linkage, then the undo behavior. Terse and well ordered.

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

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

For a destructive mutation with no output schema, the description covers what is destroyed, the parameter provenance, cross-tool dependencies, and recoverability via undo. Combined with annotations that already carry the safety profile, nothing needed to invoke it correctly is missing.

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

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

Schema coverage is 50% and checkpointId has no schema description, but the description supplies its origin ('when createCheckpoint returned this checkpointId') and reinforces projectId semantics ('same projectId as to createCheckpoint'). It adds genuine meaning beyond the schema, though it does not restate the editor-fallback rule for omitting projectId.

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 ('put the project back exactly as it was when createCheckpoint returned this checkpointId') and explicitly scopes what is discarded. It ties itself to the sibling createCheckpoint, so an agent can distinguish it from other edit tools 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 clear usage context: pass the same projectId as to createCheckpoint, and the checkpointId comes from createCheckpoint's return. It also implies the restore must follow a prior checkpoint. It does not state explicit exclusions (e.g., when not to restore), but the trigger condition is unambiguous.

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

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

Annotations only declare readOnlyHint=false, destructiveHint=false, openWorldHint=false, which the description goes well beyond. It discloses partial-update semantics, type-conversion behavior (stays put on screen, default box for arrow/blur, text retained for revert), text-box refit around centre, rejection of cross-type arguments, and span-collision refusal with the conflicting annotation named.

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

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

The description is long but front-loaded with verb+resource and ID, then proceeds field-group by field-group. Nearly every sentence carries distinct behavioral information (conversion rules, refit, refusals). It is dense rather than padded, though the enumerated field list is somewhat sprawling.

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 nested objects and no output schema, the description covers the critical semantics: partial updates, type-conversion side effects, and input validation refusals. It does not describe what the call returns, but with no output schema that is not expected.

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 59%, so the description must compensate, and it does by grouping parameters semantically and flagging applicability (width/height only for arrow and blur, look fields only for text). It clarifies that figureData/blurData are partial (only passed keys change). Some nested fields like freehandPoints and endSec get no added meaning, but overall it adds substantial value over 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 (Change) on a specific resource (an existing annotation by id) and enumerates exactly which field groups are editable: span, type, centre, size, text/look, figureData/blurData. This clearly separates it from the sibling addAnnotation (creates) by specifying it mutates an existing annotation identified by id.

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

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

Gives clear context: operate on an existing annotation by id, and only the fields passed are changed. It also documents refusal conditions (wrong-kind arguments, span collisions). However, it never explicitly names addAnnotation as the creation alternative or states when-not to use this tool, so routing guidance is implied rather than spelled out.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: 'Annotations on the frame keep their place and shape,' disclosing that existing overlay content is preserved when the ratio changes. It stops short of stating whether the change is immediate or undoable.

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

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

Front-loads the core action, then packs value-mapping and sibling equivalence into two tight sentences. The enumeration is long but every entry carries decision-relevant information for picking a ratio.

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

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

For a 2-param, no-output-schema mutation tool with annotations covering safety, the description covers purpose, valid inputs, cross-tool equivalence, and preservation behavior. Minor gaps remain (immediacy of effect, undo, permission requirements) but nothing blocks correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema by explaining what each ratio value is for (16:9 = X/YouTube/slide, auto = follow recording) and by clarifying that a token from getCurrentDocument's settingsContext.originalAspectRatios is a valid input.

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 ('Set the shape of the exported video') and enumerates the value space, so the agent immediately knows this is an aspect-ratio setter. It also explicitly relates itself to the sibling setEditorSettings ('The same as setEditorSettings with aspectRatio alone'), disambiguating it from that tool.

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

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

Gives concrete usage guidance by mapping each value to an intent (16:9 for X/YouTube/slide, 9:16 for vertical story/short, 1:1 or 4:5 for square feed, auto to follow the recording). Lacks explicit when-not-to-use guidance, but the setEditorSettings equivalence tells the agent the two can be used interchangeably.

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 a non-read-only, non-destructive, closed-world mutation. The description adds real behavioral context beyond that: 'Only the fields you pass are changed' establishes PATCH-style partial-update semantics, and 'the whole track is edited, not one fragment' warns that splits are not targeted. It does not state auth or permission requirements, but for this profile the added semantics are meaningful and consistent 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?

A single dense paragraph with the core verbs front-loaded before the use-case examples and the partial-edit caveat. Nearly every clause adds information, though the enumeration is long enough that it borders on listy.

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

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

For an 11-parameter mutation with no output schema, the description covers update semantics, scope (whole track vs. fragment), and the meaning of most editable fields. An agent has enough to invoke it correctly; only explicit required/optional signaling and permission notes are absent.

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

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

Schema description coverage is only 9% (just projectId), so the description must carry the burden, and it largely does: gainDb (ducking), fadeInMs/fadeOutMs with the 0-5000 ms range, offsetSec (which part of the file plays), kind (voiceover/music lanes), plus the move/resize/mute/loop fields implied by the verb list. It adds units and intent the bare schema lacks, though it doesn't spell out startSec/endSec or the gainDb range the schema enforces.

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?

Opens with a specific set of verbs (move, resize, re-level, re-lane, mute, loop, fade, re-point) applied to a concrete resource: an existing audio track identified by id. This clearly separates it from siblings like addAudio (new track) and removeMedia, so an agent can select it 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 use cases — duck a bed under narration via gainDb, fade in/out, offsetSec to shift the played portion, kind to move between voiceover and music lanes. This tells the agent when the tool is the right choice. It does not explicitly name an alternative tool or state exclusions, 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 declare a non-read, non-destructive, closed-world mutation, so safety is partly covered. The description adds genuinely new behavior beyond them: merge semantics for omitted fields and a documented refusal condition, which the agent could not infer from the schema or hints.

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

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

Three short sentences, each front-loaded with a distinct fact (action, merge semantics, refusal condition). No filler and no repetition of the schema.

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

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

For a no-output-schema mutation tool this covers the essentials: what it edits, how omitted fields behave, and when it fails. It stops short of return value or permission requirements, which is acceptable given the schema and annotations carry the rest.

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

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

Schema coverage is only 25% (just projectId), so the description must carry the load. It usefully supplies the unit for startSec/endSec ('virtual-timeline seconds') and the meaning of cameraFullscreenId ('by id'), but adds nothing about valid ranges or the relationship between startSec and endSec.

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 pair ('move or resize'), the resource ('existing camera-fullscreen region'), and the lookup key ('by id'), which cleanly separates it from the sibling addCameraFullscreen. An agent can pick it without opening the schema.

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

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

Gives the partial-update contract ('Only the fields you pass are changed') and a hard precondition ('Refused if the new span lands on footage with no linked webcam'). It does not explicitly name addCameraFullscreen as the creation alternative, but the 'existing ... by id' framing makes the edit-vs-create split clear.

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

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

Annotations only cover the safety profile (not read-only, not destructive, closed world); the description instead supplies the non-obvious behavior: field precedence (style first, then plate, then any explicit field wins), the plate-driven recolour side effect, lane fallback with resolvedLane to detect it, and that enabled captions are burnt into the export. This is exactly the context annotations cannot carry.

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 action and the precedence rule, and every clause carries information rather than filler. It is a single dense block for 17 parameters, though, and prose is doing work that a short structured list would do more scannably.

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, and the description still volunteers the one interesting return signal (resolvedLane) plus the export side effect. Given 17 parameters, zero required fields, and a mutation with no destructive annotation, the agent has everything needed to call it correctly.

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

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

Schema description coverage is 6%, so the description carries nearly the whole burden and does: ranges and units for insetX/insetY, fontSize, plateOpacity, min/maxWordsPerLine, hex format for color, what each anchor does, the rule that insetX is ignored when anchorH is centred, and what language/lane select. Only projectId/fontFamily/fontWeight are left to the schema, and fontFamily/fontWeight are folded into the 'style' explanation.

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?

Opens with a specific verb pair ('turn the captions on or off') plus the styling/positioning scope, and anchors it to a concrete mental model ('as the editor's Captions pane does'). It is clearly distinguishable from read-side siblings like getCaptions and translation-side siblings like putCaptionTranslation.

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?

States patch semantics explicitly ('Only the fields you pass change') and gives the prerequisite that captions require a transcript, plus the lane fallback rule. It never names a competing sibling tool or says when to prefer getCaptions/putCaptionTranslation over this, so it stops short of full routing guidance.

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

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

Annotations only declare readOnly=false, destructive=false, openWorld=false; the description goes well beyond by disclosing mutation semantics ("Only the fields you pass are changed"), timeline side effects ("All clips are re-laid back-to-back afterwards, so downstream clips shift automatically"), and a subtle result condition ("joinedIntoNeighbour when an edit made them so"). These are exactly the consequences an agent can't infer from 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 with purpose, then the when/when-not rule, then parameter and return nuances. It is dense and em-dash-heavy but each clause carries distinct information (trim distinction, crop semantics, re-layout behavior, join condition). Slightly packed rather than wasteful.

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

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

For a 5-parameter mutation with no output schema and modest schema coverage, the description covers the essential effects: partial update, automatic re-layout, crop reversal, and the join result. It does not cover error/permission behavior or interactions when range and crop are combined in one call, but nothing critical for correct invocation is missing.

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

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

Schema coverage is only 40%, so the description must compensate, and it does for the two undocumented numeric fields by framing them as in/out points in source-time seconds. cropRegion gets more meaning than the schema gives, including the "null shows the whole frame" reversal behavior and its availability via getCurrentDocument. clipId is left implicit, which is minor but 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+resource: "Set a clip's in/out points (source-time seconds) to shorten its head or tail ... and/or its crop." It immediately distinguishes itself from the sibling trim operations by defining a trim as cutting "a span inside the clip." An agent can separate this from setTrim/addTrim/addTrims 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 explicit gating ("Change the range ONLY when the user explicitly asks to shorten or extend a clip") plus a named anti-pattern with a redirect: "Do NOT use this for 'remove silences' or 'cut pauses' — for those, use addTrim." This is exactly the when/when-not/alternative structure needed to route 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 carry the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false); the description adds substantial behaviour beyond that: rejection of out-of-range values or unknown keys with nothing changed (atomicity), a return value listing what was applied plus an `inactive` set for settings without effect, and cross-field interactions like formatFollowCursor overriding the fill-follows-cursor behaviour.

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 instruction and merge rule are front-loaded in the first sentence, and the category labels (Background:/Frame:/Camera:) give scannable structure. It is still a single dense paragraph for 28 keys, and some range-only entries such as "motionBlurAmount 0–1" add little, but the bulk of the length is justified by the parameter surface.

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 28-parameter mutation tool with no output schema, the description covers the merge contract, validation failure behaviour, the shape of the result including `inactive`, and a dependency precondition. It is close to complete; only the few unexplained keys and the absence of any undo/reversibility note leave a gap.

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

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

Schema description coverage is only 21%, so the description must compensate, and it largely does: it enumerates nearly all 28 keys grouped by Background/Frame/Camera/Cursor and adds meaning the schema lacks (wallpaper accepted formats, per-axis cropPan with 0.5 = centred, cropRegion width = height ≥ 1/3, aspectRatio token sourcing). A handful of keys (frameTheme, webcamLayoutPreset, webcamMirrored, shadowIntensity) are named with no added semantics, keeping it short of 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?

"Change the project's look: pass only the settings to change, named as getCurrentDocument returns them under `settings`" is a specific verb+resource with clear merge semantics, and it points at the sibling that supplies the shape. It does not, however, disambiguate against siblings that also touch these fields (setAspectRatio, setProjectInfo, setEffect), so a 5 is withheld.

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

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

The description implies when to use it — only pass the keys you want changed, and read current values from getCurrentDocument — and it discloses preconditions such as settingsContext.cameraSegmentation being required for webcamBackgroundMode "custom". But there is no explicit when-not guidance or routing versus setAspectRatio/setProjectInfo, which overlap on individual fields.

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 a non-read-only, non-destructive mutation. The description adds meaningful behavioral detail beyond that: only passed fields change, values equal to defaults are dropped, and the operation is refused if the new span collides with another effect (one runs at a time). It could have added more about prerequisites or return behavior, but the mutation semantics and failure mode are well 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?

Three tight sentences, front-loaded with the core action and followed immediately by mutation semantics and the conflict-refusal rule. Every sentence adds information and there is no filler.

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

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

For a mutation tool with six parameters, a nested object, no output schema, and sparse schema descriptions, the definition is largely complete: it covers purpose, partial-update behavior, default-omission, and conflict refusal. It leaves some parameter-level detail for the schema, but given the annotations and the complex input shape, it is adequate and helpful.

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

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

With schema description coverage at only 17%, the description must carry more weight. It identifies the mutable groups (span, values, target) and notes span uses virtual seconds, plus the default-dropping behavior for values. But it does not explain the structure of the values object or clarify the target enum beyond its name, leaving much for the schema to describe despite the low coverage.

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

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

The description states a specific verb set (move, resize, re-tune), the resource (effect region), and the fields that can change (span, values, target). It clearly implies modification of an existing region by id, distinguishing it from creation tools like addEffect, but it does not explicitly name any sibling alternative.

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

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

Usage is implied by the need for an effectRegionId and by the refusal condition when spans overlap, which tells the agent one effect runs at a time. However, there is no explicit when-to-use versus when-not-to-use guidance, and no alternative sibling is named for comparison.

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

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

Discloses substantial behavior beyond the annotations: new code is compiled before apply and rejected with the compiler's error, the edit propagates to every region using the effect, removed parameters lose their values, and remaining bounds are re-clamped. This is exactly the mutation-safety context an agent needs; annotations only supply the coarse safety flags.

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

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

Three dense sentences, front-loaded with the mutation and its propagation scope, then the compile gate, then the parameter-removal consequence, then the getEffect prerequisite. No filler or repetition.

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

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

For a six-parameter mutation with nested schemas and no output schema, the description covers the critical semantics: scope of change, compile validation, and data-loss behavior on removed params. It does not mention permissions/authorization or the projectId context, but that parameter is documented in 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?

With only 17% schema description coverage, the description compensates by naming most top-level fields and attaching behavioral meaning to them (code is WGSL and compiled, params changes can drop/re-clamp values). It does not unpack the nested param object shapes, but the schema carries those.

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

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

States a specific verb (Change) and resource (an effect itself by effectId) and enumerates the mutable fields (name, description, WGSL code, params). It also scopes the blast radius ('every region that uses it'), which implicitly contrasts with the sibling setEffect, though it never names that sibling explicitly.

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

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

Explicitly routes the agent to getEffect for reading the current code before rewriting, which is concrete pre-call guidance. It gives no explicit when-not conditions or direct comparison to setEffect, so it stops just short of 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?

Goes well beyond the destructiveHint=true annotation by stating exactly what is destroyed ('replaces the pointer recorded with the take'), the state dependency (checkpoint requirement, only for this server's takes), the side effect (plans zooms on new clicks clear of existing ones), and the return signal (autoZoomsAdded).

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 front-loaded: the scenario that selects the tool comes first, then behavior/undo, then the coordinate math. Every clause carries actionable information, including the formula an agent needs to build valid events.

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

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

For a nuanced edit operation with no output schema, it covers what is destroyed, the checkpoint/undo model, the zoom-planning side effect, and the return field. An agent has everything needed to call it correctly.

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

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

Schema description coverage is 0%, and the description fully compensates: it defines `at` (epoch ms from Date.now(), same clock as recordingStartedAt), `x`/`y` as fractions 0–1 of the recorded window, and even supplies the border/outerWidth/outerHeight formula to convert client coordinates.

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 ('setPointerTrack' → 'Give the pointer's path here and OpenScreen draws it') and defines the exact scope: script-driven takes where the real pointer never moved. An agent can tell this apart from getCursorTrack (reads the track) and addZoom/addAutoZooms (which this tool plans zooms as stopRecording does), even without the sibling named verbatim.

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

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

Explicit when-to-use ('For a take driven by a script rather than the real mouse'), when-not ('Only for a take recorded by this server'), and the alternative/undo path ('restoreCheckpoint undoes it'). It also names the precondition (needs a checkpoint on a project not open in the editor).

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds real value beyond them by bounding the blast radius ('Changes nothing else') and by equating the effect with the in-app rename action, telling the agent this is a metadata-only 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?

One front-loaded sentence with the essential action first and the scope-limiting clause last. Slightly redundant phrasing ('as renaming it there does' after already naming the UI surfaces) keeps it just short of ideal.

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 two-parameter, non-destructive mutation with full schema coverage and no output schema, this covers what the agent needs: what changes and, importantly, what does not. Return/response behavior and any permission requirements are left 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?

Schema description coverage is 100%, so the schema already documents both 'title' and 'projectId' (including the editor-open default). The description adds no parameter-level detail; the baseline 3 is appropriate when the schema does all the work.

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

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

States a specific verb+resource ('Rename the project') and names the exact surfaces affected (project list, editor top bar). It is immediately distinguishable from siblings such as createProject, listProjects, or setEditorSettings.

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

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

Usage is implied by the verb: use this to rename a project. There is no explicit when-to-use/when-not or reference to an alternative tool, though for a single-purpose rename tool there is little ambiguity to resolve.

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 and destructive=false, so the safety profile is covered. The description adds a genuinely useful behavioral trait beyond annotations: 'Only the fields you pass are changed' discloses partial-patch update semantics, which an agent could not derive from the annotations alone.

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

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

Two tight sentences, no waste, with the core action and the patch-semantics caveat both front-loaded.

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

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

For a 5-parameter mutation tool with 20% schema coverage and no output schema, the description covers the essential patch behavior and time units but omits the speed multiplier bounds and the projectId/openProject dependency, leaving real 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 low at 20% (only projectId is documented). The description compensates partially by clarifying 'multiplier' for the speed field and noting virtual-timeline seconds for the time fields, but leaves the speed range and id/project scoping largely 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?

States a concrete verb set (move, resize, change multiplier) applied to a specific resource (an existing speed region) identified by id. 'Existing' implicitly distinguishes it from the sibling addSpeed, though no sibling is named explicitly.

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

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

The phrase 'by id' plus 'existing speed region' implies this is the update path rather than the create path (addSpeed), but the description never states when/when-not to use it or names the alternative. Usage 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 only say non-readOnly, non-destructive, non-openWorld; the description goes far beyond that. It discloses that the cut follows to whichever clip the new range lands in 'when that clip is unambiguous', that a chained-zoom camera pan lasts 1 s, and that the operation emits a cutTransitions warning where 'nothing is refused', which is exactly the kind of consequence detail an agent needs for a 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?

The core purpose is correctly front-loaded, but the body is a dense wall of timing math, including a six-entry renderedScale example list (0.72 s at 1.25× … 1.49 s at 5.00×) that is far more detail than a tool description needs. Signal is real but 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?

No output schema exists, yet the description explains the returned cutTransitions shape (which zoom, which side, cutSec, lost seconds, by: trim/junction), and references getCurrentDocument for zoomInFromSec/zoomOutUntilSec. That covers nearly everything an agent needs to call and interpret the result correctly.

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

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

Schema coverage is only 25% (just projectId documented), so the description must compensate. It does add the critical unit for the two undocumented numerics ('Times are source-time seconds') and ties trimRangeId to 'by id', though it never clarifies ordering/constraints between startSec and endSec or the id's format.

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

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

States a specific verb pair (move or resize) on a specific resource (an existing trim range) addressed by id. The word 'existing' implicitly distinguishes it from the sibling creators addTrim/addTrims and the remover removeTrim, so an agent can place it 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?

Usage is implied by 'existing trim range' (i.e., not for creating or deleting) and there is operational guidance ('leave the windows untrimmed', 'move the cut or the zoom unless a hard cut is what you want'). However, no sibling is named as an explicit alternative and there are no stated preconditions, so the routing is inferred 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 mark this as a non-destructive mutation (readOnlyHint=false, destructiveHint=false), so the safety profile is covered. The description adds real behavioral context: the 600-character cap, that empty string clears it, and that it does not retroactively change transcripts. Auth/permission behavior is not mentioned, keeping it short of a 5.

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

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

Front-loaded with the core action and effect, followed by constraint and clearing semantics. Dense but each sentence carries a distinct fact; the final cross-reference to getCurrentDocument is a useful pointer rather than filler.

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

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

For a mutation tool with no output schema, the definition covers the actionable facts: format, limit, clearing behavior, and non-retroactivity. It leaves only permission/auth details and response shape unstated, which are minor given the annotations and lack of an output schema.

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

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

Schema coverage is only 50% (projectId documented, vocabulary bare), so the description must compensate, and it does: it explains that vocabulary is read as a plain list, gives an example ("OpenScreen, Vulkan, whisper.cpp"), and states the 600-char limit and empty-string semantics. projectId semantics are already carried 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 (set) and resource (project vocabulary) plus the exact effect: what Whisper is primed with on every transcription of this project. An agent can distinguish this from getCurrentDocument and transcribe at a glance.

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

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

Explicitly tells the agent that an empty string clears the vocabulary and that existing transcripts are unaffected, directing it to re-run transcribe for that. It names the relevant siblings (transcribe, getCurrentDocument) but does not spell out when to prefer this over alternatives or any prerequisites.

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

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

Beyond the annotations (which only mark it as a non-readonly, non-open-world, non-destructive write), the description discloses what is mutated (transcript + captions, not film or audio), that an empty string blanks rather than deletes the word, and that restoring the original text clears 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?

It opens with the core action and scope before branching into edge cases and the contrast with removeWords. Every sentence carries distinct information, though the final removeWords contrast is slightly convoluted and adds 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?

No output schema exists, so the description appropriately covers the mutation semantics; with 4 params it covers text and wordId well and relies on the schema for projectId, but assetId's role is never addressed.

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

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

Schema coverage is only 25% (only projectId documented), so the description must carry the rest. It richly defines the `text` parameter (empty = blank, original = clear) and points to getTranscriptWords as the source of wordId, but assetId is left completely 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?

States a specific verb and resource ('Correct ONE word's text') with a precise scope ('This changes the TRANSCRIPT and nothing else'), and explicitly distinguishes itself from removeWords. An agent can select it correctly without opening the schema.

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

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

Gives an explicit when ('Use it when the transcriber misheard something — a name, a technical term'), a when-not ('This is NOT how you make a spoken word go away'), and names the alternative (removeWords) with the reason it differs (it cuts audio).

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 covering only the safety profile (readOnly false, destructive false, openWorld false), the description carries the rest and does so heavily: only passed fields change, customScale is cleared when depth is passed, refusals name the clip limit, the result's renderedScale/cursorAnchor/cutTransitions are explained, and animation/chaining timing is specified. Far exceeds 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?

Front-loaded correctly with the core action in sentence one, but the body is a dense multi-topic wall covering animation formulas, speed-region scaling, chaining pan timing, and warnings. Much of it is useful, yet the arithmetic tables and timing constants over-supply what an agent needs at selection time.

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, so the description must describe returns — and it does, itemizing renderedScale, cursorAnchor, the depth-clearing notice, and cutTransitions fields. For a 10-parameter mutation tool with only one required param, nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is only 20%, and the description compensates: it spells out the full depth→scale table (1=1.25× … 6=5.00×), defines focusMode manual vs auto, hideCursor, customScale's 1–5 rounding and refusal case, and all four rotationPreset values. Only the focus object's cx/cy coordinates and startSec/endSec semantics are left thin.

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?

Opens with a precise verb triple and resource: 'Move, resize, or restyle an existing zoom by id (virtual-timeline seconds).' The word 'existing' implicitly separates it from the sibling addZoom/create tools, and the modifier scope is stated immediately.

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 guidance for individual features: rotationPreset is 'for a reveal or a key moment, not every zoom'; leave the hold windows untrimmed; 'Pass depth or customScale, not both.' It never explicitly names addZoom/addAutoZooms as the alternatives for creating zooms, so sibling routing must be 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?

Annotations only declare the generic non-read-only, non-destructive, closed-world profile. The description adds real behavior: capture starts asynchronously on return, pointer is recorded as data by default so exports draw a clean cursor and zooms, webcam becomes picture-in-picture, icon hiding follows the user's Record mode setting, and Linux delegates source choice to the OS picker. It omits error/permission behavior, keeping it short of a 5.

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

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

Front-loads the core action and target in the first clause, then layers workflow and behavioral detail. Four sentences with no filler, though the webcam/icons/Linux sentences are informative rather than essential to invoking the tool.

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

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

With no output schema, the description correctly states the return behavior ('Returns once capture has started') and explains the follow-up action. Combined with a fully documented 6-parameter schema and annotations, an agent has enough to call it correctly; only error/failure handling is unaddressed.

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

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

Schema description coverage is 100%, with cursor defaults, window-over-display precedence, and display indexing all documented in the schema, so the baseline is 3. The description's only added semantic is the preference note that window capture avoids capturing anything else on the desktop – useful, but marginal against a fully documented 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 ('Start recording one window ... or one display') and immediately scopes the target. An agent can distinguish it from stopRecording and listSources without opening any schema.

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

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

Gives the workflow explicitly: 'Returns once capture has started; then drive the app and call stopRecording', naming the sibling to call next. It also flags the Linux picker dependency. It does not state when-not-to-use, but there is effectively no competing start-recording tool, so guidance is clear.

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

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

Annotations only declare readOnly=false, destructive=false, openWorld=false, so the description carries the interesting load and does so well: it explains that the take plus recorded clicks become one clip with planned zooms, that clicks merge into shared zooms, that early/stopping clicks get none, and that autoZooms controls the count. It stops short of stating preconditions (must a recording be active?) or side effects on the recording state afterward.

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

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

Purpose is front-loaded in the first clause and every subsequent sentence carries real information about zoom planning or return values. It is somewhat dense and clause-heavy, which slightly impedes scanning, but there is no filler.

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

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

With no output schema, the description usefully enumerates the return values (projectId to edit, checkpointId restoring the raw take, videoPath). Combined with the zoom-planning detail, an agent has enough to call and interpret it, though error/precondition behavior is unaddressed.

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

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

Only one parameter (title) and the schema already documents it at 100% coverage, so the baseline is 3. The description mentions the new project but never connects it to the title argument, adding no 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?

States a specific verb and resource ('Stop the recording and turn the take into a new project'), and the remainder of the sentence specifies the exact layout semantics of the produced project. This clearly separates it from startRecording and createProject in the sibling list.

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 rather than stated: the reader infers this is for ending an in-progress recording. There is no explicit when-not condition (e.g. what happens if no recording is active) and no named alternative such as createProject when the user wants a project without a take.

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