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

Annotations declare destructiveHint=false (additive updates only), yet the description states 'Overlapping items are overwritten' — an update that removes existing track content. This directly contradicts the declared safety profile, leaving the agent with conflicting signals about data loss and reversibility.

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

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

Two tight sentences, front-loaded with the operation and its placement anchor, with no filler. It is efficient, though the brevity is partly what leaves the parameter space unexplained.

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 9 parameters and 0% schema description coverage, the description should carry far more: source-range semantics, how track integers and strings are interpreted, and project/sequence resolution are all missing. An output schema exists, so return values need not be explained, but invocation inputs remain 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% across 9 parameters, so the schema provides no semantics at all. The description explains only `timeline_in` and its default; `clip`, `kind`, `track` (integer vs string addressing), `project`, `sequence`, `source_in`/`source_out`, and `audio_channel` are entirely undefined.

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

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

Names a specific verb and resource ('Cut a clip into a track') plus a placement anchor (`timeline_in`), which is enough to distinguish it from listers like list_track_items. It does not explicitly separate itself from nearby edit tools such as razor or update_track_item, and 'Cut' is potentially confusable with splitting.

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 supplies placement behavior (default placement is after the last item) which implicitly tells the agent when to omit `timeline_in`. However, it never says when to prefer this over siblings like razor, create_sequence, or add_track, nor does it state prerequisites such as an open project/sequence.

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

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

Annotations already declare a non-readonly, non-destructive, closed-world mutation. The description adds meaningful defaults ("Without item or range it covers the whole sequence") and explains knob-setting behavior, but omits permission requirements, side effects, and error behavior for invalid effect types.

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-load the core action and follow with the knob/scope defaults. It is efficient, though the line break and the parenthetical example could be tightened slightly.

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 8 parameters and 0% schema coverage, the description leaves most parameters unexplained. An output schema exists, so return values need not be covered, but the omission of project/sequence/track/timeline semantics is a significant gap for correct invocation.

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

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

Schema description coverage is 0% across 8 parameters, so the description must carry the burden. It explains `knobs` and implies `effect_type` via 'Nuke node class', and mentions item/range defaults, but leaves `track`, `project`, `sequence`, `timeline_in`, and `timeline_out` completely undocumented.

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

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

States a specific verb and resource (add a soft effect) and clarifies that the effect is a Nuke node class with concrete examples ("Grade", "Transform", "Text2"). It does not explicitly differentiate from siblings like add_clip_to_track or add_track, but the resource is distinct enough for selection.

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 scope (over a shot or frame range, whole sequence by default) but gives no explicit when-to-use/when-not guidance or alternate tools. The default behavior is a useful hint, but an agent still has to infer applicability.

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

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

Annotations already establish that this is a non-destructive mutation (`readOnlyHint: false`, `destructiveHint: false`), so the bar is lower. The description adds meaningful behavior beyond annotations by stating that an existing project tag with the same name is reused rather than duplicated, and it clarifies the valid target structures.

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 tightly front-loaded: the action is stated first, followed by the tag-reuse behavior and target grammar. There is no redundant or filler text, and the target combinations are easy to scan.

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

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

The output schema reduces the need to explain return values, and annotations cover the safety profile. Still, for a 10-parameter mutation tool with 0% schema description coverage, the description is not complete enough: it omits the meanings of several optional parameters and does not mention project context or any error/precondition 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% and there are 10 parameters, so the description must carry the semantic burden. It explains the target-related parameters (`clip`, `sequence`, `track`, `item`) and their combinations, but completely omits `icon`, `kind`, `note`, `project`, and `metadata`, leaving half the parameters 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 gives a specific verb and target resources: tagging clips, sequences, tracks, or shots. It is clearly distinguishable from siblings like remove_tag and list_project_tags because it describes adding a tag rather than listing or removing one.

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 defines valid target combinations (`clip` alone, `sequence` alone, `sequence`+`track`, or `sequence`+`track`+`item`), which is useful invocation guidance. However, it does not explicitly state when to use this tool versus alternatives such as `remove_tag` or `list_project_tags`, nor does it describe prerequisites like needing an open project.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds that the operation targets a sequence and accepts video or audio kinds, but does not explain whether the sequence must already exist, whether duplicate tracks are allowed, or what side effects occur. With annotations present, this is adequate but not rich.

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 the core action front-loaded and no wasted words. It is appropriately short, though the brevity contributes to the missing detail elsewhere.

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?

Although an output schema exists so return values need not be described, this is a mutation tool with four parameters at 0% schema description coverage and no meaningful usage guidance. The description is too thin to let an agent call it correctly without trial and error.

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

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

Schema description coverage is 0%, so the description must compensate for four undocumented parameters. It only implicitly maps to 'kind' (video/audio) and 'sequence', while 'name' and 'project' remain completely unexplained, including defaults and identity/selection 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: adding a video or audio track to a sequence. It is clear what the tool does, but it does not differentiate itself from siblings like update_track, delete_track, or add_clip_to_track.

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, no prerequisites such as needing an existing sequence or project, and no mention of when not to use it. The one-sentence description only implies usage from 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?

Annotations already declare destructiveHint=true and readOnlyHint=false, and the description adds a real behavioral guard the annotations don't convey: the operation fails rather than silently discarding unsaved changes. It still doesn't say whether `save: true` persists to disk or what state the project is left in after closing.

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, zero waste, with the action stated first and the failure mode second. Nothing padded or repeated from the schema.

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

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

An output schema exists, so return values needn't be described, and the key gotcha (unsaved changes) is covered. For a two-parameter destructive tool it's nearly complete; the missing piece is identifying what `project` accepts and whether close releases the project handle for reuse.

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 carries the burden for both parameters. It fully explains `save` (gates whether unsaved changes are persisted instead of refusing), but `project` — a required string, presumably name or path — gets no explanation 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?

"Close a project" is a specific verb + resource and is clearly distinct from siblings like open_project, save_project, and new_project. It doesn't explicitly contrast itself with save_project (which the same agent might otherwise reach for), so it stops short of a 5.

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

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

The refusal condition ("Refuses if it has unsaved changes unless `save` is true") gives the agent a concrete decision rule for the `save` flag. However it never says when to prefer close_project over save_project, or whether close is required before opening/creating another project.

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

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

Annotations already declare this is a non-destructive mutation in a closed world. The description usefully adds that intermediate parent bins are created, which is real behavioral information beyond the annotations, but it says nothing about duplicate/existing bin handling or which project the bin lands in.

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 parent-creation behavior and a concrete example front-loaded. Nothing is wasted, though one more clause on project scoping would have been cheap.

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

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

Output schema exists, so return values need no explanation, and the core creation behavior is covered. But with 0% schema coverage and an unexplained project param, plus no existing-bin behavior, the definition is only adequate for this two-parameter mutation.

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

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

Schema description coverage is 0%, so the description must carry the load. It gives a helpful hierarchical path example for bin_path ("Footage/Day1"), but the project parameter is never explained — whether null means the active project is left entirely to inference.

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 (create a bin) and adds the notable scope detail that missing parent bins are created too, with a path example. It does not explicitly distinguish itself from sibling creation tools like create_sequence or new_project, 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?

No guidance on when to use this versus other creation tools, no prerequisites (e.g. whether a project must be open or the project argument matters), and no note on behavior when the bin already exists. Usage is only inferable from 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?

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=false, so the safety profile is covered and the bar is lower. The description adds that the sequence is placed in a bin and that timecode is expressed in frames, but says nothing about whether the bin must already exist, what happens with default track counts, or whether an open project is 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?

Two short sentences with no filler, and the core action is front-loaded before the parameter clarifications. It is efficient, though the extreme brevity is part of why the remaining parameters go unexplained.

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

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

The output schema covers return values, so that is not a gap. But for an 8-parameter mutation tool with 0% schema description coverage, two sentences explaining two parameters leave an agent unable to set project, bin_path, framerate or track counts with confidence.

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

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

Schema description coverage is 0%, so the description carries the full burden, yet it explains only 2 of 8 parameters: `format` (a name from list_formats) and `timecode_start` (frames). `project`, `bin_path`, `framerate`, `audio_tracks`, `video_tracks` and even `name` get no clarification, leaving the agent to guess at units, defaults and interactions.

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 ("Create a sequence in a bin") and even names the destination container, which distinguishes it from get_sequence, list_sequences and update_sequence in the sibling list. It stops short of explicitly contrasting those siblings, but the intent is unambiguous.

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

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

Usage is only implied by the verb: an agent infers this is the creation step before update_sequence or add_track, but no when-to-use/when-not or prerequisite (open project? existing bin?) is stated. The pointer to list_formats for valid `format` values is the one genuinely useful routing hint.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the bar is lower; the description still earns credit for adding '(undoable)', which is real context not present in annotations. However it omits high-value behavior for a destructive call: whether deleting a bin cascades to its contents, and whether underlying media files on disk are affected or only the project reference.

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 the resource list and reversibility caveat; no padding or repeated information. Efficient for the amount of content present.

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

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

An output schema exists, so return values need not be explained, and annotations cover the safety profile. What remains missing is the one thing an agent cannot infer: how to form a valid 'path' for an irreversible-looking delete, plus cascade behavior — a material gap for a two-parameter destructive tool with zero schema documentation.

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 bare strings, so the description must compensate — it does not. It says nothing about the format of 'path' (filesystem path, bin hierarchy path, or item identifier) or what 'project' does when null, which is the primary ambiguity risk for a delete operation.

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 ('Remove') and enumerates the affected resource types (bin, clip, sequence), which separates it from the sibling deletion tools delete_track and delete_track_items that operate on tracks. It does not distinguish bin-vs-clip-vs-sequence handling, but the resource scope 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?

No guidance on when to prefer this over delete_track_items, close_project, or remove_tag, and no prerequisites or exclusions. The parenthetical '(undoable)' hints at recovery but does not tell the agent when this tool is the right choice.

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

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

Annotations already declare destructiveHint=true and openWorldHint=false, so the safety profile is known. The description adds two things annotations cannot convey: the deletion cascades to everything on the track, and the operation is reversible via undo. It stops short of describing permissions or return content, but the meaningful additions are there.

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 core action front-loaded, cascade scope second, and reversibility as a compact parenthetical. Nothing wasted, nothing 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?

An output schema exists, so return values are covered, and annotations cover the destructive profile. But for a four-parameter mutation with zero schema documentation, the description should clarify how the track is identified and how project/sequence scoping resolves; that gap keeps it at minimum viable.

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

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

Schema description coverage is 0% across four parameters, and the description compensates for none of it. An agent gets no help on whether 'track' is an index or a name (the schema allows both integer and string), or what 'project', 'sequence', and 'kind' default to when omitted.

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

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

States a specific verb and resource ('Remove a track') plus cascade scope ('and everything on it'), so the agent knows exactly what is affected. It doesn't distinguish itself from the sibling delete_track_items or from update_track, but the core action is unambiguous.

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

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

No indication of when to choose this over delete_track_items, or whether prerequisites exist (empty track, active sequence). The only usage-adjacent signal is the parenthetical '(undoable)', which is informational rather than routing guidance.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds that removal is undoable, which is useful context, but it does not explain permissions, side effects, or what happens to related media.

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. It is concise and immediately states the action and undoability.

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?

This is a destructive five-parameter mutation with no schema parameter descriptions, and the description covers only the undoable trait. It leaves key invocation details, especially item identifiers and track/project/sequence targeting, to inference.

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

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

Schema description coverage is 0% across five parameters, including the required items array and the video/audio kind enum. The description only implicitly gestures at items and track; it does not clarify kind, project, sequence, accepted id types, or defaults.

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?

"Remove shots from a track" gives a specific verb and resource, and the resource distinguishes it from siblings like delete_track and delete_bin_item. It does not explicitly name those alternatives, but the action is still clear.

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

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

The description gives no guidance on when to use this instead of delete_track, razor, update_track_item, or delete_bin_item. "Undoable" describes behavior, not usage conditions.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the description adds real value beyond them: main-thread execution (implying UI blocking), pre-imported hiero.core/hiero.ui, and the `result` capture convention. It does not say that the code is unsandboxed, that mutations are not undoable, or that exceptions are surfaced as errors rather than thrown to the caller.

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 lines: purpose and scoping first, then the return convention. Zero filler, and the escape-hatch framing is 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 single-parameter, destructive escape hatch with an output schema, the description covers the essentials an agent needs to call it successfully. The notable omission is the blast radius of arbitrary code execution in a live project session — no statement about persistence, undo, or sandboxing.

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 schema only names a 'code' string with no description, so the description must carry the load — and it does, specifying the assignment target `result` that controls what is returned. The stdout/stderr/traceback note is redundant with the output schema and the string-of-source nature of `code` is only implied.

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 runtime context ('Run Python inside Hiero's main thread') and defines its role as the catch-all the other ~45 tools don't cover. An agent can immediately place it relative to siblings like add_effect or run_export.

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 anything the other tools do not cover' gives an explicit selection rule favoring the dedicated siblings first, which is exactly the routing an agent needs. It stops short of naming concrete when-not cases (e.g. prefer delete_bin_item over raw code for deletions) or warning against routine use for simple operations.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds only a field list, which duplicates the output schema, and says nothing about cost, side effects or how 'open projects' relates to the sibling list_projects.

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 compact phrase with no filler. It is appropriately sized, though being a bare fragment rather than a sentence slightly reduces clarity.

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

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

With zero parameters, an output schema present and annotations covering the read-only profile, an agent has everything needed to invoke it. Only the lack of guidance tying it to sibling tools is missing.

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

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

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

The fragment enumerates exactly what get_app_info returns: product, version, mode (Hiero / Nuke Studio), Python version and open projects. That is specific enough to separate it from siblings like list_projects or get_project, though it is a noun list rather than a verb+resource statement.

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 alternatives (list_projects reports projects too, and mode/version info could plausibly be needed before many other operations). The agent must infer usage from the name alone.

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

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

Annotations already declare this as a read-only, closed-world operation, so the safety profile is covered. The description adds that it returns media metadata and related clip details, but it does not disclose lookup failure behavior, project scoping, or other operational context beyond what annotations and the output schema already imply.

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-loads the returned clip details, then adds the key identifier forms for `clip`. It is efficient, though the parameter note is slightly disconnected and the `project` parameter is omitted.

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

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

The tool is simple and has an output schema plus read-only annotations, so much of the burden is handled structurally. However, the description leaves the optional `project` parameter unexplained and gives no usage routing against siblings, leaving a meaningful gap for an agent choosing and calling the tool.

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

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

Schema description coverage is 0%, so the description must compensate. It usefully defines `clip` as a bin path, clip name, or GUID, but the optional `project` parameter 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?

The description names the resource and the specific details retrieved (media path, resolution, timecode, versions, tags, media metadata), so an agent can tell this is a clip-inspection tool. It does not explicitly distinguish it from related sibling tools such as get_track_item or get_selection.

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

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

The description provides no when-to-use guidance or alternatives. It explains what forms the `clip` argument may take, but not when an agent should call get_clip versus inspecting a selection, track item, or sequence.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds only a restatement of the return payload (frame + sequence), which the output schema already provides, and says nothing about behavior when no viewer is open or no sequence is loaded.

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 sentence with no waste, but it is a sentence fragment rather than a front-loaded statement of purpose, so brevity comes at the cost of clarity.

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

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

With an output schema, zero parameters, and annotations covering the read-only nature, the tool is simple enough that the description is minimally viable. It still omits any statement of the calling context or edge-case behavior, leaving a gap for an agent that does not know the app 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?

The tool takes zero parameters, so the baseline of 4 applies; there is nothing for the description to disambiguate. No parameter-related detail is missing.

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 fragment "Current viewer frame and the sequence being viewed" identifies the resource (playhead state: frame + sequence) but uses no verb and reads as a noun phrase rather than a statement of what the tool does. It is distinguishable from set_playhead only by inference, and no sibling (e.g., get_selection, open_in_viewer) is 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?

There is no guidance on when to call this versus set_playhead, get_selection, or open_in_viewer, and no mention of preconditions such as an open project or an active viewer. The agent must guess the call context entirely.

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?

readOnlyHint=true and openWorldHint=false already tell the agent this is a safe local read. The description adds useful scope information by naming the specific settings categories returned (including transient state like undo/redo and sequences), which goes slightly beyond the annotations, but it says nothing about behavior when 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?

A single compact sentence listing contents, front-loaded with the resource type and zero filler. It is a fragment rather than a sentence, but it wastes no tokens.

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

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

An output schema exists, so return-value detail is not required. However, for a tool whose only argument is an optional project selector, the description leaves the core selection semantics (default = current project? name vs. id?) unexplained, which is the one gap an agent actually needs closed.

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

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

Schema description coverage is 0%, and the single 'project' parameter defaults to null — a meaningful ambiguity (null presumably means the currently open project) that the description never addresses. With no schema text to lean on, the description should have compensated and does not.

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

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

The description enumerates the concrete data the tool surfaces (frame rate, output format, OCIO, views, export root, undo/redo state, sequences), so the resource is identifiable. But it is a bare noun phrase with no verb and no differentiation from siblings such as get_app_info or list_projects, which also return project-level state.

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 indication of when to call this versus list_projects, get_app_info, or open_project, and no mention of what the optional 'project' argument selects. The agent must infer usage entirely from the name.

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

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

Annotations already indicate this is a read-only operation with openWorldHint=false. The description adds useful scope context by stating that it covers both the active timeline and the project bin, which is not captured by annotations. It does not describe edge cases like empty selections, but that is partly covered by the output schema.

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

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

The description is a single, front-loaded sentence that states the tool's purpose without any filler or redundancy. Every word contributes to distinguishing what selection context is captured.

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 zero parameters, an output schema, and read-only annotations, the description is nearly complete. It identifies both scopes of selection, and the output schema can explain the return structure. A minor gap is that it does not clarify whether timeline and bin selections are returned together or separately.

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 has zero parameters, so there are no parameter semantics to document. Per the rubric, a zero-parameter tool receives a baseline of 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 clearly identifies the resource being read: the current selection in both the active timeline and project bin. It is specific enough for an agent to understand the tool's purpose, though it does not explicitly differentiate itself from sibling tools like set_selection or open_in_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?

There is no explicit guidance on when to call this tool, when not to call it, or how it relates to alternatives such as set_selection or get_clip. Usage is only implied by the description of what is returned.

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

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

Annotations already establish that this is a read-only, closed-world operation. The description adds useful behavior for include_items, but it does not cover other behavioral details such as how project/sequence resolution works or what happens when optional identifiers are omitted.

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 sentence with no wasted text, and the include_items behavior is front-loaded. It is efficient, though the phrase 'soft effect' is slightly jargon-heavy for such a short 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?

An output schema exists, so return-value documentation is not required, and annotations cover safety. However, with three parameters and 0% schema description coverage, the description should clarify how project and sequence select the target, especially since all parameters are optional.

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 explains include_items, but project and sequence remain undocumented in both the schema and the description, leaving key parameter semantics 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?

The description identifies the resource (a sequence) and what is returned: details, tracks, and optionally every track item and soft effect. It is clearer than the tool name alone, but it does not explicitly differentiate this from siblings like list_sequences or get_track_item.

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 signal is the conditional behavior of include_items. There is no guidance on when to use get_sequence instead of list_sequences, get_track_item, or list_track_items, and no exclusions or prerequisites 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?

readOnlyHint=true and openWorldHint=false already tell the agent this is a safe local read, so the description carries a lighter burden. The enumerated fields (ranges, handles, speed, media, versions, linked items, tags, metadata) confirm this is the "full detail" accessor, but since an output schema exists this mostly restates the return shape rather than adding behavioral context such as error cases or how unresolvable item references behave.

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 compact sentence with the most salient information (this returns full detail) front-loaded. No waste, though the fragmentary style leaves it slightly under-specified rather than over-long.

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

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

With five parameters at zero schema coverage, an output schema that already documents returns, and read-only annotations that cover safety, the description should spend its words on parameter semantics and item/project/sequence resolution. Instead it spends them on enumerating return fields the output schema already provides, leaving the parameters entirely 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?

All five parameters (item, kind, track, project, sequence) have 0% schema description coverage, and the description says nothing about any of them. Critically, the anyOf[integer, string] type of `item` leaves it ambiguous whether it takes an index, name, or UID, and nothing explains the project/sequence resolution chain or the video/audio `kind` default.

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?

"Full shot details" names the resource conceptually and the field list hints at the retrieve-one semantics, but the description never uses a verb like "get" or states that it fetches a single track item (as opposed to a clip, sequence, or item list). Against siblings like get_clip and list_track_items, an agent must infer the distinction from the tool name alone.

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

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

There is no guidance on when to call this versus get_clip or list_track_items, and no preconditions (open project, valid sequence/track, item must exist). The only usage signal is implicit in the name.

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

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

Annotations already declare this is a non-read-only, non-destructive, closed-world operation, so the safety profile is covered. The description contributes a genuinely useful side-effect disclosure — that the target bin is created automatically if it doesn't exist — but says nothing about overwrite/duplicate handling, supported formats, permission requirements, or failure modes for unwritable paths.

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 most important information (what is imported and where it lands) comes first, and the auto-create behavior is appended where it is most useful.

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

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

An output schema exists, so return values need not be described, and annotations cover the mutation safety profile. However, for a 3-parameter write tool with zero schema documentation, the omission of the 'project' parameter's meaning and the bin_path default behavior leaves real gaps an agent would have to guess at.

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

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

Schema description coverage is 0%, so the description must carry the parameter burden. It loosely explains 'paths' (files or folders, image sequences, movies) and hints at 'bin_path' via 'creating it if needed', but leaves 'project' entirely unexplained and gives no guidance on path format, whether globs are supported, or what the empty default for bin_path means.

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

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

The description uses a specific verb (import) with a concrete resource (files/folders as clips) and names the destination (a bin), plus the types of source material handled (image sequences, movies). It is clearly distinguishable from siblings like create_bin or add_clip_to_track without opening the schema, though it does not explicitly name those alternatives.

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

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

The phrase 'creating it if needed' implies the tool is the entry point for bringing external media into a project, but there is no explicit statement of when to prefer this over create_bin followed by other tools, nor any prerequisites or exclusions. Usage is inferable from the name and sentence, not spelled out.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. Beyond that, the description only states which entity types appear in the tree; it says nothing about how depth limits traversal, whether the result is lazy, or how large a tree can get, which matters for a recursive listing 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?

One tight sentence with no filler and the root-path convention placed up front where it is needed. It is slightly cryptic rather than verbose, but every clause carries information.

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

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

An output schema exists, so return values needn't be described, but the input side is bare: with 0% schema coverage, depth and project are undocumented and there is no hint about hierarchy shape or defaults. For a three-parameter traversal tool the description leaves too much for the agent to infer.

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% for three parameters, so the description must compensate and largely doesn't. It explains bin_path's empty-string convention (partial credit) but leaves 'depth' (default 3, clearly a traversal control) and 'project' completely undefined, forcing guesswork on two of three inputs.

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 (a tree of bins, clips, sequences and tags under a bin) and clarifies the root convention, so the agent can infer this retrieves a hierarchical listing. However, it never uses an explicit verb like 'list' or 'retrieve', relying on 'Tree of...' to imply the operation. It is distinguishable from siblings like list_sequences or list_projects, but only implicitly.

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 use this versus the many sibling list tools (list_sequences, list_projects, list_project_tags), nor any exclusions. The only usable hint is the parenthetical that an empty bin_path means project root, which helps invocation but not tool selection.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds that results span two origins (local and project), which is genuinely useful context, but it doesn't clarify whether both sets are always merged or how the project argument changes the scope.

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. It is efficient, though its brevity is partly the cause of the parameter ambiguity rather than a virtue.

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

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

An output schema exists, so return-value explanation is not required, and the tool is low complexity. The remaining gap is the undefined behavior of the optional project argument, which an agent needs in order 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% for the single 'project' parameter, so the description must carry the meaning; instead it only alludes to 'in the project' without stating whether the argument selects which project's presets to include or what the null default resolves to (current project vs. local-only).

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

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

States a specific verb and resource ('Export (processor) presets') and adds a scope qualifier ('available locally and in the project'), which distinguishes it from siblings like list_formats and list_projects. The parenthetical '(processor)' is slightly cryptic but the core purpose is unmistakable.

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 call this versus list_formats or how it relates to run_export, which is the downstream consumer of these presets. It also doesn't say whether the tool should be called before run_export or what happens if no presets exist.

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?

readOnlyHint and openWorldHint=false already tell the agent this is a safe, closed-world read. The description adds only the parenthetical field list (name, width, height, pixel aspect), which largely duplicates the output schema and says nothing about ordering, formatting syntax, or whether the list is static.

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 the resource first and the returned fields in parentheses. Nothing redundant.

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

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

For a zero-argument, read-only enumerator with an output schema and full annotation coverage, the description supplies everything the agent needs to select and invoke it correctly.

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

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

The tool takes zero parameters, so the baseline of 4 applies; there is nothing in the schema that the description needs to compensate for.

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

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

Names a concrete resource (image formats known to Hiero) and enumerates the fields returned, so the agent knows exactly what it gets. It is clearly distinguishable from resource-oriented siblings like list_export_presets or list_bin, though it never says so 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 description offers no when-to-use guidance, no prerequisites, and no pointer to alternative tools. An agent must infer from the name alone that this is the way to discover supported still-image formats.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description does add one real behavioral fact beyond that — only currently open projects are returned, not all projects on disk — but it does not explain ordering, cost, or what an empty result means.

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 scope constraint ("Open projects") comes first and the returned fields follow, which is the right order for scanning.

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

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

An output schema exists, so the description does not need to explain return values, and with zero parameters there is little else to cover. The only gap is the absence of any pointer to sibling tools for retrieving or opening a specific project.

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; baseline 4 applies. The description's field list (path, unsaved-changes flag, sequence/clip counts) describes output, not inputs.

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?

"Open projects with path, unsaved-changes flag and counts of sequences and clips" states a specific verb (list, implied by name) and resource, and scopes it to currently open projects. It is clearly distinguishable from singular siblings like get_project and from list_sequences/list_bin, 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?

Usage is only implied: the word "Open" tells an agent this covers the currently open project set, and the name makes list-vs-get obvious. There is no explicit statement of when to prefer this over get_project or how it relates to open_project/new_project, leaving routing to inference.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds useful composition detail about the returned set (project Tags bin plus preset tags), but does not clarify whether the optional project parameter defaults to the current project or how preset tags are ordered or deduplicated.

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

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

It is a single front-loaded sentence with no wasted clauses. It is appropriately sized, though its brevity contributes to gaps in usage and parameter guidance rather than being excessive.

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

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

An output schema exists, so return structure need not be explained, and annotations cover safety. However, the description leaves the optional project parameter and usage conditions unexplained, which are meaningful for correct invocation.

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

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

The single optional 'project' parameter has no schema description (0% coverage) and the tool description does not explain what it does, how it defaults, or what happens when it is omitted. The phrase 'available to the project' hints at a project context but does not compensate for the missing parameter 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 clearly identifies the resource (tags available to the project) and distinguishes its contents from generic tag storage by mentioning both the project Tags bin and Hiero preset tags. The verb is implicit rather than explicit, but the tool name and sentence together make the listing operation 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 does not say when to use this tool versus siblings like add_tag, remove_tag, or list_bin, nor does it state prerequisites such as whether a project must be open. The only guidance is implicit in the phrase 'available to the project'.

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

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

Annotations already cover the safety profile (readOnlyHint=true, openWorldHint=false), so the bar is lower. The one genuine addition is the default behavior when 'project' is omitted — it enumerates all open projects — which is useful. Nothing is said about ordering, result size, or whether closed projects are ever included.

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 no waste; the scope constraint is packed into the parenthetical rather than front-loaded as a clause. Efficient for the amount of information conveyed.

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

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

Output schema exists so return values need no explanation, and annotations cover safety. But with 0% schema description coverage on the only parameter, the description should fully compensate and does not — it leaves the identifier format for 'project' undefined.

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 'project' property carries no description, so the description is the only source of meaning. It does explain the optionality and the all-open-projects fallback, but never clarifies whether 'project' expects a name, ID, or index, nor what happens on an invalid value.

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

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

Names the resource (sequences) and scopes it precisely to one project or all open projects, plus the attributes returned (duration, frame rate, format). The plural form plus the sibling get_sequence makes the list-vs-fetch distinction inferable, though it is never stated outright.

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

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

The parenthetical '(or all open projects)' implies the no-argument path, but the description never says when to use this versus get_sequence, list_projects, or list_bin. Usage must be inferred from the name.

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

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

Annotations already declare `readOnlyHint: true` and `openWorldHint: false`, so the safety profile is covered. The description adds that results include timeline and source ranges, which is useful, but it does not disclose ordering, pagination, or default project/sequence 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 compact sentence with no wasted words or repetition. However, it is a fragment rather than a front-loaded verb phrase, which slightly reduces structural clarity.

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

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

An output schema exists, so return format details are less critical, but the input side is materially incomplete. With four parameters, 0% schema coverage, and no description of project/sequence scoping, kind defaulting, or track identifier forms, an agent lacks enough context to call the tool 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% across four optional parameters, so the description must compensate. It only hints at `track` and `kind`, and omits `project` and `sequence` entirely; it also does not explain that `track` may be an integer or string or that `kind` defaults to video.

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

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

The description states the resource being listed, shots/track items, and clarifies the two scopes: one specified track or every track of a given kind. It is clear enough to distinguish from a single-item getter, though it leans on the tool name for the verb and does not explicitly contrast with `get_track_item` or `delete_track_items`.

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 "on one track, or on every track of `kind`" implies when to use the tool based on scope, but it does not explicitly state when to choose it over siblings such as `get_track_item` or `list_sequences`. No prerequisites or exclusions are 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?

Annotations already declare readOnlyHint=false and destructiveHint=false, so the safety profile is known; the description usefully extends this by clarifying which item kinds can be moved and that the root is a valid destination. It says nothing about what happens on name collisions in the target bin, whether the item keeps its position, or what errors occur for invalid paths.

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 the scope and destination up front. The parenthetical about the project root earns its place, though its mangled empty-string literal reduces rather than improves clarity.

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

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

An output schema exists, so return values need no explanation, but for a 3-parameter mutation tool with zero schema descriptions the description leaves too much open: meaning of each parameter, what a move does to the source bin, and any failure modes.

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

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

Schema description coverage is 0% for 3 parameters, so the description must compensate, and it largely does not. It explains only that the empty-string destination means project root (and even that is garbled in the text as '""'), leaving 'path' (source item path? name?) and 'project' (which project, default null behavior) undefined.

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 ('Move') plus resource enumerated ('a bin, clip or sequence') and the destination concept ('into another bin'). It is implicitly distinguishable from siblings like rename_bin_item and delete_bin_item, but never explicitly contrasts with 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 move semantics imply when to use it (relocating an existing item to a different bin), but there is no explicit when/when-not guidance, no mention of alternatives such as create_bin + delete_bin_item, and no prerequisites (e.g., project must be open).

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

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

Annotations already declare this is a non-readonly, non-destructive, closed-world write, so the bar is lower, but the description only adds the word "empty". It says nothing about whether the current project is replaced, whether existing projects are affected, or whether the new project persists to disk automatically.

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 six-word sentence with the action front-loaded and no filler. It is efficient, though the brevity is partly under-specification rather than disciplined editing.

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

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

An output schema exists so return values need not be explained, but for a state-changing project-creation tool the description omits the side effects on the currently open project and the meaning of the optional name parameter. That leaves the agent without enough to call it confidently.

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

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

Schema description coverage is 0% and the single parameter "name" is an undocumented nullable string defaulting to null. The description never explains whether the name is optional, what happens if it is omitted (auto-generated name?), or any naming constraints.

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 ("Create a new empty project") and the word "empty" adds real scope information. It does not explicitly differentiate itself from siblings such as open_project or create_sequence, so the agent must infer the contrast from tool names alone.

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

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

There is no guidance on when to use this versus open_project, nor any mention of prerequisites such as what happens to a currently open project or unsaved changes. The agent is left to infer usage from 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?

Annotations declare readOnlyHint=false, implying state change, but the description never says what that side effect is (does it create/modify a timeline tab or alter the project?). It also omits behavior when both clip and sequence are provided or when neither is, and says nothing about identifiers being resolved against an open project.

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, front-loaded sentence with no filler. It is efficient, though the brevity comes at the cost of the missing information scored elsewhere.

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

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

An output schema exists so return values needn't be explained, but for a 3-optional-parameter, non-read-only tool the description leaves critical gaps: which parameter selects the target, whether project is required for identifier resolution, and what the observable effect of opening is.

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 all three parameters are untyped-in-meaning optional strings with null defaults. The description mentions "sequence" and "clip" but adds no format details, no mutual-exclusivity rule, and never mentions the project 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 gives a specific verb+resource ("open ... in a timeline tab") that is distinguishable from most siblings, but it never contrasts with the closely related open_in_viewer tool, so the agent must infer the distinction between viewing and timeline editing.

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 open_in_viewer, no mention of prerequisites (must a project already be open?), and no note about whether clip or sequence should be supplied. Usage is left entirely to inference.

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

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

Annotations declare readOnlyHint=false with destructiveHint=false, so the agent knows this mutates something safe-ish. The description adds no context about what actually changes (viewer/UI state only, not media or timeline data) or whether the current viewer contents are replaced.

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, front-loaded sentence with no filler, but it is under-specified rather than efficient: there was room to add the routing and parameter detail without bloat.

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

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

An output schema exists so return values need no explanation, but for a 3-parameter action tool with zero annotation-derived detail on side effects, the description leaves the agent unable to decide between this and open_in_timeline or how to combine clip/project/sequence.

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% with three optional, nullable params (clip, project, sequence), and the description only names two of them. It never explains that all are optional, how project scopes the lookup, or what happens if both clip and sequence 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 verb+resource is generic ('Show ... in the viewer') but it does at least name the two target object types (sequence, clip). It does not distinguish this from the sibling open_in_timeline, which sounds nearly identical, so an agent must guess which one opens where.

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

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

No when-to-use guidance and no mention of the closest alternative (open_in_timeline), nor of whether the project must already be open. The only implied usage is 'you have a sequence or clip reference'.

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

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

Annotations already declare readOnlyHint=false with destructiveHint=false, so the safety profile is partly covered. The description adds only that the source is disk, without saying whether the currently open project is replaced, whether unsaved changes are lost, or whether the path must be a .hrox file — meaningful gaps for a state-changing 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?

A single front-loaded sentence with no wasted words. It is perhaps over-terse given the operation's side effects, but nothing in it is redundant.

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

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

An output schema exists so return values need not be explained, and only one parameter is involved. However, for a mutation-adjacent tool that swaps the active project, the description omits what happens to existing project state and how failures are surfaced.

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 'path' parameter is undocumented in the schema, so the description carries the burden. It does add the implicit constraint that the path must point to a .hrox file on disk, but gives no format details such as absolute vs relative paths or extension handling.

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 (.hrox project from disk), which is clearly distinct from new_project, save_project and close_project in intent. It does not explicitly contrast with these siblings, but the action itself is unambiguous.

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

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

No guidance on when to use this instead of new_project, list_projects or get_project, and no prerequisites such as whether the file must exist or whether an open project must be closed first.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the description's added note that only unlocked tracks are affected is useful scope. However, it does not disclose undoability, selection impact, or other mutation behavior beyond what annotations provide.

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

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

A single front-loaded sentence with no filler and the action stated first. The parenthetical is compact, though the extreme brevity contributes to gaps captured under completeness rather than 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 five-parameter mutation tool with 0% schema description coverage, the description is too thin. Even though an output schema exists, it should clarify the non-time parameters and targeting behavior such as project/sequence context and track identifier semantics.

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

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

Schema description coverage is 0% across five parameters. The description only loosely maps 'time' to 'at a frame' and 'track' to '(or one track)'; it leaves kind, project, sequence, and track identifier formats undocumented, so it does not compensate for the schema gap.

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

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

States a specific action, 'Cut', and a clear scope, 'every unlocked track (or one track) at a frame'. It does not explicitly distinguish itself from sibling editing tools, but the verb and resource are understandable 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?

Provides no when-to-use guidance, alternatives, or prerequisites. It describes the operation but does not tell an agent when to choose razor over sibling tools such as delete_track_items or update_track_item.

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

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

Annotations already declare readOnlyHint=false with destructiveHint=false, so the agent knows this is a non-destructive mutation; the description usefully adds that the relink source is a folder path. It does not disclose what happens on an invalid path, whether existing links are overwritten, or whether any partial reconnect can occur.

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 scope alternatives are packed into one clause. It is efficient, though so terse that some of the missing detail could have been added without bloat.

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

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

An output schema exists, so return values need not be explained, and annotations cover the safety profile. Still, for a 4-parameter mutation tool with 0% schema coverage, the description leaves the project parameter and the clip-vs-sequence selection rule undocumented.

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

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

Schema description coverage is 0%, so the description must carry the load, and it does map three of four params meaningfully: path is the folder source, clip is a single target, sequence targets every clip in it. However, the 'project' parameter is never mentioned and the precedence when both clip and sequence are supplied is left ambiguous.

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

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

States a specific verb (reconnect) plus the resource (offline media) and the two scopes it supports (a single clip, or every clip in a sequence) from a folder. An agent can distinguish this from import_media or get_clip. It stops short of naming a sibling explicitly, so it is not 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 word 'offline' implies the trigger condition (media that has gone missing from its original location), but the description never says when to prefer reconnect_media over import_media, nor explains how clip and sequence interact as targets. Usage is inferable rather than stated.

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

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

Annotations already cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false), so the description only needs to add state-changing context. It confirms a project-scoped history mutation but does not disclose error behavior (e.g., nothing to redo), whether history is global or per-project, or any permission requirements.

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, front-loaded sentence with no filler. It is efficiently written, though the extreme brevity leaves needed semantic detail on the table rather than being 'appropriately sized' for a tool with an optional, undocumented parameter.

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

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

An output schema exists so return values need no explanation, and annotations cover safety. However, for a mutation tool with an undocumented optional parameter, the description omits what the default project resolution is and what failure looks like — gaps an agent would care about 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?

The single 'project' parameter has 0% schema description coverage and defaults to null, yet the description only says 'in a project' without explaining what omitting it does (presumably the currently open project). With low coverage the description must compensate, and it does not.

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

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

Specific verb (redo) plus resource context (last undone action in a project) — an agent immediately knows what it does. It does not explicitly contrast itself with the sibling 'undo', relying instead on the name to convey direction, so it stops short of the 5 tier.

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

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

Usage is implied by the name and the phrase 'last undone action', but there is no explicit when-to-use guidance, no mention of the 'undo' sibling as the inverse operation, and no statement about what happens when the undo history is empty.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the mutation risk is covered structurally. The description adds nothing beyond that: it does not say whether the operation is idempotent, what happens when the tag is absent, whether it errors or no-ops, or whether removal 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 front-loaded sentence with no filler. It is efficient, though for a seven-parameter tool the compressed form leaves no structure for disambiguating how the target is specified.

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

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

For a destructive mutation with seven parameters and 0% schema coverage, the description is far too thin. The critical missing piece is the target-addressing logic — which of clip/item/track/project/sequence/kind to supply for each object type — which an agent cannot infer from the schema alone.

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

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

Schema description coverage is 0% across seven parameters, and the description only clarifies the 'tag' parameter (name or GUID). The six target-location parameters (clip, item, kind, track, project, sequence) are left entirely unexplained, so an agent cannot tell which combination is required for which target type.

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

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

States a specific verb and resource ('Remove a tag') and names the accepted identifier forms (name or GUID). It distinguishes itself from the sibling add_tag by direction of the operation, but it muddles the target by listing 'clip, sequence, track or shot' while the schema actually exposes clip/item/track/project/sequence/kind, leaving the exact target model slightly ambiguous.

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

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

There is no when-to-use guidance, no mention of prerequisites, and no reference to alternatives such as add_tag or get_selection. An agent has no signal about how this relates to the many other mutation tools in the sibling list.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so the agent knows this is a non-destructive, local mutation. The description adds only the target categories; it says nothing about whether the rename is persisted immediately, whether it is undoable, how name conflicts are handled, or what error states exist. For a mutation tool this is thin.

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. However, the brevity comes at the cost of substance rather than being a model of compressed 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?

Three parameters, zero schema descriptions, and a mutation operation — the definition should explain path syntax, project scoping, and rename side effects. An output schema exists so return values need not be described, but the input and behavioral picture is materially incomplete.

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

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

Schema description coverage is 0%, so all three parameters (path, project, new_name) are undocumented. The description hints that 'path' is a bin path but says nothing about the path format, the optional 'project' scoping parameter, or any naming constraints on 'new_name' — the schema's burden is not compensated.

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 ('Rename') and enumerates the affected resources (bin, clip, sequence), plus the lookup key ('bin path'). That distinguishes it from siblings like move_bin_item and delete_bin_item, though the tool name's 'bin_item' wording slightly clashes with the broader 'bin, clip or sequence' scope.

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

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

No indication of when to prefer this over move_bin_item or delete_bin_item, no prerequisites (must the project be open? must the item exist?), and no note about what happens on name collisions. The agent is left to infer everything about invocation context.

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

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

The annotations already declare destructiveHint=true and readOnlyHint=false, and the description usefully adds that the export 'may overwrite files on disk.' It also discloses that the operation is asynchronous by default and that progress is visible in Hiero's export queue, which is valuable behavioral context beyond the annotations.

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

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

The description is compact and front-loaded with the main action, followed by focused notes on track_items, export_root, and asynchronous behavior. Every sentence adds actionable information without repetition or 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?

Annotations cover safety signals and an output schema exists, so the description does not need to explain return values. Still, for a six-parameter export operation with 0% schema description coverage, it leaves gaps around project/sequence defaults and how to obtain a valid preset name, making it only adequately 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?

With schema description coverage at 0%, the description must carry parameter meaning and it partially does: it gives a track_items example, explains that export_root overrides the preset root for this run only, and implies the synchronous option via 'Asynchronous by default.' However, it leaves project, sequence defaults, preset discovery, and the track_items item semantics underexplained.

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

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

The description clearly states a specific verb and resource: exporting a sequence or selected shots using a named export preset. It is distinguishable from sibling listing tools like list_export_presets, but it does not explicitly name an alternative or contrast itself with siblings.

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

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

The usage context is implied by 'Export a sequence, or selected shots, with a named export preset,' but there is no explicit when-to-use guidance versus list_export_presets or other sequence tools. It also does not state when to prefer synchronous mode over the default asynchronous behavior.

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

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

Annotations already declare this is a non-read-only, non-destructive, closed-world mutation. The description adds the save-as trigger via `path`, which is useful context beyond annotations. But it doesn't disclose overwrite behavior, error conditions, or whether the `project` argument selects a project or requires it to be open, which matters for a mutation tool.

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

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

A single efficient sentence that front-loads the core action and then qualifies the save-as variant. No wasted words.

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

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

An output schema exists and annotations cover safety, which reduces the burden. However, for a mutation with two 0%-documented parameters, the description should explain the `project` parameter and overwrite/path-exists behavior. Those gaps keep it at minimum viable.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It explains `path` well by tying it to save-as, but says nothing about `project`, leaving an optional parameter completely unexplained. It compensates for only half of the schema gap.

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

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

States a specific verb ('save') and resource ('project') and explicitly distinguishes the save-as variant via the `path` parameter. It is clearly distinct from siblings like `open_project` or `close_project`, though it doesn't mention `new_project` as a related operation.

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 two modes: plain save when `path` is omitted, save-as when `path` is given. However, it doesn't state prerequisites (e.g., whether a project must be open), what happens if the path already exists, or when an agent should prefer `save_project` over `close_project` with save semantics.

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

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

The annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds that the tool changes the clip's active version, which is consistent with a non-destructive mutation. It does not explain side effects, version validity handling, or whether the change 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?

The description is a single front-loaded sentence with no wasted text. It puts the action and the primary parameter values in the most useful order.

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

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

An output schema exists and annotations cover the safety profile, but the input schema has 0% description coverage. The description is too thin for a mutation tool with three parameters, especially because it does not clarify what a clip reference is or when project is required.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It explains the version modes and that an integer can be used as a version index, but says nothing about the required clip identifier or the optional project parameter. This leaves key invocation details 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 and resource: "Change a clip's active version." It also enumerates the version modes, making the tool's purpose clear. It does not explicitly differentiate itself from siblings, but no sibling appears to offer the same version-switching behavior.

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 action: use this tool to switch a clip to a different version. However, the description gives no explicit when-to-use guidance, no prerequisites, and no alternatives for cases where the requested version does not exist.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the safety profile is known. The description adds no behavioral context: it does not state whether playback is paused, whether a sequence must be loaded in the viewer, or whether this only affects ephemeral viewer state versus project data. With annotations carrying the safety burden, the description still leaves too much unstated for a state-mutating call.

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 no filler. Its brevity is appropriate for a trivial setter, though the same sentence could have carried the missing units hint without bloat.

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

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

The tool mutates viewer state and takes an undefined integer, and the description covers neither prerequisites (a sequence open in the viewer) nor the meaning of 'time'. An output schema exists, so return values need not be explained, but the call itself remains under-specified.

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

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

Schema coverage is 0% and the single 'time' integer parameter has no description anywhere. The word 'frame' only weakly hints that 'time' is a frame index rather than a seconds value, and no range, origin, or unit is 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 and resource: 'Move the viewer playhead to a frame.' An agent can tell this affects viewer position rather than clip data. It never contrasts with the sibling get_playhead, so the reader is not explicitly routed away from the read 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?

No when-to-use or when-not guidance. It does not say to call set_playhead only after a sequence is open in the viewer, nor that get_playhead is the read-only counterpart. The agent must infer everything from the name.

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

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

Annotations declare this is a non-destructive mutation, so the safety profile is covered. The description adds useful item-shape detail, but it omits the key behavioral question for a "set" operation: whether the new selection replaces or augments the existing selection, and whether the sequence/project defaults to the active one.

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, nothing wasted, and the purpose is front-loaded ahead of the example. The inline JSON example is dense but earns its space given the opaque items schema.

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

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

An output schema exists, so return values needn't be explained, and annotations carry the safety profile. What remains missing is material for a mutation tool: selection-replacement semantics and the role of the nullable project/sequence scoping parameters.

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

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

Schema coverage is 0% and the items array is an untyped object bag, so the inline example ({"track": 0, "item": "shot010", "kind": "video"}) is genuinely compensating for the most important parameter. However, the project and sequence parameters receive no explanation at all, leaving half the surface undocumented in both schema and prose.

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?

"Select shots in the timeline" gives a specific verb plus resource, so an agent knows the operation immediately. It does not explicitly distinguish itself from the sibling get_selection (the natural inverse), 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?

There is no when-to-use guidance, no mention of get_selection as the read counterpart, and no stated prerequisite that a project/sequence must be open. The agent must infer all of this from the tool name alone.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the safety profile is known. The phrase 'the last action' usefully reveals single-level undo depth rather than a full history stack, but the description says nothing about reversibility via redo, error behavior on empty history, or which project is affected when the parameter is omitted.

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. It is efficient, though the brevity comes at the cost of the behavioral detail noted above rather than being paired with it.

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

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

An output schema exists so return values need not be described, but for a state-mutating tool with one undocumented optional parameter the description omits project scoping, empty-history behavior, and the redo relationship. Too thin to let an agent invoke it confidently.

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

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

Schema description coverage is 0% and the single 'project' parameter is nullable with a null default. The description never explains what an omitted/null project means (presumably the currently open project) or what values are accepted, leaving the agent to guess.

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 ('Undo') and resource scope ('the last action in a project'), so the operation is unambiguous. It does not differentiate 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 guidance on when to use this versus 'redo', no prerequisites, and no mention of what happens when there is nothing on the history stack to undo. Usage is only implied by the word 'undo' itself.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=false, so the safety profile is known. The description adds only the list of mutable fields and says nothing beyond that: whether changes are persisted immediately, whether altering timecode/in-out points shifts existing track items, or whether omitted fields are left untouched is all undisclosed.

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

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

One short sentence, front-loaded with the primary action (rename) followed by the secondary mutations. Nothing is padded or repeated.

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 eight all-optional parameters and zero schema descriptions, the definition leaves critical questions open: how to identify the target sequence and project, whether omitted parameters mean "no change" (partial update) or reset, and whether in_time/out_time are frame indices or timecodes. The presence of an output schema removes the need to document return values, but the input side remains under-specified.

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

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

Schema description coverage is 0%, so the description must carry the burden. It maps conceptually to six of the eight parameters (name, framerate, format, timecode_start, in_time, out_time) but leaves the two selector parameters, sequence and project, entirely unexplained, and gives no units or formats (frames vs. timecode string, framerate as float) for the numeric fields.

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

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

The description names a specific verb-resource pair ("Rename a sequence") plus the exact mutable attributes (frame rate, format, start timecode, in/out points). An agent immediately knows this is a sequence-level mutation, though nothing distinguishes it from the sibling update_track / update_track_item tools that mutate other timeline entities.

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

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

There is no when-to-use guidance, no prerequisite (e.g. project must be open, sequence must exist), and no routing to siblings such as get_sequence for inspection or update_track for track-level changes. The agent must infer all of that from the tool name alone.

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

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

Annotations already establish that this is a non-read-only, non-destructive mutation, so the description does not need to restate safety. It adds useful field-level behavior (what properties can change and the audio volume range), but it omits important mutation semantics: whether omitted/null fields mean 'leave unchanged', whether updates are partial, and whether project/sequence resolution is 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?

It is a single front-loaded sentence that enumerates the core operations without filler. Every clause corresponds to a real capability, and there is no repetition of annotation or schema text.

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

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

For a 10-parameter mutation tool with zero schema description coverage, the description is too thin: it leaves identifier formats, context parameters, null/no-op semantics, and several update flags unexplained. The output schema means return values need not be described, but the input-side gaps remain substantial.

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 10 parameters. It explains the key editable fields and the volume range, and it distinguishes video blend mode from audio volume, but it does not explain the track identifier (integer vs string), project, sequence, blend_enabled, null defaults, or allowed blend_mode values.

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

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

The description states a clear verb and resource: update a track, with specific mutable properties (name, enabled/disabled, lock/unlock, blend mode, volume). It is distinguishable from siblings like add_track and update_track_item by operating on a track itself rather than track items, though it does not explicitly name or contrast those siblings.

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

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

Usage is implied by the listed operations, but there is no explicit guidance on when to use this versus add_track/delete_track/update_track_item, nor any prerequisites about project/sequence context. The video/audio split gives some conditionality but not enough to reach a clear when-to-use 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?

Annotations already declare readOnlyHint=false, openWorldHint=false, and destructiveHint=false. The description adds valuable behavior beyond annotations: move_to sets a new timeline in while keeping duration, trims preserve playback speed, and source frames are relative to clip start. It does not disclose combined-operation behavior or persistence details, but the key edit semantics are covered.

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: the first paragraph summarizes all operations, and the second paragraph adds only high-value trim semantics. 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?

The output schema means return values need not be explained, and annotations cover safety traits. But for a 15-parameter mutation tool with 0% schema description coverage, the description still omits meaningful context for several routing and selection parameters, leaving gaps an agent must infer.

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

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

With 0% schema description coverage, the description must carry parameter meaning. It does well for move_to, timeline_in/out, source_in/out, and indirectly for playback_speed and replace_clip, but leaves required 'item', 'kind', 'track', 'project', 'sequence', the version enum values, and exact replace_clip/playback_speed 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 and resource ('Edit a shot') and enumerates concrete edit operations: rename, enable, retime, move, trim, version, swap clip. This clearly distinguishes it from read/list/add/delete siblings, though it does not explicitly name alternatives like update_sequence or update_track.

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 operation list implies when to use the tool: editing an existing track item. However, it gives no explicit when-to-use/when-not guidance versus siblings such as add_clip_to_track, update_sequence, update_track, or razor, and it names no prerequisites.

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