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

No annotations are provided, so the description carries the full behavioral burden. It implies a mutation and gives partial semantics for kind values, but it does not state required permissions, timeline targeting, time format expectations, or what happens when the marker is created.

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 short and front-loaded with the core action. Its second sentence adds useful kind semantics without unnecessary text. It is concise, though under-specified rather than overly verbose.

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 four-parameter mutation tool with no annotations, no output schema, and no schema descriptions, the description is too thin. It does not explain required time/name semantics, the role of note, or the default standard kind.

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 undocumented parameters. It adds meaning only for kind='chapter' and kind='todo', leaving standard, name, note, and especially time 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 states a specific verb and resource: 'Add a marker.' It also clarifies the meaning of two marker kinds, chapter and todo. However, it does not explicitly distinguish this tool from siblings such as list_markers or remove_markers, so it is clear but not fully sibling-differentiated.

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 chapter and todo markers mean, but does not say when to use add_marker itself, when to avoid it, or how it relates to alternatives like list_markers or remove_markers. Usage is only implied by the tool 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?

With no annotations at all, the description carries the full behavioral burden and falls well short. It never says whether FCP must already be running, whether the title is created on the open timeline, what happens to existing titles, or whether the operation is undoable. It adds only format hints (hex/name color, pixel offset), which are parameter detail rather than 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 short sentences, front-loaded with the action and followed by concrete parameter hints, with no filler. The formatting is slightly cramped and the color/offset notes sit awkwardly without bullets, but nothing is wasted.

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

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

A 10-parameter mutation tool with zero annotation coverage and no output schema needs substantially more description than two sentences. An agent lacks the required-parameter callout (text and time), the meaning of time/duration/duration units, and any behavioral context about the Final Cut host state.

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 10 parameters, so the description must compensate, yet it explains only color and y_offset. Key inputs like text, time, duration, lane, alignment, font, size and bold get no meaning, units, or format from either source — for instance 'time' is a bare string with no expected format.

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

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

The description conveys that this creates a Basic Title overlaid on the storyline, which is a specific resource, but the verb "Connect" is imprecise for a creation operation. It also never distinguishes itself from the sibling edit_title, so an agent cannot tell from the text which one to reach for on a given request.

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 reference to edit_title, remove_markers-adjacent title flows, or prerequisites such as Final Cut being open. The only implicit signal is the placement example ('-380 for a lower third'), which is positional, not usage-scoping.

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

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

No annotations are provided, so the description carries the full burden. It discloses scope (all dialogue clips, or a subset via refs), which implies non-dialogue clips are untouched, but says nothing about reversibility/undo, in-place modification vs. new clips, or behavior when no style has been saved.

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, no waste: the action and scope come first and the routing hint second. The parenthetical reference to save_audio_style is compact and load-bearing.

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 annotations and no output schema, the description should cover more of the mutation's edges: what is returned, whether the change is undoable (an undo sibling exists), and the failure mode when no saved style exists. The core action and scope are covered, but these operational gaps remain.

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 the single 'refs' parameter, so the description must compensate. Saying 'or to the given refs' clarifies that refs selects a subset rather than changing the operation, but it never explains what a ref is or how to obtain one (presumably from get_timeline).

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

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

States a specific verb (apply), a specific resource (the saved dialogue sound / audio style), and a precise scope (every dialogue clip in the storyline, or the given refs). It also cross-references save_audio_style so the agent knows where the style comes from, making it clearly distinguishable from normalize_audio.

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

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

Explicitly names the alternative (normalize_audio) and the condition that selects this tool over it (when a style is saved), plus points to save_audio_style for creating the style. It does not state what happens if no style is saved, leaving the negative case 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?

No annotations exist, so the description carries the full burden. It does usefully disclose destructive scope ('Replaces an existing empty/same-named adjustment clip') and that the effect spans the entire timeline, but says nothing about permissions, undoability, or what happens to a non-empty clip with the same name.

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, zero filler, with the primary action and the timeline-wide scope front-loaded before the sequencing 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?

For a two-optional-parameter mutation tool with no annotations and no output schema, the description covers scope, replacement semantics, and ordering. It still leaves the caller guessing about return value and about the `replace_existing` toggle's actual effect.

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

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

Schema coverage is 0%, so the description must compensate. It explains the `name` default ('the style's default look') and implies `replace_existing` behavior via the replacement sentence, but the interaction between the two — e.g. what false does — is never clarified.

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

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

States a specific verb and resource ('Add an adjustment clip with a saved look') and pins the scope ('over the whole timeline'), which separates it from per-clip effect tools like copy_effects and from apply_audio_style. It never explicitly names a sibling as the alternative, so it lands at 4 rather than 5.

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

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

Gives real sequencing guidance: 'Run after cutting (or run fit_to_timeline after later cuts).' That tells the agent where this belongs in a workflow. It stops short of stating when *not* to use it or which sibling to prefer for per-clip looks.

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

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

With no annotations, the description carries the full burden. It does disclose a real constraint ('Only effects already used in this project can be copied') and the 'all' targeting behavior, which are not visible in the schema. The major omission is replace_existing, which defaults to true — meaning existing effects on the destination clips may be overwritten — and this destructive behavior is never mentioned.

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

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

Three tight sentences, front-loaded with the core action and an illustrative example before moving to the special-case behaviors. No filler, though the example phrasing ('e.g. a colour grade or LUT') is the only slightly expendable element.

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 zero annotation coverage, no output schema, and 0% schema description coverage, the definition covers scope and filtering but leaves the overwrite semantics of replace_existing unaddressed. An agent could call this correctly and still unintentionally destroy existing effects on the target clips.

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 all four parameters. It explains to_refs (including the "all" special value) and name_contains, and implicitly frames from_ref as the source clip, but replace_existing is completely undocumented in both schema and description.

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

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

States a specific verb+resource ('Copy video/audio effects from one clip to others') with a concrete example (colour grade, LUT) that disambiguates it from generic operations. It implicitly separates itself from remove_effects and apply_look by scoping to effects already in the project, though it never names those siblings 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?

Provides useful operating context: the magic value to_refs=["all"] targets the whole storyline, name_contains narrows the copy set, and effects must already exist in the project. However, it gives no guidance on when to use this versus apply_look/save_look or remove_effects, and no prerequisites or warnings about overwriting.

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

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

No annotations are provided, so the description carries the full burden, and it does disclose key behavior: later clips slide left, connected items anchored inside a removed range are re-attached at the cut point under "keep" or removed like FCP under "delete". It omits that this is a destructive edit requiring undo, and says nothing about whether it acts only on the primary storyline or also on connected lanes.

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, lead sentence carries verb+resource+argument example, then behavior, then the enum semantics. No filler.

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

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

For an unannotated destructive timeline mutation with no output schema, the description covers ripple mechanics and the connected flag but leaves gaps an agent needs: prerequisites (which timeline), undo/reversibility expectations, and any indication of what is returned. Adequate but not complete.

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

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

Schema coverage is 0%, so the description must compensate and largely does: it gives an example shape for ranges ([[12.5, 15], [40, 41.2]]) and explains both enum values of connected with concrete consequences. It still leaves the time unit (seconds?) and ordering/overlap rules for ranges unstated.

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 ('Ripple-delete time ranges from the primary storyline') with a concrete example of the range argument. The ripple/primary-storyline scoping is clear, but it never names the obvious counterpart sibling keep_ranges or distinguishes itself from delete_clip/remove_silences, so sibling 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?

Usage is implied by the ripple semantics and the connected=

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

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

No annotations exist, so the description carries the full load. It does disclose the key behavioral consequence – whether downstream timing shifts (ripple=True closes the gap) – which is genuinely useful for a destructive edit. It omits reversibility/undo availability, permission needs, and what happens if the ref is invalid.

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 zero filler, leading with the action and identifier format before the optional parameter's effect. Every clause carries information the schema does not.

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

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

For a two-parameter destructive tool with no annotations and no output schema, the definition covers the essential mechanics: identifier format and timing consequences. Missing are error behavior on a bad ref and whether the deletion is undoable, but the core calling information is present.

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

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

Schema coverage is 0%, so the description must compensate, and it largely does: it documents the ref string format including the FCPXML dotted form, and explains what ripple=True/False actually does to the timeline. The only gap is that it doesn't repeat the default value (true) already present in the schema.

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

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

States a specific verb and resource ("Delete a clip") plus the identifier form accepted ("3" or connected "3.0"), so the action is unambiguous. It does not distinguish itself from adjacent edit tools like trim_clip or move_clip, but the verb is specific enough to select correctly.

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 guidance on when to use this versus alternatives such as trim_clip, move_clip, or remove_effects, nor any stated preconditions (e.g. clip must exist in the open timeline). The ripple explanation helps choose a parameter value but not the tool 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?

No annotations are provided, so the description carries the full behavioral burden. It does not say whether unspecified fields are preserved (partial update), what happens if the ref is invalid or no title exists, whether the change is undoable, or what is returned.

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, front-loaded with the action and the editable fields, with the ref hint tucked into a parenthetical. Nothing is wasted, though the parenthetical is slightly awkward.

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

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

For a 4-parameter mutation tool with no annotations and no output schema, the description covers the core operation and the required ref, but leaves partial-update semantics, error behavior, and return value undefined. Adequate but with clear gaps.

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

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

Schema description coverage is 0%, so the description must compensate, and it partly does by naming the three editable fields (text, colour, size) and clarifying the ref format with an example ('2.0'). It omits color format (hex vs name) and size units, leaving real ambiguity in two 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?

States a specific verb+resource ('Change an existing title's text, colour or size'), which distinguishes it from the sibling add_title by making clear it operates on an existing title. It does not name the sibling explicitly, so it falls just short of the top score.

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: use this to modify a title that already exists rather than to create one. There is no explicit statement of when to prefer add_title vs edit_title, nor any prerequisite/permission guidance, so context must be inferred.

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

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

With no annotations, the description carries the full burden. It discloses the key behavioral trait that the clip is not deleted and that the operation toggles a muted/hidden state, but it omits permissions required, exact effect of enabled=false (audio mute vs timeline hide), and whether changes are reversible or affect export.

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 with no wasted words. It conveys the core action and the non-destructive constraint efficiently.

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

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

Given a mutation tool with no annotations, no output schema, and 0% schema description coverage, the description is too sparse. It lacks parameter semantics, permission context, and a clear statement of the resulting state, which an agent needs before invoking it safely.

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 not explain what 'ref' expects (clip ID, name, or reference) nor does it clarify that the 'enabled' boolean maps to enable/disable, leaving both 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 action (enable or disable) on a specific resource (a clip) and explicitly distinguishes it from deletion. However, it doesn't differentiate from other clip-manipulation siblings like trim_clip or move_clip beyond the non-deletion note, which keeps it from a 5.

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

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

The phrase 'without deleting it' implies this is a non-destructive alternative to delete_clip, and '(mute/hide)' hints at the use case. But there is no explicit when-to-use guidance, no named alternatives, and no prerequisites or exclusions stated.

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

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

No annotations exist, so the description carries the full burden. It helpfully discloses the underlying mechanism (drives File > Export XML…) and the side effect of opening the exported file, plus the timeline prerequisite. It omits where the file is written by default, overwrite behavior, and what happens if no project is open.

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; the primary action comes first and the prerequisite last. Minor awkwardness in 'then open it for editing' but nothing 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?

Adequate for a two-parameter tool with no output schema: action, mechanism, and prerequisite are covered. Still missing default save location/filename semantics and failure behavior when no project is open, which an agent would need to call it reliably.

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 implies the open-after behavior ('then open it for editing') but never states that this is controlled by the open_after parameter or defaulted to true, and 'filename' is entirely unexplained (default name/path unknown).

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 (export) + resource (the project currently open in the FCP timeline) + output format (FCPXML). An agent can distinguish this from fcp_import_xml and send_to_final_cut by direction of data flow, 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?

States one real prerequisite ('The user should have the project open in the timeline first'), which is genuinely useful pre-call guidance. However, it offers no when-to-use/when-not guidance relative to alternatives like send_to_final_cut, fcp_menu, or save_timeline.

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

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

With no annotations, the description carries the full behavioral burden. It doesn't say whether this is a safe/non-destructive reposition, what happens if no project is open, how out-of-range times are handled, or how fps affects interpretation, all of which matter for this tool.

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

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

A single tight sentence with zero waste and the key information front-loaded.

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

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

For a simple two-parameter tool with no output schema, the purpose is covered, but the fps parameter's role and the exact time format remain unspecified, leaving an agent guessing on invocation details.

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

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

Schema coverage is 0%. The description clarifies that 'time' accepts seconds or timecode, adding real meaning, but the 'fps' parameter (default 30) is undocumented in both schema and description.

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

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

Specific verb+resource ('Move ... playhead') plus scope ('in the open project'). No sibling competes at playhead positioning, but the description doesn't explicitly differentiate from anything, so a 4 rather than 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 'in the open project' implies the context in which it applies, but there is no explicit when-to-use/when-not guidance or mention of alternatives.

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

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

No annotations are provided, so the description carries the full behavioral burden. It does not say whether the import replaces the current timeline, opens a new library/event, requires FCP to be running, or whether the import is blocking/reversible — significant gaps for a state-changing action.

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 compact sentence with the action and resource front-loaded and no filler. It is efficient, though it also demonstrates that brevity here comes at the cost of missing behavioral detail.

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 annotations, no output schema, and an undocumented required parameter, the description does not cover prerequisites, side effects on the current project, or success/failure behavior. For a file-import action, that leaves materially important context unstated.

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

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

The single 'path' parameter has 0% schema description coverage, so the description must compensate. It names the file types implicitly but doesn't clarify whether path is an absolute filesystem path, whether it accepts a directory for .fcpxmld bundles, or expected format.

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

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

States a specific verb (Import) and resource (.fcpxml/.fcpxmld) and adds the equivalent UI menu path, which makes the intent unambiguous. It doesn't explicitly contrast with siblings like fcp_export_project or find_fcpxml_files, but the import direction is clear enough to distinguish 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?

The 'File > Import > XML' parenthetical implies this mirrors a manual FCP import, giving an implied usage context. However, there is no explicit statement of when to use this versus opening a timeline, or any precondition such as Final Cut Pro already running.

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

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

No annotations exist, so the description carries the burden. It does usefully disclose idempotent-style behavior ('or bring it to the front'), telling the agent it is safe to call on an already-running app. It omits whether the call blocks until the app is ready, what error surfaces if Final Cut Pro is not installed, or whether any permissions are required.

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 short sentence with the primary action front-loaded and the fallback behavior in parentheses. Nothing is wasted and nothing important is buried.

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 zero-parameter, no-output launcher this is nearly complete — no return values need describing. The only real omission given the absence of annotations is readiness/blocking behavior after the launch call.

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

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

The tool takes zero parameters, so there is nothing for the description to explain beyond what the empty schema already shows; baseline 4 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?

States a specific verb ('Open') and resource ('Final Cut Pro'), with a parenthetical clarifying the bring-to-front case. An agent can immediately tell this launches the app rather than inspecting it (unlike fcp_status), 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?

Usage is only implied: an agent infers this is the prerequisite call before timeline/app operations. There is no explicit 'call this first' instruction, no mention of what to do if launch fails, and no reference to fcp_status as a way to check whether it is already running.

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

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

With no annotations, the description carries the full burden. It signals read-only behavior via 'read from Final Cut Pro', which is useful, but omits whether FCP must be running, whether automation permissions are required, and what happens when no libraries are open.

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 tight sentence with the verb and scope front-loaded and no filler. It is arguably too terse for the information it withholds, but that is a completeness issue rather than a conciseness flaw.

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 zero-parameter inspection tool with no output schema, the agent still lacks the return shape (how libraries, events, and projects are nested) and the preconditions for the call. The description gives a useful high-level picture but stops short of what's needed to act confidently.

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

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

The tool takes zero parameters, so the baseline is 4. The description correctly implies no filtering or selection input is needed to get the full overview.

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 a concrete resource ('open libraries, their events and projects') read from Final Cut Pro, which is far more informative than the bare name 'overview'. It doesn't explicitly distinguish itself from siblings like fcp_status or get_timeline, 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?

There is no guidance on when to call this versus fcp_status, open_timeline, or get_timeline, and no stated prerequisites. The parenthetical '(read from Final Cut Pro)' hints at a non-mutating inspection use case but names no alternatives or exclusions.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It usefully discloses the dual behavior of clicking a menu path versus listing items when one entry is supplied, but it does not mention preconditions such as Final Cut Pro being open/frontmost, side effects of clicking arbitrary menu items, or error behavior.

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

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

The description is two concise sentences, front-loads the core action, and uses examples efficiently. Every sentence adds useful information about how the path argument behaves.

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 one-parameter, no-output-schema tool, the description covers the essential invocation semantics and the listing mode well. However, because there are no annotations and no output schema, it should ideally also state basic preconditions and clarify what is returned in the listing mode or after a click.

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

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

Schema coverage is 0%, so the description must compensate for the bare array-typed path parameter. It does so well: the examples show ordered menu traversal, including nested submenus like ["File", "Share", "Master File (default)…"], and it explains the special single-element 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?

The description states a specific verb and resource: "Click a Final Cut Pro menu item," and the examples make the intended operation concrete. It also explains that a single-entry path lists menu items instead of clicking, which clarifies the tool's dual behavior, though it does not explicitly distinguish this from sibling tools such as fcp_shortcut.

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

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

The description gives clear usage context for the single-entry case: "With a single entry (["Modify"]) it lists that menu's items instead of clicking." However, it does not say when to choose this tool rather than alternatives like fcp_shortcut or fcp_go_to, so usage guidance is mostly implied by the examples.

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

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

No annotations are provided, so the description carries the full burden. It implies a harmless read, but says nothing about what the returned image is (full screen vs. FCP window only), its format/resolution, freshness, or macOS screen-recording permission requirements. For a capture tool with no output schema, this leaves meaningful behavioral 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?

A single short sentence with the action front-loaded and no filler. The trailing purpose clause is useful, though the phrasing ("Screenshot of the screen") is slightly awkward and could be tightened into a verb-first statement.

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 parameters and no annotations, the definition is low-complexity and the description covers the core intent. However, the most important unknown for a screenshot tool — what the returned image actually contains and in what form — is not addressed anywhere.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline of 4 applies. The description correctly implies the capture is always of the current screen with no configurable options.

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

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

The description states a specific action (capture a screenshot) and the target (the screen / Final Cut Pro's current display), so an agent knows exactly what it produces. It doesn't explicitly contrast with the nearest visual siblings (preview_frame, render_preview, fcp_status), but the operation 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?

"To see what Final Cut Pro is showing" implies the use case — visual verification of FCP's current UI state — but gives no explicit when/when-not guidance or pointers to alternatives like preview_frame for a specific frame or fcp_status for state. Usage is inferred, not stated.

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

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

With no annotations, the description carries the full behavioral burden. It usefully notes that the shortcut acts on whatever is selected in FCP, but it does not disclose side effects, whether destructive actions are undoable, whether FCP must be running or focused, permissions needs, or error behavior for shortcut invocation.

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

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

The description is front-loaded with the core purpose and then the two input modes. The action list is long but directly useful for invocation, and the final sentence about selection scope adds important context without excessive verbosity.

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

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

For a three-optional-parameter shortcut tool with no annotations or output schema, the description covers purpose and parameter usage reasonably well. However, it omits important context such as whether Final Cut Pro must already be running/focused, how conflicts between `action` and `key` are resolved, and what kind of response or failure an agent should expect.

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

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

Schema description coverage is 0%, so the description must compensate, and it largely does. It explains that `action` takes named shortcuts with many concrete examples, and that `key` with `modifiers` provides raw shortcut input using command/option/control/shift. It does not fully specify key format, modifier casing, or precedence if both `action` and `key` are supplied.

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

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

The description states a specific verb and resource: press a Final Cut Pro shortcut in the app. It also gives concrete action examples and explains the raw key/modifier path, so the tool is distinguishable from generic menu or dedicated edit tools. It does not explicitly contrast itself with siblings like fcp_menu, undo, redo, or split_clip.

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 the two invocation modes, named action or raw key plus modifiers, but does not say when to choose this tool over siblings such as fcp_menu, undo, redo, split_clip, or other dedicated editing tools. It also gives no exclusions or prerequisites for use.

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

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

With no annotations, the description carries the full burden. The interrogative phrasing ('Is...installed/running') makes clear this is a non-mutating probe with no side effects, which is the key behavioral fact. However it does not say what happens if FCP is not installed (error vs. false), nor whether it launches the app as a side effect.

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

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

A single front-loaded clause with no waste; every element maps to a distinct returned fact. It is a sentence fragment without an explicit verb phrase, which costs it a point on structure but not on length.

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

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

For a zero-parameter, read-only status probe with no output schema, the description is sufficient: it enumerates the three facts an agent would need to decide whether to proceed with fcp_launch or other operations. Only the not-installed/failure behavior is left unstated.

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

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

The tool takes zero parameters, so the schema is trivially complete and there is nothing for the description to disambiguate. Baseline of 4 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 names a specific resource (Final Cut Pro) and enumerates exactly what state is reported: installed/running, version, and frontmost status. It is distinguishable from fcp_launch (which starts the app) by being purely interrogative, though it never explicitly contrasts with that sibling.

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 the pre-flight probe to run before/after fcp_launch or before any timeline operation. There is no explicit 'call this when...' clause and no named alternative.

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

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

No annotations are provided, so the description carries the behavioral burden. It discloses search locations and that it looks for recent exports, but it does not clarify return format, sorting, whether the operation is read-only, or how 'recent' is determined beyond the unexplained 'days' parameter.

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. Search locations and file types are packed efficiently, and there is no redundant restatement of the tool name or 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 simple file-search tool, the description covers the file types and default locations well enough to attempt a call. However, with no annotations and no output schema, the unexplained 'days' parameter and undefined return behavior leave meaningful gaps for an agent trying to invoke it precisely.

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 only vaguely mentions the optional folder ('or a given folder') and never explains the 'days' parameter, its default of 14, or how recency is measured, leaving most parameter 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?

The description states a specific verb ('Find') and resource ('recent FCPXML exports') with file extensions and default search locations, making the tool's scope clear. It does not explicitly differentiate itself from siblings such as fcp_import_xml or fcp_export_project, 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 implies usage by saying it searches recent exports in common folders or a given folder, but it provides no explicit when-to-use guidance, exclusions, or named alternatives. An agent can infer this is a discovery tool, but routing decisions remain underspecified.

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

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

With no annotations, the description carries the burden and does well: it discloses that nothing is changed, that each result proposes removing the FIRST take in favor of the later one, and that times are on the current timeline. It omits detection limits, cost/scope of the scan, and what happens for very short or long timelines, so it is strong but not exhaustive.

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

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

Front-loaded with the purpose and examples, then behavior, then usage advice—every sentence adds information. The review caveat is slightly parenthetical but still earns its place by preventing blind cut_ranges calls.

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

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

No output schema or annotations exist, so the description is the only specification; it covers result semantics (first-take removal proposals, current-timeline times) but leaves window_seconds undefined and does not describe the shape of each returned result beyond one proposed action.

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

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

The single parameter window_seconds has 0% schema description coverage and the description never mentions it, so an agent cannot know it controls how far apart the repeated takes may be. This is the tool's only tunable and it is completely undocumented in both places.

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 (find) and resource (stutters, retakes, filler sounds) with concrete inline examples ("to new to new tech", um/uh), which is far more precise than a name restatement. It is clearly distinguishable from siblings like find_silences or transcribe because the artifact types it targets are 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?

Gives real downstream guidance: results are proposals 'ready for cut_ranges', and it instructs the agent to review and keep the first take when it is clearly better. It does not explicitly contrast with find_silences or say what context (whole timeline vs selection) it should be run in, so usage is clear but not fully framed.

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

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

With no annotations, the description carries the safety burden well: 'Nothing is changed' makes the non-destructive nature unambiguous, and it explains that defaults derive from the user's own hand-trimmed style. It does not describe the shape of the returned pause list, which is the remaining gap for a tool whose primary output is that list.

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 distinction (dry run, nothing changed), then defaults, then per-parameter semantics. Every clause carries information; there is no filler.

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

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

For a zero-annotation tool with 0% schema coverage and no output schema, the description covers purpose, safety, defaults, and all four parameters. Missing only units of measure and any hint about the returned pause entries, both of which the agent would otherwise have to discover by calling.

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

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

Schema coverage is 0%, so the description must compensate, and it does: each of the four parameters gets meaning, with concrete anchors like '-30 catches breaths, -40 only near-silence' and the distinction between air left after a word vs before the next. Units (seconds vs milliseconds) are never stated, which is the one real ambiguity left.

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 ('list pauses in the storyline clips' audio') and frames itself explicitly as the 'dry run for remove_silences', which cleanly separates it from that sibling. An agent knows exactly what it gets back without opening the schema.

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

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

It names the alternative (remove_silences), states this variant changes nothing, and tells the agent that settings come from get_style unless overridden ('pass values only to override'). That is an explicit when-to-use and when-to-override rule, not an inference.

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

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

With no annotations, the description carries the full burden. It discloses the core mutation, target type, resulting span, and sequencing, but does not address reversibility, selection/auth prerequisites, side effects on linked media, or behavior when multiple items match.

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 operation and result, followed by target identification and timing. Every sentence adds useful information with no filler.

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

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

For a simple two-parameter timeline operation with no output schema, it covers purpose, target identification, and timing. However, because both parameters are optional and no annotations exist, it should clarify that at least one identifier is required and what happens if both are provided.

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%, but the description compensates by explaining both parameters: ref as an identifier like "0.1", and name_contains as matching part of a name or effect name. It does not state precedence when both are supplied or that at least one identifier is 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?

The description states a specific verb and resource: stretch/shrink a connected item so it starts at 0 and covers the whole edit. The examples (Adjustment Clip with a look, watermark title) make the operation concrete and distinguish it from generic trimming or moving.

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 sequencing guidance with 'Run after cuts' and implies when to use it based on the desired full-edit span. It does not name alternatives or exclusions, so it falls short of explicit when-not guidance.

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

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

No annotations are provided, so the description carries the full burden. 'Read this' implies a non-mutating lookup and the content list hints at the return payload, but it never states that it is side-effect free, requires no permissions, or what shape the data comes back in. Adequate but with real gaps for an unannotated tool.

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

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

Two sentences, zero filler: the first enumerates the returned style components, the second gives the timing cue. The content list is front-loaded and every clause earns its place.

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

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

There is no output schema, so the description must describe the return, and it does so by naming the style facets the agent will receive. What's missing is the response format (structured object vs prose summary), which matters slightly given no output schema exists.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate. The baseline for a no-parameter tool 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?

Specific verb (read/get) and resource (the user's saved editing style), with an enumeration of what the style contains: pause-cut tightness, audio chain, default look, saved looks and learned notes. That is far more than a restatement of the name. It does not explicitly differentiate from siblings like update_style or apply_look, though 'Read this' implies the non-mutating counterpart.

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

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

States a clear when-to-use: 'Read this before a rough cut,' which tells the agent the exact point in the workflow to call it. No exclusions or named alternatives are given, so it stops short of a 5.

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

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

With no annotations, the description carries the full behavioral burden. It discloses the scope ('primary storyline') and the data returned, including connected items, but does not explicitly state that the operation is read-only, what happens on invalid ranges, or any pagination/output format details.

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 compact sentences with no wasted words. The primary data scope is front-loaded and the optional range filter follows immediately.

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

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

For a read-only timeline inspection tool with no output schema, the description is reasonably complete: it enumerates the returned clip data and explains the optional range filter. It could do slightly more on output shape and range semantics, but an agent has enough to call it correctly.

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

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

Schema description coverage is 0%, so the description has to compensate for the two parameters. It clarifies that start and end are seconds and define an overlap filter, but it does not specify inclusive/exclusive boundary behavior, null/default handling, or whether both must be supplied.

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

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

The description identifies the resource and contents precisely: clips in the primary storyline with refs, times, source media, effects, volume, and connected items. It is clear enough to distinguish a timeline-inspection tool from edit/mutation tools, though it never explicitly says 'retrieve/list' and does not contrast itself with open_timeline.

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

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

The only usage guidance is the optional start..end overlap filter, which implies how to narrow results. It does not state when to use this tool instead of siblings such as open_timeline, validate_timeline, or list_markers, nor does it mention prerequisites or exclusions.

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

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

No annotations exist, so the description carries the whole burden. It does disclose meaningful side effects — insert splits the storyline and pushes later clips right — which is exactly the kind of ripple consequence an agent needs. It is silent on prerequisites (must a timeline be open?), failure behavior for bad paths, and whether the operation is undoable, which are significant gaps for a mutation tool with zero annotation coverage.

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

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

Front-loads the core action in one sentence, then spends the remaining clauses entirely on mode semantics and parameter meaning. No filler, no restatement of the name, and the highest-value distinguishing information comes first.

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

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

For a 7-parameter mutation tool with no annotations and no output schema, the description covers the decisions that matter most (mode, time, trim range, role). The notable hole is the lane parameter, which is referenced only indirectly through "lane 1" / "lane -1" in the connect explanation and never defined as an input.

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, and it largely does: mode values are decoded with real semantics, time is tied to connect placement, source_in/duration are explained as selecting the portion of the file, and role gets a concrete example ("music"). lane and path remain unexplained, leaving two of seven parameters to be inferred.

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

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

Opens with a specific verb+resource ("Add a media file to the timeline") and immediately disambiguates the three modes with concrete spatial semantics (above/below the storyline, splits and pushes later clips, appends to end). An agent can distinguish this from siblings like add_title, split_clip or move_clip 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 explicit selection guidance among the mode values with the practical outcome of each (connect = B-roll or music, insert = ripple, append = tail). It does not name alternative tools or state when not to use this tool versus e.g. add_title for titles or move_clip for repositioning, so it stops short of full when/when-not guidance.

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

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

With no annotations, the description carries the full burden, and it does disclose the key destructive fact that everything outside the ranges is removed. It says nothing about reversibility (undo/redo are siblings), whether a timeline must be open, or what the call 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?

One compact sentence with the core behavior front-loaded and the scope constraint immediately after. The trailing tip is short and useful, though slightly informal for a tool definition.

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

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

For a destructive one-parameter tool with no annotations and no output schema, the description is thin: it omits range format/units, whether ranges are applied against the current timeline, and what happens on invalid or overlapping ranges. The core semantic gap is the parameter format.

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

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

Schema coverage is 0% and the only parameter is an untyped nested array of numbers with no title beyond 'Ranges'. The description repeats 'time ranges (in order)' but never specifies the unit or format (seconds, frames, timecode) or that each inner pair is a [start, end] tuple, which is the single most important thing an agent needs.

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: keep only the given ranges and remove everything else. The effect is unambiguous. It never distinguishes itself from the obvious inverse sibling cut_ranges, so an agent must infer which of the two to pick.

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 'handy for building a short/teaser from a longer edit' implies the intended use case but is framed as a tip rather than a rule. There is no explicit when-not guidance and no mention of cut_ranges, the sibling that performs the complementary operation.

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses that save=True stores pause settings, audio chain, and look as defaults, and describes what the comparison reports, but it does not clearly state whether the default compare path is read-only or what happens on failure.

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

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

The description is reasonably concise and front-loads the core purpose before parameter defaults and save behavior. The line breaks and parenthetical examples are slightly messy, but every sentence contributes useful information.

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

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

For a relatively complex comparison-and-learning tool with no annotations and no output schema, the description covers inputs, defaults, reported findings, and save behavior. However, it still leaves the exact return shape and edge-case behavior underspecified.

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, and it largely does: it explains your_version as an exported .fcpxml/.fcpxmld with a default, claude_version as the last sent version, save as persistence, and look_name with an example preset name.

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: compare Claude's rough cut with the user's hand-finished version and learn their style. It is clearly distinct from generic style-management siblings, though it does not explicitly name alternatives such as get_style or update_style.

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

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

It provides implied usage context through defaults for your_version and claude_version, but does not explicitly say when to use this tool versus related siblings like get_style or update_style. There are no exclusions or alternative-routing instructions.

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

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

No annotations are provided, so the description must carry the full behavioral disclosure burden. It only says that markers are returned with their times; it does not state whether the operation is read-only, what scope of markers is covered, or whether any permissions or side effects apply.

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 compact phrase with no wasted words. It is front-loaded but grammatically a fragment rather than a fully structured statement, which keeps it from a 5.

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

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

For a zero-parameter, no-output-schema tool, the description gives some useful return context (marker types and times). However, it leaves the scope ambiguous (e.g., current timeline vs. entire project) and does not fully describe the returned marker fields, so it is adequate but 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?

The tool takes zero parameters, and the schema is fully described (100% coverage). The description adds no parameter information, but the baseline for zero-parameter tools is 4.

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

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

The description identifies the resource (markers) and enumerates the included types (standard, to-do, chapter), making it clear that it retrieves all markers with their times. It lacks an explicit verb such as 'list' and does not contrast itself with sibling tools like add_marker or remove_markers, so it falls short of a 5.

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

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

There is no guidance on when to use this tool versus alternatives. With sibling tools such as add_marker and remove_markers present, an agent receives no explicit context about the appropriate situation for listing markers or any prerequisites.

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

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

With no annotations, the description carries the full burden, and it does disclose the most important behavioral caveat: the measurement excludes Final Cut's Loudness enhancement, so the number reflects the pre-effect level. It does not explicitly confirm the operation is read-only or say what happens when the edit contains no storyline clips, which leaves minor 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?

Three short sentences, front-loaded with what is measured and what is returned before the caveat and the benchmark. Nearly every clause earns its place; only the phrasing 'so treat it as' is slightly loose.

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?

It usefully compensates for the missing output schema by naming the return values (LUFS, true peak) and for the missing annotations by disclosing the enhancement caveat. It is still incomplete on the two undocumented parameters and on the read-only nature of the call, which matters for a tool with no annotations.

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?

Two parameters exist with 0% schema description coverage, and the description never mentions them. It says nothing about how start and end scope the measurement window, so an agent must guess whether they are timestamps, seconds, or frame positions, and whether omitting them measures the whole edit.

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 (measure) and resource (the edit's dialogue loudness) and specifies exactly which metrics are returned (integrated LUFS and true peak). It also pins the measurement scope to storyline clips with clip volume applied, which distinguishes it from level-changing siblings such as normalize_audio or set_volume.

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 interpretive context ('treat it as the level BEFORE that effect') and a useful benchmark ('Reels usually sit around -14 LUFS'), which helps an agent judge results. However, it never states when to choose this over normalize_audio, nor any exclusions or prerequisites, leaving the selection decision 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?

No annotations are provided, so the description carries the full behavioral burden. It states that this reorders the primary storyline, but it does not disclose side effects such as index shifting, whether the operation is undoable, permission requirements, or failure behavior.

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

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

The description is a single, front-loaded sentence with zero wasted text. It communicates the core operation and parameters compactly.

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

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

For a mutation tool with no annotations, no output schema, and 0% schema description coverage, the description is too thin. It leaves important invocation details unspecified, especially index semantics and side effects, so an agent cannot confidently call it without inferring behavior.

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

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

Schema description coverage is 0%, so the description must compensate. It does clarify that `index` is the clip's current position and `to_index` is the destination position, but it omits indexing base, bounds behavior, and how surrounding clips shift.

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 ('move clip') plus the scope ('primary storyline') and the reorder intent. It is clear enough to distinguish from split/trim/delete siblings, though it does not explicitly name 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?

The description implies the tool is used to reorder clips, but it gives no explicit when-to-use guidance, no exclusions, and no alternatives such as insert_media or cut_ranges. An agent must infer usage from the one-sentence action statement.

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

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

With no annotations, the description carries the full load and does well: it discloses that gain is shared across takes by default, that only edit-used portions are measured, and that music/connected audio is excluded unless listed in refs. Missing are reversibility/undo and permission notes, but the scoping disclosure is substantive.

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 dense sentences, each adding a distinct fact — gain target, shared-vs-per-clip behavior, measurement scope, and exclusion rule. The controlling behavior is front-loaded with no filler.

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

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

For a 3-parameter mutation tool with no annotations and no output schema, the description covers what is affected, what is measured, and what is skipped. It leaves open what is returned and whether the change is undoable, which an agent would benefit from knowing.

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

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

Schema coverage is 0%, so the description must compensate, and it does: target_peak_db gains a unit/default (−2 dB), per_clip gains a semantic contrast (each clip separately vs shared gain), and refs gains meaning (list music/connected audio to include). Only refs' exact format (clip references vs names) remains unclear.

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

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

States a specific verb and resource: sets dialogue gain so the loudest peak sits at target_peak_db. This clearly distinguishes it from measure_loudness (reads) and set_volume (manual value). It does not explicitly name siblings, so a 4 rather than 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 implies usage through parameter behavior (shared gain keeps takes balanced; per_clip=True levels each clip) and scoping (music/connected audio left alone unless in refs). It never says when to prefer this over measure_loudness or set_volume, so guidance is implied rather than explicit.

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

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

With no annotations, the description carries the full burden. It usefully discloses return behavior ('Returns a summary and the clip list') and the conditional project-selection behavior, but says nothing about whether loading replaces the current timeline state, how a missing/ambiguous project name is handled, or error conditions for a state-affecting load.

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

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

Three short sentences, front-loaded with the core action, then the conditional case, then the return value. Nothing is wasted.

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

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

With no output schema, the description's return-value sentence is necessary and present, and both params are explained. The main omission is the side effect on existing timeline state, which matters for a load operation.

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

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

Schema description coverage is 0%, so the description must compensate, and it largely does: it explains that 'path' accepts either a file or a .fcpxmld bundle and that 'project' is used to pick one by name when the file holds several projects. It lacks specifics on project-name matching, but both params gain real meaning.

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

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

States a specific verb (Load) and resource (exported FCPXML file or .fcpxmld bundle) with the 'for editing' purpose. It's clear what the tool does, but it doesn't explicitly distinguish itself from siblings like fcp_import_xml or get_timeline, so sibling 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?

'for editing' implies the intent, and the project-selection sentence covers the multi-project case. But there's no explicit when-to-use this versus fcp_import_xml or get_timeline, and no stated prerequisites (e.g., that the file must already be exported).

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

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

With no annotations, the description carries the full behavioral burden and discloses important behavior: it returns an image of the main clip, is scoped to a specific time, and ignores titles/effects/B-roll. It does not explicitly discuss side effects or permissions, but the output and filtering behavior are clearly stated.

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 efficient sentence with no wasted text. The key output and scoping behavior are front-loaded before the parenthetical clarification.

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

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

For a simple two-parameter preview tool, the description covers the core purpose and output scope adequately. However, with no output schema, no annotations, and no schema descriptions, it leaves important invocation details such as time encoding and width behavior unspecified.

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

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

Schema description coverage is 0%, so the description needs to compensate for the undocumented parameters. It only vaguely references the time parameter via "at a time" and does not explain the time format, nor does it mention the width parameter at all.

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

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

The description states a specific output and scope: an image of the storyline's main clip at a given time. It also distinguishes this from a full render by explicitly noting that it ignores titles/effects/B-roll, though it does not name sibling tools.

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

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

The phrase "for checking what's on screen at a cut" gives a clear intended use case. It does not provide explicit exclusions or compare against alternatives such as render_preview or fcp_screenshot, so it stops short of a 5.

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

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

With no annotations, the description carries the full burden. It implies a read but never states that it is non-destructive and requires no Final Cut session, nor does it say how it behaves on unsupported codecs, missing files, or remote URLs. The listed fields are the only behavioral hint.

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 short fragment, front-loaded and free of waste, but it is undersized for a tool with zero annotations and an undocumented parameter, leaving obvious questions unanswered rather than resolving them compactly.

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

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

A read tool with no annotations, no output schema, and no parameter documentation relies entirely on the description. It enumerates some return fields but omits path semantics, error behavior, and whether output is structured JSON, so it is not complete enough to invoke confidently.

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

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

Schema description coverage is 0% and the single required parameter `path` is never explained. The agent cannot tell from either source whether it accepts a filesystem path, file:// URL, or media reference, which is essential for this tool.

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 (media file) and the concrete facts returned (duration, resolution, frame rate, audio, timecode), so an agent can tell this is a metadata-inspection tool. It is not a full verb+resource statement, but among the siblings no other tool probes media metadata, so confusion risk is low.

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, no note that it is read-only inspection before editing, and no guidance on path form (local file, URL, project-relative). The agent must infer everything about usage.

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

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

No annotations are provided, so the description carries the full behavioral burden. It discloses only the scope of the effect; it says nothing about failure when there is nothing to redo, whether the redo stack persists, or whether an intervening edit clears it.

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 with no waste; the verb and object come first and nothing redundant follows.

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 parameterless, single-action command with no output schema, the description is nearly sufficient — an agent can call it correctly. The only meaningful gap is the empty-stack / stack-reset behavior, which matters for a redo command.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline of 4 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?

States a specific verb (redo) and resource (the last undone timeline edit), so the agent knows exactly what the call does. It doesn't name the sibling 'undo' explicitly, but the phrase 'last undone' makes the pairing obvious enough to distinguish it.

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 agent can infer it applies after an undo, but there is no explicit when-to-use/when-not, no note about what happens when the undo stack is empty, and no pointer to the 'undo' sibling.

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

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

No annotations are provided, so the description must carry the full behavioral burden. It indicates a destructive mutation by saying 'Remove effects,' but it does not disclose reversibility, undo behavior, permissions, or what happens when no effects match the filter.

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 wasted words. The core action and the optional filtering behavior are both stated immediately.

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

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

Given that this is a destructive tool with no annotations, no output schema, and 0% schema description coverage, the definition is incomplete. It should explain safety behavior, expected return information, and more precise parameter semantics to be sufficient for reliable 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. It adds useful meaning for name_contains by explaining that effects are matched by name text, and it implies that ref identifies the target clip. However, it does not specify the expected ref format, such as clip ID, index, or name.

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: 'Remove effects from a clip.' It also clarifies the two removal modes, all effects or a name-filtered subset. It does not explicitly distinguish itself from the sibling copy_effects tool, which keeps it from a 5.

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

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

The description implies the tool is used to remove effects and explains the optional name filter. However, it gives no explicit when-to-use guidance, no exclusions, and no comparison to alternatives such as copy_effects. Usage is implied rather than fully guided.

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

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

No annotations are provided, so the description carries the full burden. It does not state that removal is irreversible, what happens when no filters are supplied (presumably all markers are removed), whether the two filters combine with AND/OR logic, or what the operation 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?

A single front-loaded sentence with no wasted prose. The grammar is slightly awkward ('or of one kind'), but it remains efficient.

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

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

For a destructive, unannotated, two-parameter tool with no output schema and no schema descriptions, the description leaves key operational facts unstated: permanence of deletion, default behavior with no filters, and filter composition. It is not sufficient on its own.

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

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

Schema coverage is 0%, so the description must compensate. It mentions both the name-substring filter and the kind filter, but does not explain the allowed kind values (standard/todo/chapter, visible only in the schema enum) or whether both filters can be applied simultaneously.

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

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

States a specific verb and resource ('Remove markers') plus the optional filtering scope. An agent can readily distinguish it from add_marker and list_markers, though no sibling is named explicitly.

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

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

The phrase 'optionally only those whose name contains text or of one kind' hints at filtering, but there is no explicit guidance on when to use this versus list_markers or how to decide between filtering modes. No prerequisites or exclusions are stated.

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

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

With no annotations, the description carries the full load and does well: it discloses that the edit is a ripple (timeline shortens), scoped to storyline clips, and that connected B-roll, titles, music and the adjustment clip survive. It omits whether the operation is reversible or how to revert, which matters for a destructive timeline edit.

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

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

Three short sentences, front-loaded with the operation and its scope, followed by what is preserved and the required precondition. Each sentence adds distinct 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?

Behavioral context is solid for a mutation tool with no annotations and no output schema, but with four undocumented parameters at 0% coverage the agent cannot reason about tuning the silence detection. The definition is adequate to call the tool with defaults, not to configure it deliberately.

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 no parameter names are mentioned; the description only gestures at 'the user's saved style unless overridden' without mapping that to min_silence, threshold_db, keep_before_speech or keep_after_speech. Units, sensible defaults and the relationship between the four params 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?

Names a specific operation ('ripple-delete pauses from the storyline clips') with an explicit framing verb ('jump-cut edit'), which is far more precise than the tool name alone. It also distinguishes itself from find_silences and implicitly from cut_ranges/keep_ranges by scoping the action to detected pauses in storyline clips.

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 workflow precondition: 'Run find_silences first to show the user what will go,' which routes the agent to the correct sibling and even encodes a user-confirmation step. It lacks an explicit exclusion (e.g., what to do for non-storyline clips or manual ranges), so it falls short of a 5.

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

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

With no annotations, the description carries the full burden and does useful work: it discloses the output format, resolution class, and exactly what content is omitted from the render. It says nothing about render duration/blocking behavior, where the file lands when output_path is null, or whether an existing file is overwritten.

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 purpose and its scope caveats front-loaded; the optional partial-render note follows naturally. No filler or restated name.

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

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

For a 4-parameter, no-output-schema tool whose result is a file on disk, the gap around output_path destination and render timing is material — an agent cannot tell where the MP4 will be written or whether the call blocks. Core intent is covered, but these practical details are 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 0%, so the description must compensate. It supplies units for start/end ('seconds') and clarifies that they render only a subrange, and 'low-res' loosely explains height, but output_path and the height default (360) are left completely undescribed.

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 ('render a quick low-res MP4 of the primary storyline') plus explicit scope limits (straight cuts, no effects, titles or connected clips). It implicitly separates itself from a full export, but never names fcp_export_project or any sibling, so an agent must infer the contrast.

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?

'so the user can review an edit before importing' gives a clear context for when to call it, and the 'quick low-res' framing implies it is not the tool for final delivery. No explicit when-not or named alternative (e.g. fcp_export_project) is provided.

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

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

With no annotations, the description must carry the behavioral burden. It discloses that this captures existing state and persists it as a default, but leaves open whether a prior default is overwritten, whether scope is per-project or global, and whether the operation is reversible.

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, zero filler, with the captured content front-loaded before the outcome. The trailing clause 'from a clip they set up by hand' is slightly awkward but earns its place by conveying the prerequisite.

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 one-parameter mutation with no annotations and no output schema, the description covers what is saved and why, but omits what 'ref' expects and what happens to an existing default. Those gaps are material for an agent invoking it unattended.

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

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

Schema coverage is 0% and the single parameter is named 'ref' with a default of '0' - a cryptic name the description never explains. 'From a clip' hints that ref identifies the source clip, but not whether it is an index, id, or timeline reference.

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 (Save) and resource (a clip's audio chain: volume, loudness/noise removal/EQ/effects) plus the outcome (becomes the user's default dialogue sound). This clearly separates it from apply_audio_style and apply_look, though it doesn't name those siblings explicitly.

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

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

The phrase 'from a clip they set up by hand' implies the prerequisite that the source clip must already carry the desired chain, which is useful implicit guidance. It never states when to prefer this over save_look or apply_audio_style, nor any exclusion.

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

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

With no annotations, the description carries the burden and it does disclose the key behavioral trait: the effects are harvested from the adjustment clip in the currently open timeline, and ref falls back to the sole adjustment clip. It leaves out what happens on a name collision, whether a look is overwritten, and what the tool returns, which matters for a persistence operation.

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

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

Front-loaded with the action and result, and the trailing sentence about ref's default is genuinely useful. The aside 'e.g. the one you made with your colour preset' and the informal 'no more Option-A by hand' add color but little precision.

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

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

No output schema and no annotations, yet the description covers purpose, source, and the apply_look pairing. It is still incomplete for a three-parameter mutation: make_default is undefined, overwrite/error behavior is unstated, and nothing indicates what the agent gets back after saving.

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

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

Schema coverage is 0%, so all three parameters need the description. It clarifies ref's meaning beyond the bare null default ('the only adjustment clip') and implies name is the look's label, but make_default is never mentioned despite defaulting to true — an agent cannot tell what it changes.

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 (save) plus resource (effects on an adjustment clip) plus the resulting artifact (a reusable look), with the source clip scoped to the open timeline. It also implicitly separates itself from apply_look, which consumes what this tool produces, so an agent can place it in the workflow without opening either schema.

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

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

It states the condition for use (you have graded an adjustment clip and want that treatment reusable in future rough cuts) and names apply_look as the companion consumer, which is real routing guidance. It stops short of explicit exclusions — e.g. whether copying effects directly with copy_effects is the alternative when you don't want a persisted look.

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

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

With no annotations, the description carries the full burden, and it does disclose two real behavioral traits: the operation writes a new file rather than importing, and the project is renamed by default to avoid clashing. It does not say whether an existing file at the output path is overwritten, whether Final Cut must be running, or what the call 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 sentences, no filler, with the core action and non-import behavior front-loaded and the rename safeguard second. Every clause earns its place.

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

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

For a two-optional-parameter write tool with no annotations and no output schema, the description covers intent and one default but leaves the return value, overwrite semantics, and prerequisites unaddressed. Adequate to call it, not complete enough to predict its effects.

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 explain the project_name default ('<name> (Claude edit)') and implies output_path via '.fcpxml (or .fcpxmld)', but neither parameter's format is specified — no guidance on whether output_path is a file or directory, or what happens when it is omitted (both params are optional).

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 the edited timeline') plus the exact artifact produced (a new .fcpxml/.fcpxmld file) and the key qualifier 'without importing it'. This separates it from file-reading siblings like open_timeline and fcp_import_xml, though it never names the closest alternative, fcp_export_project.

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

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

Usage is only implied: the phrase 'edited timeline' and 'without importing it' suggest calling this after edits to persist work to disk rather than pushing into Final Cut. There is no explicit when-to-use statement and no routing to fcp_export_project or send_to_final_cut, which the agent must disambiguate on its own.

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

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

With no annotations, the description carries the full burden, and it does disclose a genuinely useful trait: the operation is non-destructive and the result lands in the same event. It omits whether Final Cut Pro must already be running, whether the app is launched/opened, and what happens on failure or name collision.

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 zero waste; the action is front-loaded and the non-destructive guarantee follows immediately.

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

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

A file-creating mutation tool with no annotations, no output schema, and 0% parameter coverage needs the description to cover inputs and preconditions, and it covers neither. The outcome is clear but the mechanics of calling it are not.

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

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

Schema description coverage is 0% and both parameters are optional and undocumented. The description never mentions output_path or project_name, so an agent cannot tell where the file is written or how the new project is named.

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 the edited timeline as a new project and import it into Final Cut Pro. This is distinguishable from save_timeline and fcp_export_project by the 'new project' + 'same event' framing, 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?

Usage is implied rather than stated: the note that the original project is untouched tells the agent this is the non-destructive route, which is decision-relevant. But there is no explicit when-to-use vs save_timeline/fcp_export_project guidance and no stated prerequisites.

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

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

No annotations are provided, so the description carries the full burden. It conveys that this is a mutation ('set') and gives useful calibration of the value range, but says nothing about whether the change is additive to existing clip gain, whether it is undoable, what permissions/selection state are needed, or what the response contains.

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 with zero filler; the parenthetical examples each add real interpretive value for the numeric argument.

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

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

For a 2-required-parameter mutation tool with no annotations and no output schema, the definition leaves the central 'ref' parameter undefined and omits any account of effect or return. It is under-specified for the complexity of the operation.

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

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

Schema coverage is 0%, so the description must compensate. It does well for 'db' (0 unchanged, -6 quieter, -20 background music) but leaves 'ref' completely unexplained – the agent cannot tell whether it is a clip ID, name, or index.

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 (set) and resource (clip's volume) plus the unit (dB), which is unambiguous on its own. It stops short of distinguishing this from siblings like normalize_audio or measure_loudness, but an agent can still tell what the tool does.

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 dB examples hint at the intended scale but never say when to use this rather than normalize_audio or measure_loudness, nor any prerequisites (must a timeline/clip be selected first?). The agent must infer the selection context from sibling names 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?

No annotations, so the description carries the full burden. It implies a destructive edit ('Blade') but says nothing about whether the clip is split into two segments, what happens to selection, whether undo is required, or what the response 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?

A single efficient sentence with the action and scope front-loaded. Nothing is wasted, though it could afford one more clause of behavioral detail.

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 one-parameter tool with no annotations or output schema, the description is minimally adequate. It leaves open the post-split state (two clips vs. a cut) and any prerequisites, which an agent would want to know before invoking a destructive edit.

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

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

Schema coverage is 0%, so the description must compensate, and it does partially by clarifying that 'time' accepts seconds or timecode. That is meaningful format information beyond the bare string type, though no examples or constraints are given.

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 ('Blade') and resource ('the primary storyline'), plus the triggering input ('at a time'). The scope constraint 'primary storyline' helps separate it from generic edit tools like trim_clip or move_clip, but 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?

No guidance on when to choose split_clip over alternatives like cut_ranges, keep_ranges, or trim_clip. The phrase 'at a time' weakly implies a single-point split but no conditions or exclusions are stated.

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

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

With no annotations, the description carries the burden well: it discloses that timestamps are on the CURRENT timeline and shift after cuts, and that the first run per file is slow and may download the model while later calls are instant. It stops short of saying whether results are cached to disk, whether the operation mutates project state, or what the transcript looks like.

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 timestamp behavior, then usage, then parameter hints, then performance notes. Dense but every sentence carries information; minor tightening possible.

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

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

For a 6-parameter tool with no annotations and no output schema, the description is decent but incomplete: it never describes the return shape (plain text vs. segments vs. word list) or what refresh actually does, both of which an agent needs before calling.

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

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

Schema coverage is 0%, so the description must compensate; it explains include_words, vocabulary, and vaguely start/end ('limit the window'), but never states units or defaults for start/end. Two parameters — refresh and language — are entirely unexplained, which is a real gap at zero coverage.

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

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

States a specific verb+resource ('Transcribe what's said in the storyline') plus the engine and timestamp behavior, so an agent can tell it apart from editing tools like cut_ranges or find_silences. It does not explicitly differentiate itself from the sibling find_repeats, even though it claims to help 'find repeated takes,' leaving a small ambiguity.

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

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

Gives concrete usage context ('Use it to find repeated takes, flubs and filler') and a conditional recommendation for include_words with start/end to limit the window. No explicit when-not guidance or named alternative is provided.

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

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

With no annotations, the description carries the burden, and it does disclose the most important non-obvious trait: the edit ripples the storyline, so downstream clips shift. It omits permission/undo behavior, what happens if trim_start+trim_end exceeds the clip duration, and whether the operation is reversible.

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, front-loaded with the action and its effect, with zero redundant text. The parenthetical ripple warning is placed exactly where it matters.

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 3-param mutating timeline tool with no annotations and no output schema, the description covers the core edit and its ripple side effect but leaves ref semantics, failure modes, and reversibility unaddressed.

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

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

Schema description coverage is 0%, so the description must compensate. It does define trim_start and trim_end well — units in seconds and which edge each removes — but the required `ref` parameter is never explained (clip id? timeline index?), leaving one of three params 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 (shorten/trim), the resource (clip), and the exact mechanism (removing seconds from each end). It separates itself from siblings like delete_clip and split_clip implicitly via the 'ripples the storyline' note, though it never names an alternative 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: an agent can infer 'use this to shorten a clip in place.' There is no guidance on when to prefer trim_clip over cut_ranges, keep_ranges, split_clip, or delete_clip, and no stated preconditions (e.g., clip must be on an open timeline).

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

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

No annotations are provided, so the description carries the full behavioral burden for a state-mutating tool. It does not say whether undo is reversible (redo stack), how many edits deep it goes, which state it touches (clip edits vs. markers vs. looks), or what it returns or errors with when the history is empty.

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 with no filler. The action and target are stated immediately.

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 zero-parameter, no-output-schema command the description is minimally viable, but it omits failure behavior (empty undo history) and the relationship to 'redo', which an agent in a 50-sibling editing suite would need to call this safely.

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

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

The tool takes zero parameters, so there is nothing for the description to clarify beyond the schema. Baseline 4 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?

States a specific verb and resource ('Undo the last timeline edit'), which is much clearer than the bare name. However, it does not differentiate itself from the sibling 'redo', which is the natural counterpart an agent will be choosing between.

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

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

No explicit when-to-use guidance or conditions. The presence of a 'redo' sibling makes routing guidance especially valuable here, yet the description never says 'use this to reverse an edit; use redo to reapply it' or what happens when there is nothing to undo.

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

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

With no annotations, the description carries the burden: it implies persistence ("saved style defaults") but never says whether changes apply retroactively to existing timelines, take effect on future edits only, or need a re-apply. The add_note behavior (storing a free-text preference) is a useful disclosure beyond the schema, but the operational impact is left implicit.

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 core action and then anchored by user-utterance examples. No filler; the parenthetical direction cues ("raise", "lower") earn their 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?

A 7-parameter mutation tool with no annotations and no output schema needs more than this: four parameters are unexplained and there is no statement about persistence scope, defaults, or what happens to omitted fields. What is present is good, but the coverage gap is large.

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

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

Schema coverage is 0%, so the description must compensate for all seven params, and it explains only three: keep_after_speech, min_silence, and add_note. threshold_db, default_look, remove_stutters, and keep_before_speech get no meaning at all, leaving over 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?

"Change saved style defaults" is a specific verb+resource that clearly separates this tool from timeline-editing siblings like cut_ranges or trim_clip. It doesn't explicitly distinguish itself from get_style or save_audio_style, but the notion of per-editor defaults 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?

It gives concrete trigger language ("when the user says cuts feel too tight… or too loose") and maps each to the right knob, which is exactly the routing an agent needs. It stops short of saying when to prefer this over apply_audio_style or when not to call it.

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

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

With no annotations, the description carries the full burden. It does usefully disclose one behavioral trait beyond structure: the DTD check is conditional on Final Cut Pro being installed, so results vary by environment. It does not state that the operation is read-only/non-mutating, whether problems are reported or auto-corrected, or what form the findings take.

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 action front-loaded and the checks enumerated in a compact list. No filler, nothing buried; every clause adds information.

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

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

For a zero-parameter validation tool with no output schema, the description covers what is checked and one environment dependency. The remaining gap is whether it merely reports issues or alters the timeline, and what it returns — notable given the absence of annotations.

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?

Zero parameters, so the baseline of 4 applies; there is nothing in the schema the description needed to compensate for. No parameter detail is added because none exists to add.

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 ('Check the edited timeline') followed by an enumerated scope: references, gaps/overlaps, frame alignment, and FCPXML DTD conformance. This clearly separates it from neighbors like get_timeline, open_timeline, or preview_frame. It stops short of naming a sibling it is *not*, which keeps it off 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 'the edited timeline' implies it should be run after edits are made, and the parenthetical '(when Final Cut Pro is installed)' gives one concrete precondition. But there is no explicit when-to-use vs. alternative guidance (e.g., before save_timeline, before fcp_export_project) and no when-not conditions.

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