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

Annotations already declare read-only, non-destructive, non-open-world behavior, so the description does not need to restate safety. It adds useful behavioral context by describing the brief's structure, the coverage line "timed items shown n/n", and the typical 15-25x size reduction.

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

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

The description is front-loaded with the core purpose and is dense with useful detail rather than filler. It is somewhat run-on and could be structured more readably, but every clause contributes to explaining the brief's 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?

There is no output schema, so the description carries the burden of explaining return values, which it does thoroughly: symbol table, per-cut lines, nested captions/titles/overlays/sounds/transitions/markers, lane table, density, and coverage line. Combined with the fully described input schema, this is complete enough for correct invocation.

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

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

Schema description coverage is 100%, so the schema already defines all six parameters, including start, end, ids, lang, and detail. The description does not add significant parameter-specific meaning beyond implying that non-default effects and captions are surfaced in the output.

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 a timeline as a compact editorial brief instead of raw XML. The phrase "call this first" and the detailed brief contents make its role clear and distinguish it from raw XML inspection and downstream editing tools.

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

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

It gives clear usage guidance with "call this first" and positions itself against raw XML. However, it does not explicitly mention when to prefer siblings such as fcpkit_timeline_diff or fcpkit_filmstrip, so alternatives beyond raw XML are left implicit.

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

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

Adds substantial context beyond the annotations: only changed lines are written, main-storyline cuts accept vol only, out-of-scope edits abort with nothing written, the result is verified and DTD-validated, and the source is never overwritten. That is consistent with readOnlyHint=false/destructiveHint=false. It does not explain how dry_run or partial alter behavior, which leaves a behavioral 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?

Front-loaded with the core action and then densely packed with constraints; nearly every clause carries information (accepted fields, refusal behavior, verification, no overwrite). Slightly heavy in embedded parentheticals, but no wasted sentences.

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

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

For a mutation tool with five parameters and no output schema, the description covers the write semantics and safety but says nothing about the return value or about dry_run/partial modes. Adequate but with clear gaps an agent would have to discover by probing.

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 60%, and the two undocumented parameters (dry_run, partial) are behaviorally significant flags that the description never mentions. The description clarifies the xml/edited_brief/out relationship somewhat, but it does not compensate for the missing flag semantics.

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 (apply an edited brief back to a NEW FCPXML) and pins the input's provenance to fcpkit_brief ids=true from this exact XML, which separates it cleanly from the sibling fcpkit_brief that produces the brief. An agent can tell exactly what this tool does without opening the schema.

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

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

Gives a clear prerequisite (brief must come from fcpkit_brief ids=true on this exact XML) and an explicit allow-list of applicable edits, with the rule that anything else is refused. It stops short of naming the alternative tool to use when the edit falls outside that list, but the guardrails make the intended usage unambiguous.

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

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

Annotations already declare readOnly, non-destructive, closed-world, so the safety bar is met. The description goes beyond them by disclosing the resolution sources it consults and the four result classifications (MISSING/REVIEW/OK/INFO), which is real behavioral information not encoded anywhere else given there is no output 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 tight sentences, front-loaded with the core action and scoped by the resolution sources. The telegraphic style ('Motion templates (src/uid files)', 'MISSING/REVIEW/OK/INFO per effect') is dense but earns its space; no filler.

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

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

With no output schema, the description is the only source for return semantics, and it gives labels without definitions — an agent cannot tell what distinguishes REVIEW from INFO or what actions each implies. The core scope is adequately covered, but the ambiguous status vocabulary leaves a real gap for interpreting 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 description coverage is 100%, with both 'xml' (path to .fcpxml/.fcpxmld bundle) and optional 'templates_dir' fully documented inline. The description adds nothing about either parameter, so the baseline 3 applies.

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

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

Names a specific verb ('Check') and a specific resource ('every <effect> resource'), and enumerates the three resolution paths covered: Motion templates, FCP built-ins, and FxPlug UUIDs. The sibling tools all operate on other resources (libraries, handles, timeline diff, filmstrip), so there is no realistic confusion, though the description never explicitly routes against them.

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

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

Usage is implied rather than stated: an agent can infer this is a pre-flight validation for effect resolution in a .fcpxml file. There is no explicit 'when to use this vs X', no stated prerequisites (e.g. FCP installed, registry accessible), and no mention of what to do with REVIEW vs MISSING results.

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 non-read-only, non-destructive, closed-world behavior; the description adds meaningful context by saying it writes PNGs to a new folder, returns them as images, and is capped at 8 times. It does not contradict the annotations. It omits details such as overwrite/permission behavior, but the annotation set carries some of that burden.

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 packed sentences with the visual composition and output behavior front-loaded. There is little filler, though the final phrase 'max 8 times' is ambiguous and slightly undermines 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?

For a 6-parameter local tool with no output schema, the description adequately explains the visual output and file-writing behavior. However, it leaves usage routing and several parameter semantics under-specified, so an agent would still need the schema to call it correctly.

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

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

Schema coverage is only 50%, so the description needs to compensate. It implies timeline times and a new output folder, and 'evenly spaced frames' hints at the frames parameter, but it leaves pre, post, and frames defaults/units unexplained. The 'max 8 times' phrase is also unclear about which parameter or limit it refers to.

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 concretely describes generating pictures of the main storyline around timeline times, including what is rendered (multicam angles/compounds, waveform, cut ticks) and the output (PNG folder/images). It clearly distinguishes the tool from siblings like fcpkit_handles or fcpkit_timeline_diff. It is slightly telegraphic and never plainly says 'generate a filmstrip', but the purpose is still evident.

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 does not state when to use this tool, when not to use it, or which sibling to prefer for adjacent tasks. Usage must be inferred from the visual-output description. There is no explicit routing guidance.

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

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

Annotations already establish readOnly/closed-world/non-destructive, so the description spends its budget well by defining the status vocabulary (PASS/INFO/REVIEW/FAIL) and the conservative rule that unknown resolves to REVIEW, never PASS. That is real behavioral context an agent cannot get from annotations. It omits any note about ffmpeg availability affecting results when measuring.

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; the media check precedes the jump-cut check, matching execution order, and the status rule is placed last as a caveat. The parentheticals make sentences long but each 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?

With no output schema, the description usefully supplies the status enum and its default semantics, which is the key return-value knowledge. Missing only the report shape (per-transition list vs aggregate) and whether ffmpeg is required for 'measure' — minor gaps for a read-only inspection tool with a fully documented schema.

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

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

Schema coverage is 100%, so both 'xml' and 'measure' are already documented; baseline 3 applies. The description's mention of 'it would show removed material' loosely hints at what measurement is for, but adds no syntax, format, or cost information beyond the schema.

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

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

States a concrete verb ('check every transition') and enumerates the two things verified: media presence on each side (multicam, compound, retime aware) and dissolves landing on jump cuts. The opaquely named resource 'handles' is defined inline, so an agent can distinguish this from fcpkit_effects_check and fcpkit_timeline_diff. It stops short of a one-line summary of what a 'handle' problem means overall.

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

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

Implies the tool is for pre-conformance validation of transitions, but never says when to reach for it versus fcpkit_effects_check or fcpkit_timeline_diff, nor any prerequisites or exclusion conditions. The triggering context must be inferred from the check list itself.

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

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

Beyond the readOnlyHint annotation, the description discloses key operational behavior: it uses AppleScript, refuses when FCP is not running or two copies are running, and never launches FCP. These are exactly the preconditions an agent needs to avoid failed or surprising calls.

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 front-load the purpose and follow with the critical failure behaviors. Every clause earns its place, including the parenthetical '(AppleScript, read only)' and the 'never launches FCP' guarantee.

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 is simple and its core scope plus refusal behavior are well covered, but with no output schema and no parameter documentation, the definition leaves the two input parameters unexplained. An agent can call it with defaults, but cannot make informed choices about timeout or durations from the description.

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

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

The schema has two parameters, 'timeout' and 'durations', with 0% description coverage, and the description says nothing about either. Since schema coverage is low, the description should compensate for this gap, but it provides no meaning, units, or effect for the parameters.

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

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

The description gives a specific verb ('List') and precise resources ('libraries, events and projects') scoped to the running Final Cut Pro application. It is immediately distinguishable from sibling tools such as timeline_diff or effects_check without needing to open the schema.

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

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

The context of use is implied by 'open in the running Final Cut Pro', but the description never states explicit when-to-use or when-not-to-use guidance relative to siblings like fcpkit_brief. The precondition 'Refuses if FCP is not running' is helpful but is behavioral rather than a usage routing rule.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description reinforces that with "Never rewrites the XML" while adding substantive behavior the annotations don't cover: NFC/NFD-aware path existence checks and bookmark presence. It does not discuss cost on large libraries or how many assets are reported, which keeps it below a 5 given the lower bar set by 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 short sentences, no filler, with the report contents front-loaded and the key safety guarantee ("Never rewrites the XML") placed as a closing qualifier where it is most needed. Every clause carries information an agent cannot get from the schema or annotations.

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

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

There is no output schema, so the description must carry the return shape, and it does by enumerating the four report elements per asset. The remaining gap is the treatment of the two optional-looking prefix parameters and what the output looks like when they are absent, which leaves a small but real hole for a 3-parameter tool.

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

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

Schema coverage is only 33% — only `xml` is documented, while `from_prefix` and `to_prefix` have no schema description. The phrase "whole-segment prefix remap" does add real semantics, implying segment-aware matching rather than substring replacement, but the description never says the two prefixes are optional, whether they must be supplied as a pair, or how the report changes when they are omitted.

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 concrete verb ("Report") and enumerates exactly what is reported: media path per asset, existence with NFC/NFD awareness, bookmark presence, and the result of a hypothetical prefix remap. It is clearly a non-mutating diagnostic, which separates it from any sibling that edits a timeline. It stops short of explicitly naming which sibling to use instead, but no listed sibling overlaps with relink diagnosis.

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

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

Usage is implied rather than stated: "what a whole-segment prefix remap would find" plus "Never rewrites the XML" signals a dry-run to be consulted before committing a relink. There is no explicit when-to-use/when-not-to-use sentence and no named alternative or follow-up tool. Adequate for an agent to infer intent, but it requires inference.

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

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

Annotations already establish readOnly=true, destructive=false, closed-world, so the safety profile is covered. The description still adds real behavioral content beyond them: it discloses that items are paired by unique key (so both timelines must carry stable identifiers) and that deltas are reported in frames for start/end/source. It does not touch cost or output shape, but for a read-only comparison that gap is minor.

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

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

A single front-loaded sentence opens with the core question ('What changed between two timelines') and then packs the comparison semantics and reported fields. Every clause carries information; 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?

With no output schema, the description must carry return-value expectations, and it does list the categories of changes reported. What is missing is the result's shape (a match/changed/added/removed grouping, units of the frame deltas), which an agent would have to discover by calling. For a 4-parameter read-only tool this is close to sufficient but not fully 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 100%, so the schema already documents 'a' as baseline, 'b' as changed, the allowed `kinds` values, and the `caption_pattern` regex. The description reinforces the asymmetric baseline-vs-changed framing via the build-vs-export example but adds no syntax or format detail beyond the schema. Baseline 3 applies.

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

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

The description states a specific verb (diff / 'what changed') and a specific resource (two timelines), then enumerates exactly which aspects are compared: unique-key matching, frame deltas of start/end/source, lane and text changes, added/removed items. No sibling tool (handles, filmstrip, effects_check, relink_preview) shares this operation, so an agent can route unambiguously.

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 parenthetical 'e.g. a generated build vs the editor's FCP export' gives a concrete scenario that tells the agent when this tool is the right pick. There is no explicit when-not guidance or named alternative, but the siblings are functionally distant enough that no exclusion is needed.

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