Launchscene

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

Annotations declare readOnlyHint=true and idempotentHint=true, so the description's job is to explain what the transform actually does and whether anything is persisted. Instead, 'Substitute all source copy' reads like a mutation of the stored scene, and the text never says whether the adapted scene is returned-only or saved; the caveat about extrapolation is too cryptic to resolve that, so real ambiguity remains despite 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?

Two sentences with the action front-loaded, so it is reasonably tight. However, the second sentence is an unexplained warning ('mid-presence boxes are not trajectories') that consumes space without conveying actionable meaning to an unfamiliar agent.

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

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

An output schema exists, so return-value detail is not required, but for a four-parameter transform with zero schema coverage the description should at least anchor each input's meaning and state whether the source scene is modified. Neither gap is closed, so an agent could call it correctly only by guessing.

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

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

Schema description coverage is 0%, yet the description never maps to the four parameters: it does not explain that 'texts' is an ordered list capped at 32 entries of 500 chars, how 'aspect' (16:9 vs 9:16) interacts with the reflow claim, or what 'duration_ms' does to 'recalculate cadence'. Only a loose thematic hint is offered, leaving the schema's constraints to speak for themselves.

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 first clause gives a specific verb and resource: replacing a scene's source copy with supplied text, plus re-timing/reflowing it. That is concrete enough to distinguish it from read-only siblings like get_text_track or get_scene, though the second sentence ('source mid-presence boxes are not trajectories') is domain jargon that does not sharpen the purpose.

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

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

There is no statement of when to use this versus alternatives (e.g., get_scene to inspect, suggest_correction to propose changes) and no prerequisites such as where scene_id comes from. The agent must infer usage entirely from the imperative 'Substitute all source copy with your text'.

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

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

Annotations already cover readOnly, idempotent, non-destructive, closed-world. The description adds genuine behavioral context beyond them: the grid is 'synthetic' (not derived from audio), constant-tempo, and snapping 'preserves exact start/end'. It doesn't explain what the snapping does when a cut is far from a beat.

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 dense sentences with the core operation front-loaded and the caveat second. No filler, though the phrasing is compressed enough that 'preserving exact start/end' takes a second read.

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

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

For a tool whose schema includes a deeply nested structure/scene model and 7 parameters, the description explains almost none of it; the structure object's purpose is never mentioned. An output schema exists so return values needn't be described, but the input side is substantially incomplete.

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

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

Schema description coverage is 0% across 7 parameters, including a large nested `structure` object with scenes, roles, palettes and transitions. The description only explains phase and bpm; beats_per_bar, cut_every_beats, cuts_ms and the entire structure object are left undocumented, so it fails to compensate for the coverage gap.

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

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

States a specific verb and resource: 'Calculate a synthetic constant-tempo beat/downbeat grid and snap proposed cut times'. The second sentence adds a distinguishing constraint (supply phase explicitly). No direct sibling competes, but it doesn't contrast with get_audio_map, which handles real audio timing.

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?

'Supply phase explicitly; BPM alone cannot recover an audio file's real timing' implies the alternative (real audio analysis) without naming it. There is no explicit when-to-use/when-not statement or pointer to a sibling tool.

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

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

Annotations already declare readOnly, idempotent, closed-world, non-destructive, so the safety profile is covered. The description usefully adds that results are video-weighted and that the tool will not silently broaden filters — a meaningful behavioral guarantee. However, it omits the hard constraint that min_videos defaults to 8 (minimum 8), which materially affects whether a call can succeed.

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

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

A single dense sentence with the method and the scope caveats front-loaded, no filler. It is arguably over-compressed, but nothing written is wasted.

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

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

For a tool with nested filter objects, zero schema description coverage and a minimum-sample gate, the description leaves out the mechanics an agent needs: what a group filter accepts, whether groups must be disjoint, and the min_videos requirement. The presence of an output schema excuses explaining return values, but not the input and precondition gaps.

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

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

Schema description coverage is 0% against 5 parameters, two of which are 9-field nested filter objects, yet the description explains none of them. It never says group_a/group_b are filter objects, never mentions the role scoping, the max-5 metrics list, or the minimum video count per group, so an agent must reverse-engineer semantics from enum names 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?

States a specific verb (compare) and resource (two explicit groups) plus the method (video-weighted distributions) and the output emphasis (reports overlap). It implicitly distinguishes itself from compare_to_reference by insisting the groups are 'explicit', but never names that sibling or any other, so differentiation is left to inference.

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

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

The clause 'no causal claims, quality scores or silent broadening' constrains what the tool will not do, not when to call it. There is no statement of when this should be preferred over compare_to_reference, corpus_stats, trends, or typical_structure, all of which sit in adjacent territory.

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, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds real behavioral meaning beyond that: alignment is order-preserving and insertions/deletions remain explicit rather than being force-matched, which shapes how results should be read. It stops short of describing output shape or limits, but the output schema covers returns.

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

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

Two tight sentences with no filler, and the core operation is front-loaded before the alignment caveat. 'Order-preserving narrative-role alignment' is dense jargon but is a genuine specification rather than 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?

The output schema means return values needn't be explained, and annotations cover safety. However, for a two-argument tool whose plan object has a dozen optional per-scene fields including reference_scene_id, the description leaves the agent without guidance on what 'reference' means concretely or how to choose among 30+ 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 0% on a deeply nested plan object with per-scene fields (role, reference_scene_id, duration_ms, etc.), and the description adds no parameter detail at all. Worse, it calls the second input a 'reference' while the schema names it 'video', leaving the mapping between the prose and the actual argument ambiguous.

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 (compare) and both resources (a plan, one chosen reference), plus the alignment mechanism. The phrase 'one chosen reference' implicitly separates it from the plural comparison offered by compare_groups, though that sibling is never named.

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 this is appropriate ('one chosen reference'), which hints at a contrast with compare_groups, but it never states that contrast explicitly or gives any when-not guidance. The agent must infer the routing decision from the sibling list.

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, idempotent, non-destructive, closed-world behavior, so the bar is lower; the description still adds real context the annotations cannot: equal weighting per video, missing measurements remaining unknown rather than imputed, and cited median/extreme examples. The one behavioral lever it omits is allow_broaden, whose effect on the result set is never 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?

Two dense sentences with no filler, and the statistical contract (dispersion, median/extremes) is front-loaded. The compression occasionally costs clarity, but nothing is redundant.

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

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

The presence of an output schema excuses it from explaining return values, but a five-parameter tool with a nested ten-field filter object and a zero-coverage schema needs far more. The absence of any explanation of allow_broaden or of how role and metric interact leaves an agent unable to call this correctly without guessing.

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

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

Schema description coverage is 0% across five parameters, including a nested filters object with ten fields, so the description must carry the burden and does not. It never mentions role, metric, the filter dimensions, or min_videos, and allow_broaden — the parameter most likely to change results unexpectedly — is left entirely 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 description conveys that the tool produces aggregate statistical summaries (dispersion, median, extremes) for a chosen metric across the corpus, which is more than the title alone. However, the verb 'describe' is vague and the phrasing is compressed enough that the core action (compute corpus-level statistics for a metric) must be inferred. No sibling is named, despite near-neighbors like compare_groups, trends, and typical_structure.

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 versus compare_groups, compare_to_reference, trends, or typical_structure, all of which operate on aggregate corpus data. The eight-video minimum implies a sample-size prerequisite but is stated as an output rule rather than a usage condition, and no exclusions or alternatives are offered.

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 establish read-only, idempotent, non-destructive behavior, and the description adds the genuinely differentiating traits: it asks questions instead of assigning severity or a quality score, and returns unknown when the comparison is sparse. That tells an agent how to interpret and present results in a way the annotations cannot. It omits what happens when the corpus is broadened via allow_broaden or below min_videos, 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?

Three short front-loaded sentences with no filler, and the core comparison is stated first. However, for a tool with a nested required plan object and three additional parameters, this brevity crosses into under-specification rather than tight editing. The final sentence is clipped to the point of being cryptic.

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

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

An output schema exists, so return values needn't be described, but the description leaves major gaps for a complex input: the meaning of allow_broaden, the role of min_videos, how filters weight the corpus, and what constitutes a usable plan are all unstated. Given zero schema description coverage and nested objects, more guidance is required for an agent to invoke this correctly.

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

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

Schema description coverage is 0% across four parameters, including a deeply nested plan object with scenes and a nine-field filters object, so the description must compensate and largely doesn't. 'Video-weighted corpus distributions' and 'sparse comparisons remain unknown' hint obliquely that filters narrow the corpus and that low sample counts trigger unknown results, which indirectly gestures at min_videos. Nothing explains allow_broaden, bpm, aspect, or how filters like tone and industry weight the comparison.

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 first sentence names a concrete operation, comparing storyboard durations and pacing against video-weighted corpus distributions, which is more specific than a restated title. It does not distinguish itself from nearby siblings such as plan_structure, typical_structure, or compare_to_reference, so an agent can't route between them from the text alone. The verb 'contextualize' is also jargon-heavy, but the resource and comparison target are clear.

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

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

'Asks questions, never assigns severity or a quality score' describes output behavior rather than when to call the tool. There is no statement of prerequisites, when to prefer plan_structure or compare_to_reference, or what input conditions make the tool appropriate. Usage is only inferable from the verb 'critique' in the name.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered; the description adds substantive context beyond that: no footage or logos in the output, unknowns remain adjustable, and generated code is not render-tested. That last warning is exactly the kind of caveat an agent needs before acting on the result.

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 lead sentence followed by two short constraint clauses, with the core purpose front-loaded. The target list is long but each item is load-bearing since the enum is otherwise undocumented.

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

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

An output schema exists, so return-value explanation is rightly omitted, and the framework list plus input-path framing is helpful for a deeply nested schema. However, with six parameters, nested objects, and zero schema descriptions, the description leaves too much of the input contract unexplained for a tool this complex.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning, and it only partly does: it maps the 'target' enum values by naming the six frameworks and gestures at 'recipe' vs 'texts'. scene_id, aspect, and duration_ms get no mention, leaving half the surface undocumented anywhere.

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 ('Generate editable starter source') and enumerates the exact output flavors (Remotion TSX, HyperFrames HTML, CSS, GSAP, lottie-web JSON, After Effects JSX), which no sibling tool does. It doesn't name a sibling to contrast with, so it stops just short of a 5.

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

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

The phrase 'from an adapted recipe, or a reference plus mandatory replacement text' implies the two valid input paths and suggests adapt_scene/reference_brief come first, but it never states that explicitly or names alternatives. 'No source footage/logos' is a useful scope exclusion, though it describes output content rather than when to call the tool.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds real behavioural facts beyond them: similarity is precomputed, results are filtered to published and reviewed scenes only, and signed images attach to the first 12 results. Gaps remain on pagination behaviour and what exclude_brand does.

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 what the tool returns, no filler or repetition of the title.

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

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

An output schema exists, so return shape need not be explained, and the catalogue filtering is covered. But for a 6-parameter tool with zero required parameters, the agent is left without knowing whether to supply `id` or `scene_id` or how to paginate, which is a material omission.

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

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

Schema description coverage is only 17% (only `images` is documented), so the description must compensate and does so only partially: it explains the 12-result default-adjacent image behaviour. It says nothing about `cursor`, `limit` up to 50, `exclude_brand`, or the ambiguous pair of `id` and `scene_id` (identical patterns, neither required).

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

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

Specific verb-and-resource: returns scenes that look like a chosen scene, sourced from precomputed visual similarity and restricted to the published/reviewed catalogue. That clearly separates it from text-oriented siblings like search_scenes or search_by_moment, 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?

'Scenes that look like a chosen one' implies the trigger (you have a scene and want visually similar ones), but there are no explicit when-to-use/when-not rules and no named alternatives (pattern_search, compare_to_reference, search_scenes) to route between.

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, idempotent and non-destructive, so safety is covered; the description adds genuine domain behavior the annotations cannot: output is vendor-neutral, overlay text is kept separate from generated imagery, and reference links are preserved when present. It stops short of stating what happens on malformed or incomplete plans.

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 sentence with zero filler; the core transformation is front-loaded and the two preservation guarantees follow. It is slightly crammed, but every clause carries information an agent can 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?

An output schema exists, so return values need not be described. However, for a single nested-parameter tool with 0% schema coverage, the description does not explain the plan structure or the output's intended downstream use beyond 'vendor-neutral', leaving a substantive gap for correct invocation.

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

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

Schema description coverage is 0% on a deeply nested single parameter (scenes with role/camera/transition enums, palette, durations). The description implicitly maps to 'text' (user overlay text) and 'reference_scene_id' (reference links) and confirms the input is a full plan object, but leaves roles, timing, and transition semantics undocumented.

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

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

States a specific verb and output artifact: turn a supplied structure into vendor-neutral shot briefs. 'Vendor-neutral' and 'shot briefs' implicitly differentiate it from siblings like critique_plan or reference_brief, but no sibling is named or explicitly excluded.

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 'a supplied structure' hints that a plan must already exist, but there is no explicit when-to-use, no prerequisites, and no statement of when to prefer plan_structure, adapt_scene, or reference_brief instead. The agent must infer its place in the pipeline.

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 establish that this is a safe, read-only, idempotent operation. The description adds useful behavioral context beyond annotations: events are paginated and numerical sound levels are measurements rather than music files, which clarifies interpretation of returned data.

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

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

The description is two tight sentences, front-loaded with the core action and scope. Every clause adds useful information about content, pagination, and interpretation of sound-level data.

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

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

The tool has an output schema, so return values need not be fully described, and the annotations cover safety. However, with seven optional parameters and low schema description coverage, the definition leaves important parameter relationships and usage selection unclear.

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 29%, so the description should compensate for undocumented parameters. It implies the start/end window and pagination via cursor/limit, but it does not explain slug, video_slug, scene_id, or how the window relates to those identifiers.

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

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

The description gives a specific verb and resource: it reads chronological audio events, sections, and bounded samples in a window. It clearly distinguishes the content from a generic metadata lookup, but it does not mention any sibling tool or alternative, so sibling differentiation is absent.

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 explains what can be read and that events are paginated, but it gives no explicit guidance on when to use this tool rather than siblings such as beat_grid or get_scene. There are no exclusions, prerequisites, or selection criteria beyond the implied retrieval use case.

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, idempotentHint=true, and non-destructive behavior. The description adds useful context beyond annotations by disclosing that results are paginated and that the payload includes launch references plus style/video counts.

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

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

The definition is a single front-loaded sentence with no filler. It is dense but appropriately sized, though some terms remain undefined 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?

An output schema exists, so detailed return-value explanation is not required. However, with 0% schema description coverage and no sibling differentiation, the description is only minimally sufficient for correct invocation.

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

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

Schema description coverage is 0%, so the description must compensate for three undocumented parameters. It only mentions 'paginated', which hints at limit/cursor, but does not explain slug format, cursor usage, limit defaults, or bounds.

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

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

The description uses a clear verb ('Read') and resource ('a brand') and specifies the content returned: paginated launch references, descriptive style counts, and distinct-video counts. It is specific enough to distinguish a single-brand read from list_brands, though it does not name that sibling or clarify the jargon 'launch references.'

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 list_brands or other sibling tools, nor any prerequisites or exclusions. The description implies a lookup by brand, but offers no decision criteria.

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 safety (readOnly, idempotent, non-destructive, closed-world), so the description correctly spends its budget on semantics instead: units for zoom (scale ratios) versus pan/direction (fractions of image width), the heuristic nature of easing classification, and the caveat that clipping does not remeasure amplitude. That last note is genuinely useful behavioral context an agent could otherwise misread as a data-quality bug.

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

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

Four short, dense sentences with no filler, and the core action is front-loaded. Efficient, though the ordering puts measurement units ahead of any indication of what a caller must provide.

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 seven-parameter tool with three competing scope identifiers (slug, video_slug, scene_id) and zero required parameters, the description never explains how to scope a call or what happens if you scope by none, by several, or by an unknown slug. An output schema exists, so return values needn't be explained, but the invocation surface is left largely undocumented.

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

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

Schema description coverage is only 29% and the description adds nothing about the parameters — not which of slug/video_slug/scene_id scopes what, not the meaning of limit/cursor pagination, and not the relationship between the inclusive start_ms and exclusive end_ms (the schema covers those two but nothing ties them to a video). With seven params and a third documented, the description needed to compensate and does not.

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 first sentence gives a specific verb and resource: 'Read measured camera movement intervals,' which tells an agent exactly what data comes back. It does not, however, contrast itself with siblings like get_text_track, get_audio_map, or get_frames, so the agent must infer the choice from names alone.

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

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

There is no statement of when to call this versus the parallel track tools (get_text_track, get_audio_map, get_frames) or the scene/video lookups. The description only characterizes the payload, never the selection conditions.

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

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

Annotations already declare read-only, idempotent, non-destructive, so the safety bar is low; the description still adds real behavior: a hard cap of twelve URLs versus four inline images, scene-relative array times, and the invariant that requested and actual image times are separate. The overlay-precompute requirement is genuine call-affecting context that 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?

Four short sentences with the output shapes front-loaded, no filler. Slight deduction for the telegraphic 'Requested and actual image times are always separate', which is compressed to the point of ambiguity about what the agent should pass.

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

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

An output schema exists, so return-value explanation is rightly omitted, but with six undocumented parameters and zero required fields the description leaves a real gap: it never says whether `id` or `scene_id` (or neither) is needed, which is the main risk of a misinvocation.

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

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

Schema description coverage is 0% across six parameters, so the description has to compensate and only partly does: it clarifies `limit`/`inline` via the twelve-vs-four bound, `at` via scene-relative times, and `overlay` via the precomputed-image rule. It says nothing about `id` versus `scene_id`, which selector to use, or what the 'key'/'transition_in'/'transition_out' enum values mean.

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 (get reference frames) and quantifies both output modes: up to twelve URLs or four bounded inline images. An agent can distinguish this from get_video/get_scene by the frame-level granularity, 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?

There is no when-to-use or when-not-to-use guidance, and no alternative is named. The overlay sentence is a constraint, not routing advice, and the many sibling tools (get_text_track, get_scene, get_camera_track) are not distinguished.

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, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description contributes context beyond them by scoping results to the account and disclosing what is deliberately withheld (private briefs, credentials), which is exactly the kind of behavioral detail annotations can't 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?

A single sentence with the scope and exclusions front-loaded and no filler. Every clause (account scope, contents, withheld data) 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?

An output schema exists, so return-value explanation isn't needed, and the privacy boundary is well covered. However, the pagination contract (limit/cursor) is the main thing an agent must get right to call this correctly, and it is 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 0%, so the description carries the full burden for 'limit' and 'cursor' — and it says nothing about them. It doesn't explain that results are paginated, what limit defaults to (10), or how to page with cursor, leaving both parameters opaque beyond their bare types.

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

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

States a specific verb ('Read'), resource ('this account's recent MCP activity'), and enumerates the content ('operations and consulted scene IDs'), which lets an agent distinguish it from data-fetching siblings like get_scene or search_scenes. It stops short of naming an alternative, but no sibling overlaps this retrieval role.

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 'recent activity' — an agent can infer this is for auditing prior operations — but there is no explicit when-to-use, when-not-to-use, or pointer to a sibling for related needs (e.g. detail lookup via get_scene).

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, idempotent, non-destructive and closed-world, so the safety bar is low. The description earns credit beyond that by disclosing the actual payload content: timing, OCR box meaning, heuristic motion measurements, source provenance, verification and missing-data reasons — useful detail about what the read returns.

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

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

Two tight sentences, front-loaded with the verb and resource forms. No filler; the second sentence wastes nothing in listing recipe contents.

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

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

An output schema exists, so return shape need not be described. But for a tool with zero schema description coverage and two identifier parameters, the description leaves a real ambiguity (id vs scene_id) unresolved, so it is not quite complete enough for confident 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 0%, so the description has to carry parameter meaning. It does map the three `depth` values to distinct content (card/sheet/recipe), which is genuinely helpful. However, it says nothing about the distinction between `id` and `scene_id`, two overlapping identifier parameters left entirely 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 (read) and names the three concrete resource forms (card, annotated sheet, measured recipe), which maps onto the `depth` enum. It does not explicitly say it retrieves a single scene or contrast itself with the singular sibling get_scenes, but the resource is unambiguous.

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

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

Usage is only implied: the enumeration of what each depth returns hints at which variant to pick, but there is no explicit when-to-use or when-to-prefer-get_scenes/search_scenes guidance. The agent must infer the selection logic from the content list.

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, idempotent, non-destructive safety, so the description correctly focuses on what they cannot express: the 6-item cap, the tighter 3-item cap for recipe depth, and that unavailable/private scenes collapse to a generic error. The generic-error disclosure is genuinely useful because it warns the agent it cannot distinguish 'not found' from 'forbidden'.

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, with the primary action and scope front-loaded before the batch limits and the error-behavior caveat.

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

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

An output schema exists so return values need not be described, and the safety profile is annotated. The remaining gap is the unexplained depth enum, but for a two-parameter read tool the definition is otherwise complete enough to call correctly.

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

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

Schema description coverage is 0%, so the description must carry the load. It partially does by restating the six-item ceiling and tying 'recipe batches' to the depth enum's recipe value, but the card/sheet/recipe depth levels and their effect on output are never explained, leaving the only meaningful parameter semantics to guesswork.

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

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

States a specific verb (read) and resource (scene references) plus the batch-and-compare semantics, which separates it from the singular get_scene sibling by implication. It never names the sibling outright, so differentiation requires a small inference.

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

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

'for comparison' and 'Recipe batches are limited to three' imply the multi-scene comparison use case and one hard constraint, but there is no explicit when-to-use vs get_scene / search_scenes guidance or statement of when a single fetch is preferable.

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, idempotent, non-destructive behavior, so the description earns credit for adding context beyond that: pagination, that boxes stay attached to their original observation, and that old exports only permit an estimated box timestamp. Those are genuine data-quality caveats an agent would not otherwise know.

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

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

Two sentences, both load-bearing, with the core capability front-loaded ahead of the caveats. The trailing clauses about box timestamps are dense and slightly cryptic, but nothing is 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?

An output schema exists, so return-value explanation is rightly omitted. However, with 7 optional parameters and no required ones, an agent needs to know which identifier must be supplied (slug, video_slug, or scene_id) and how the scoping works together; the description leaves that inference to the schema.

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

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

Only 29% of parameters carry schema descriptions, so the description must compensate. It does partially: 'video window' maps onto start_ms/end_ms and 'scene' onto scene_id. But it never clarifies the slug vs video_slug vs scene_id relationship, nor limit/cursor semantics, which leaves the three identifier parameters ambiguous.

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: 'Read paginated OCR text intervals', and scopes it to 'a video window or a scene'. This tells an agent exactly what is returned and the two possible scopes. It stops short of distinguishing itself from siblings such as get_transcript or get_scene, but the purpose itself is unambiguous.

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

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

'Clipped to a video window or a scene' implies the choice of scope but never states when to pick each, nor when to prefer this over get_transcript or search_by_moment. Usage is inferable from the scope wording, not 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 readOnly, idempotent, non-destructive and closed-world, so safety needs no restating. The description adds one genuinely useful behavioral caveat — segment clipping does not imply word-level alignment — which warns about timestamp precision. It is silent on pagination behavior despite having limit/cursor parameters.

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

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

Two tightly written sentences with the operation front-loaded and zero filler. The precision caveat is dense but earns its place; it could be slightly clearer about what 'segment clipping' refers to.

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

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

The output schema covers return values, so that is not a gap. But a 7-parameter tool with zero required parameters and three competing identifier fields needs the description to explain selection and pagination, and it does neither — an agent could not reliably construct a call from this text alone.

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 29% (just start_ms and end_ms are documented, and only as inclusive/exclusive), so the description must carry weight and does not. Seven parameters including slug, video_slug, scene_id, limit and cursor are unexplained, and the description never clarifies the relationship between the three identifier parameters or how to paginate.

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 timestamped voice transcript segments) plus a scoping mode (video window or scene). It does not distinguish itself from adjacent siblings such as get_text_track or get_audio_map, so an agent can't tell which to pick on name 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?

No when-to-use or when-not-to-use guidance, and no mention of the alternatives (get_text_track, get_audio_map) an agent would weigh against it. The phrase 'video window or scene' hints at two access modes but never says how to choose between 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 already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description still adds real behavioral context: results are limited to published/reviewed videos and media assets are never exported, which tells the agent what it will and will not get back. It stops short of describing pagination behavior or the shape of the summary.

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 waste. The positive payload description comes first and the negative constraint (no media export) follows, which is the right ordering for an agent scanning for capability.

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

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

The presence of an output schema means return values need not be spelled out, and the media-export exclusion is a helpful boundary. But with 0% schema description coverage across three parameters, the definition leaves the agent guessing about slug semantics and page-size defaults — gaps the description should have closed.

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

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

Schema description coverage is 0%, so the description carries the burden, and it only partially does: "paginated" hints at the limit/cursor pair but never explains their interaction or the default page size. The required slug parameter — arguably a video identifier versus a board or brand slug — is never characterized in the description at all.

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

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

States a specific verb ("Read") and enumerates the exact resources returned: summary, style measurements, and paginated scene cards. That is more precise than the title alone. It does not, however, explicitly differentiate itself from close siblings like get_video_structure, get_scene, or get_scenes, which an agent must infer.

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

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

"published, reviewed" implies a precondition — only videos in that state are readable — but it is stated as a property of the payload rather than as a rule for when to call this versus a sibling. No alternative is named, and there is no guidance on what to do when a video is not yet published or reviewed.

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, idempotent, non-destructive, and closed-world, so safety is covered. The description adds one genuinely new behavioral fact — that absent precomputed data is explicitly surfaced rather than silently computed — but says nothing about whether it computes on demand, staleness, or pagination behavior.

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

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

Two tight sentences with the primary content enumeration front-loaded and no filler. The compressed list of returned facets is terse to the point of being slightly cryptic, but every clause carries information.

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

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

An output schema exists, so return values needn't be described, but for a three-parameter paginated tool with zero schema description coverage the definition leaves the agent guessing about slug semantics and pagination. Combined with no guidance against a large sibling set, it is under-specified for its complexity.

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

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

Schema description coverage is 0% across three parameters, so the description carries the full burden and adds no meaning. Nothing explains the slug format, what 'limit' bounds (12 default, max 50), or how 'cursor' paging interacts with the precomputed strip.

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

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

The description names the resource concretely (narrative sequences, durations, audio arc, voice, CTA, whole-video sync) and uses an explicit read verb, so an agent knows it returns a precomputed structural analysis. It does not differentiate itself from close siblings like get_video, get_audio_map, typical_structure, or plan_structure, leaving overlap ambiguous.

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

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

There is no statement of when to call this versus alternatives such as get_video, get_scenes, or typical_structure, nor any prerequisites. The only usage-adjacent signal is the note that a missing precomputed strip is reported, which hints at a failure mode rather than guiding tool selection.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds useful scope context ('private boards', 'bounded set of currently published scene references'), but it does not explain pagination behavior or how the bounded set is determined, and 'bounded' remains vague.

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

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

The description is a single front-loaded sentence with no filler, which is appropriate. The phrase 'bounded set' is somewhat vague, but overall it is efficiently structured.

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

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

An output schema exists and annotations cover safety/idempotency, but the description leaves major gaps for a four-parameter listing tool. With 0% schema coverage, an agent cannot determine how cursor-based pagination works, what board_id filters, or how limit differs from items_limit.

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

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

Schema description coverage is 0%, so the description must compensate for four undocumented parameters. It does not mention limit, cursor, board_id, or items_limit at all, leaving an agent with no semantic guidance for any parameter.

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

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

States a specific verb ('List') and resources (private boards plus currently published scene references), which is clearer than a generic list tool. It does not explicitly differentiate from siblings such as list_brands, get_scenes, or search_scenes, so it falls short of a 5.

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

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

The description gives no guidance on when to use this tool versus alternatives like list_brands, get_scenes, search_scenes, or save_to_board. There are no exclusions, prerequisites, or selection criteria beyond the bare purpose.

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, idempotent, non-destructive, and closed-world, so safety is covered. The description adds one genuinely new fact — that brand media/logos are excluded from results — which helps set expectations, but it says nothing about result volume, ordering, or the cursor-based pagination implied by the schema.

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

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

Two short, front-loaded sentences with no filler. Its brevity is appropriate, though the second sentence's exclusion note comes before more essential filtering/pagination information that is absent.

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

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

An output schema exists, so return shape needn't be described, but this is a 4-parameter searchable, paginated list tool and the description explains none of its filtering, paging, or ordering behavior. Undocumented parameters at 0% schema coverage leave the agent guessing.

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

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

Schema description coverage is 0% for four parameters (limit, query, cursor, industry), so the description carries the full burden — yet it never mentions filtering by query or industry, the default page size of 12, the max of 50, or how the cursor is used. It fails to compensate for the coverage gap.

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

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

Clear verb+resource: 'List brands', with a scoping qualifier about published, reviewed references and an explicit exclusion of logos/media. However, the qualifier is ambiguous (does 'published, reviewed' describe the references or the brands?) and it never distinguishes this from the sibling get_brand, which presumably fetches a single brand.

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

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

No indication of when to use this instead of get_brand, find_similar, or search tools, and no prerequisites or exclusions stated. The agent must infer from the name alone that this is the enumeration entry point.

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 safety (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description still adds genuinely non-obvious context: the output separates proposed impacts from measured references, and it explicitly confirms no audio is produced. It says nothing about how corpus widening behaves, which is a remaining gap.

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

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

Two dense sentences, front-loaded with the verb and artifact, then output composition, then the epistemic caveat. No filler and nothing restated from the title.

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

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

An output schema exists, so return values needn't be explained, and the description conveys the artifact's nature well. But for a tool with four parameters, nested objects, and zero schema descriptions, leaving filters and allow_broaden entirely unexplained is a real completeness 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 0% and the schema is deeply nested, so the description must compensate. It only covers the required `plan` argument in passing and never mentions `filters`, `min_videos`, or `allow_broaden` — the last being a consequential corpus-widening switch an agent cannot infer.

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 artifact ("Build a musical brief from a plan") plus what the brief contains (corpus BPM/voice-bed distributions, timed energy arc). This clearly distinguishes it from data-returning siblings like corpus_stats or plan_structure, though it never names them explicitly.

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

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

Usage is only implied: "from a plan" signals the required input and "no audio is generated" routes the agent away from generation tools. There is no explicit statement of when to choose this over reference_brief, critique_plan, or corpus_stats.

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

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

Annotations already cover the safety profile (readOnly, idempotent, closed-world, non-destructive), so the bar is lower. The description adds genuinely useful behavior: matches are returned individually with citations, and results are not aggregated into trend claims, which tells the agent how to interpret and trust the output.

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, then the input convention, then the output contract. Nothing is redundant with the title or 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?

An output schema exists, so return format is partly covered by the tool itself. But for a seven-parameter tool with a nested pattern array and a filters object, the description omits how pagination (cursor/limit), repeat, tolerance_ms, and the filter fields behave, leaving real gaps for correct invocation.

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

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

Schema description coverage is 0%, so the description has to carry parameter meaning. It does explain the critical part—pattern steps must use taxonomy keys, not natural language—and hints that alignment depends on measured beats, but limit, cursor, repeat, filters, and tolerance_ms are left entirely undocumented.

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

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

States a specific verb and resource ('Find consecutive scene patterns') and adds the distinguishing constraint that steps use taxonomy keys rather than free text. It does not name or contrast with the clearly adjacent siblings (search_scenes, find_similar, typical_structure), so the agent must infer 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?

'Optionally aligned with measured beats' implies when to set on_beat, and 'no small-sample trend claims' nudges away from the trends tool. However, there is no explicit when-to-use/when-not guidance and no naming of alternatives among the many search/analysis siblings.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower, and the description still adds real value: it discloses that output is 2-3 contrasting variants, that timing scaling is explicitly a proposal rather than a fact, and that under-sampled patterns will not be passed off as norms. Those are non-obvious output-epistemics that annotations cannot 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?

Two dense sentences with zero filler, and the output contract is front-loaded before the caveat. It is arguably too terse for the parameter surface it must cover, but no sentence 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?

An output schema exists so return values needn't be explained, and annotations cover the safety profile. Still, for a 6-parameter, nested-object tool in a crowded sibling set, the description leaves the filtering/cohort controls and the sibling boundary undefined, which is a real gap for correct invocation.

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

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

Schema description coverage is 0% across 6 parameters, including a nested filters object with nine sub-properties, so the description must carry the load. It only maps 'two or three' to variants and 'exact-duration' to duration_ms, saying nothing about aspect, min_videos, allow_broaden, or any filter field, leaving most of the surface undocumented.

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

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

Names a specific verb and artifact ('Create two or three contrasting exact-duration plans') sourced from 'cited observed sequences', which tells an agent what comes out. It does not, however, distinguish itself from near-siblings like typical_structure, critique_plan, or reference_brief, so an agent must guess at the boundary.

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

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

There is no explicit when-to-use or when-not-to-use guidance, and no sibling is named as an alternative even though typical_structure and critique_plan sit right next to it. The second sentence is a behavioral caveat about proposals and under-sampling, not usage routing.

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

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

Annotations already declare readOnly/idempotent/non-destructive and closed-world, so the safety profile is covered. The description adds real value by disclosing that results are baselined against per-video OCR distributions and that the WCAG contrast check comes with 'applicability caveats' — but it is silent on the non-obvious corpus-threshold behavior implied by min_videos and allow_broaden.

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 dense sentences with the primary action front-loaded and the optional contrast check second. No filler, though the semicolon-joined clauses pack multiple ideas that could be split for clarity.

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

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

An output schema exists, so return values needn't be explained. But for a tool with a nested per-item schema plus a corpus-filter and broadening mechanism, the description leaves the caller guessing how baseline comparisons resolve when filters or min_videos exclude matches.

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

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

Schema description coverage is 0%, so the description must compensate. It does partly: 'geometry and display time' maps to box/line_height_pct/in_ms/out_ms and 'optional color contrast' maps to foreground/background/large_text. However the entire filters object, min_videos, and allow_broaden go unmentioned in both schema and description.

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

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

States a concrete verb and resource: checking supplied text geometry and display time, and comparing size/reading demand/margins against per-video OCR distributions. This is specific enough to separate it from corpus-level siblings like corpus_stats or compare_to_reference, though it never explicitly names an 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?

The phrase 'supplied text' implies the caller brings items, but there is no explicit when-to-use, when-not-to-use, or named alternative among the ~34 siblings. An agent must infer that this is the per-item readability validator rather than a plan-critique or reference-comparison tool.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive), so the description is free to add genuinely new behavior: the output lands as REFERENCE.md in markdown, the 120 s window cap, both source and composition frame rates are emitted, and measured/annotated/derived/unknown values are kept separate. The provenance-separation and 'frames worth checking' notes are exactly the kind of behavioral detail annotations cannot 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?

One dense sentence plus a short clause, with the core transformation front-loaded before the contents list. Every element (artifact name, window limit, frame rates, provenance rules) carries information, though the packed middle list is harder to scan than separate lines would 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 five optional parameters, an output schema present, and safety annotations already covering the side-effect profile, the description closes the remaining gaps an agent needs: the two input modes, the 120 s ceiling, the deliverable format, and how frames/values are reported. Nothing required for a correct call 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 60% and two parameters (scene_id, video_slug) have no schema description at all. The description compensates by making the two selection modes explicit — a single scene versus a start/end window of video up to 120 s — which the schema expresses nowhere (no anyOf or mutual exclusion), and it contextualizes target_fps as the composition frame rate distinct from the source rate.

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 transformation: a chosen scene or a <=120 s window becomes a frame-numbered reference (REFERENCE.md in markdown) for motion work. The enumerated contents (scene boundaries, text entrance/landing/hold, camera moves, audio cues) make the artifact concrete. It does not name a sibling to distinguish from get_scene or compare_to_reference, so it stops short of a 5.

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

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

The two input modes ('one chosen scene, or a window of up to 120 s') imply when to use it, and the 120 s cap is a useful guardrail. However there is no explicit statement of when to prefer this over get_scene, get_frames or compare_to_reference, and no exclusions or prerequisites are given.

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

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

Adds real context beyond the annotations: the destination is a private account board mirrored to an external website, and the call needs an account plus write scope. However, the annotations flag destructiveHint=true and idempotentHint=false, and the description's 'Save' framing never explains what gets destroyed or why repeats are non-idempotent — the single most important behavioral question for this call is left unanswered.

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

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

Two sentences, front-loaded with the action and destination, followed by prerequisites. No filler or repetition of schema constraints.

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?

Output schema exists, so return values need no explanation, and the auth/exposure facts are covered. For a destructive, non-idempotent mutation with four entirely undocumented parameters — including an apparent either/or board selector — the description leaves too much for the agent to guess.

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

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

Schema description coverage is 0% across four parameters, so the description must carry the semantics and does not. It never explains the board_id vs board_name relationship (the schema requires neither, so the agent must infer one is needed), nor what the note parameter is for.

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

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

States a specific verb and resource ('Save reviewed scenes to a private account board') and names the destination surface (Launchscene website). It is clearly distinguishable from read-side siblings like list_boards or get_scene, though it never names the counterpart tool an agent would use to find a board.

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?

'Save reviewed scenes' implies a post-review moment and 'Requires an account and write scope' states a prerequisite, so some usage context is present. But there is no explicit when-not guidance, no mention of what to do when the board doesn't exist yet, and no pointer to the sibling that lists boards.

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 establish the safe, read-only, idempotent, closed-world profile, and the description adds one genuinely non-obvious behavior: unknown alignment never matches an on-beat filter. Beyond that it says nothing about pagination via limit/cursor, result ordering, or what a returned 'offset' means, leaving gaps annotations cannot 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?

Two tight, front-loaded sentences with no filler; the core action comes first and the edge-case rule second. Slight terseness costs a point since the density leaves semantics ambiguous rather than efficiently compressed.

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?

Against 9 parameters, 0% schema coverage, a nested filter object, and only an output schema to lean on, this description is far too thin — an agent cannot confidently construct a filters object or understand what cursor/limit do. It covers the beat-offset angle but not the bulk of the tool's surface.

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

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

Schema description coverage is 0% across 9 parameters including a nested 'filters' object, so the description must compensate — but it only implicitly touches on_beat/beat_kind and tolerance_ms, and says nothing about label, limit, cursor, moment_type, within_role, or any of the nine nested filter fields. This leaves most parameter meaning undocumented anywhere.

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

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

The description names a specific verb + resource: searching 'measured/annotated timeline moments' and testing offset from beats/downbeats. This distinguishes it from list-oriented siblings like search_scenes and search_videos, though it never explicitly names those alternatives.

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

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

It implies a narrow use case (beat/grid alignment queries) but never states when to pick this over sibling search tools such as search_scenes, pattern_search, or beat_grid, nor any exclusions or prerequisites. The agent must infer applicability from the phrase alone.

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

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

Annotations already cover read-only/idempotent safety, and the description adds real behavioral context beyond them: only published, reviewed references are returned; each of the first 12 results carries a signed key-frame image plus image_url and launchscene_url; filters apply per scene; scenes with unknown measurements are excluded. It does not mention pagination via cursor or result ordering behavior, which are noticeable gaps.

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

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

Four sentences, front-loaded with what the tool is and what it returns. The image sentence is dense but each sentence carries information; no filler or restatement of the title.

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

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

For a tool with a rich 18-field nested filter object and an output schema that already covers return shape, the description leaves the filter vocabulary and pagination/sorting (cursor, limit max 50, sort enum) unexplained. It is adequate on corpus scope and image behavior but incomplete on how to actually narrow 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?

Schema coverage is only 17% (only the `images` parameter is documented), so the description must compensate. It explains the query as a plain-language description, the and/or relationship with taxonomy filters, that images apply to the first 12 results only, and that unknown-measurement scenes are dropped by filters — but the ~18 nested filter fields (role, tone, brand, color, techniques, etc.), sort, limit, and cursor go 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 ('Main scene search. Finds launch-video scenes') plus the two input modes (plain description and/or taxonomy filters). It implicitly claims primacy among search tools but does not name or contrast with siblings like search_videos, search_by_moment, or find_similar.

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?

'Main scene search' hints this is the default entry point, and the description says what kinds of inputs it accepts, but there is no explicit when-to-use-this-vs-alternative guidance despite four sibling search tools existing.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description's value is the extra behavioral detail it adds: only published and reviewed videos are searchable, only the first 12 results carry signed scene images colored by narrative role, and the score means relevance rather than quality. It does not mention pagination via cursor, which is a remaining 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?

Four short sentences, scope stated first, then coverage, then result shape, then score semantics — well front-loaded with no filler. The mild overlap between 'main search for whole launch films' and 'finds ... launch videos' is the only redundancy.

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

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

An output schema exists and annotations cover safety, so the description doesn't need to explain return values, and it still helpfully flags the signed-image payload. However, for a 6-parameter, nested-filter, cursor-paginated search tool, the absence of any paging or sorting guidance leaves a real 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 17% across six top-level parameters plus a large nested filters object, so the description has to compensate. It does map conceptually to several filters (description/query, brand, industry, timing, sound, style), but says nothing about sort, limit, cursor, or how the facet words map to actual field names.

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

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

The description opens with a specific verb and resource — 'Main search for whole launch films' — and enumerates the searchable facets (description, brand, industry, timing, sound, style). The 'whole launch films' phrasing implicitly separates it from scene-level siblings such as search_scenes and search_by_moment, so an agent can tell what it returns 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?

'Main search' implies this is the primary entry point when starting a video-level lookup, but no sibling is named and no when-not condition is given. An agent must infer from purpose alone that scene-level needs belong elsewhere.

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=true and idempotentHint=false, and the description usefully narrows the blast radius by saying the video is not edited or republished. However, it says nothing about duplicate submissions creating multiple inbox entries (non-idempotent) or whether a submission can be withdrawn, which is the behavior an agent most needs to know here.

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, action first and the scope-limiting caveat second. Nothing redundant and 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?

An output schema exists, so return values need no explanation, and the human-review framing covers the lifecycle. Still, with zero schema description coverage the definition should have explained what belongs in the message and what scene_id refers to; that omission leaves the calling contract half-specified.

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

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

Schema description coverage is 0% for two required parameters, so the description must carry the load and does not. It never says that 'message' is the free-text correction proposal (10-2000 chars) or what 'scene_id' identifies, leaving the agent to infer both from the schema's type constraints 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?

States a specific verb and resource ('Submit an annotation correction') plus the destination ('existing human review inbox'), so the agent knows this routes a request to humans rather than mutating data. It separates itself from editing tools via 'Does not edit or republish the video', though it never names a specific sibling 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?

The inbox framing implies this is the path when a human needs to review a suspected annotation error, and the 'does not edit or republish' clause rules out the wrong expectation. But there is no explicit when-to-use trigger (e.g. 'use when you spot a mislabeled scene') and no alternative tools named for agents who want to change data directly.

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, idempotentHint, and destructiveHint=false, so safety is covered. The description adds useful methodology by explaining that frequencies are per-video proportion distributions to prevent long edits from dominating, but it omits cursor pagination behavior, minimum sample thresholds, and broadening semantics.

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

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

The description is two tight sentences with the core purpose front-loaded. The second sentence earns its place by explaining why the frequency metric is normalized per video.

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

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

For a tool with seven parameters, nested filters, and zero schema parameter descriptions, the description is too thin: it leaves sample-size requirements, broadening behavior, pagination, and filter semantics unexplained. An output schema exists, so return values need not be covered, but input-side completeness is poor.

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% for seven parameters, including a nested filters object. The description only hints at the kind values (next role, transition, techniques) and the after_role concept; it never explains limit, cursor, filters, min_videos, or allow_broaden.

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 analytical resource: what follows a narrative role, with result types of next role, transition, or technique. It does not name sibling tools such as typical_structure or pattern_search, so differentiation from alternatives is left implicit.

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

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

The description implies a narrative-pattern analysis use case, but does not explicitly say when to choose this tool over siblings like pattern_search or typical_structure. It also gives no guidance on when to use options like allow_broaden or min_videos.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), yet the description still adds real substance: per-year video-count gating, that sparse years return null rather than being dropped or erroring, and that "year" means catalogue published_at. That is exactly the kind of behavioral detail 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?

Three short sentences with no filler, and the most decision-relevant fact (sparse years are null) is stated early. The opening sentence is elliptical about its object, so brevity costs a little clarity.

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

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

An output schema exists, so return values need not be explained, but this is a complex aggregating tool with six parameters, nested filters and heavy enum use, all undocumented. An agent cannot choose a metric or predict how filters interact with the per-year minimum from this description alone.

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

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

Schema description coverage is 0% across 6 parameters including a 9-property nested filter object and a 13-value metric enum. The description hints at the min_videos threshold and at the date basis behind year_from/year_to, but never names them, and says nothing about metric, role, limit or cursor. It does not compensate for the coverage gap.

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

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

"Year-by-year descriptive distributions" conveys the aggregation axis (year) but not the subject – which metric, from which corpus. The metric is only discoverable in the schema. It also does not distinguish itself from near-siblings like corpus_stats, typical_structure or compare_groups.

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

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

No statement of when to call this instead of corpus_stats or compare_groups, and no prerequisites or exclusions. The agent must infer usage purely from the name and the enum list.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds genuinely new behavior: results include alternative examples, low-sample results are suppressed, and duration_s expands to a ±50% window unless explicit min/max_duration_ms bounds are given. What is missing is how allow_broaden changes the outcome and whether sequences are ranked or randomized.

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

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

Two sentences, front-loaded with what the tool yields, then the one non-obvious default. Dense and waste-free, though the telegraphic fragment style makes the first sentence read as a data label rather than an action.

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

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

An output schema exists, so return-shape explanation is rightly omitted, but for a 5-parameter tool with a 9-field nested filter object and 0% schema description coverage the description leaves too much undocumented. The agent cannot tell what filters do or how allow_broaden affects suppression without guessing.

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

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

Schema description coverage is 0% across 5 parameters, including a nested filters object with nine sub-fields (tone, brand, voice, aspect, year ranges, industry, duration bounds). The description explains only duration_s and alludes obliquely to min_videos via 'sample-size suppression'; limit, filters, and allow_broaden receive no semantic explanation anywhere.

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

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

The description names the resource precisely (observed narrative role sequences and per-video duration distributions) but is a noun phrase with no verb telling the agent what it does with them — retrieve, aggregate, or compare. It does not differentiate itself from adjacent siblings like pattern_search, trends, get_video_structure, or plan_structure, so the agent must infer the distinction.

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

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

There is no statement of when to use this tool versus alternatives, no prerequisites, and no exclusions. The only guidance-like sentence concerns the duration_s window default, which is parameter behavior, not usage routing.

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