split_clip_tool

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

No annotations are present, so the description carries the full burden, and it only partially discharges it. It discloses the mechanism ('Submits SplitAtTime on the document plane') and that it mirrors the Studio blade action, but says nothing about whether the operation is destructive/reversible, whether it requires a specific session or edit mode, or what transcript/join state results. For a mutation tool with zero annotation coverage this is a notable gap.

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

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

Front-loaded with the core action, followed tightly by parameter behavior, and sized at three short sentences with no filler. The closing 'same path as Sharecut Studio blade' remark is marginally useful context but slightly redundant against the preceding mechanism sentence.

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

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

An output schema exists, so return values need not be described, and the description does cover the central targeting decision. But with 0% schema coverage and no annotations, an agent still lacks project_path semantics and the post-split effects (new clip boundaries, edit-history interaction), leaving it only minimally adequate for a 5-parameter mutation 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, and it does for the majority of parameters: it clarifies at_time as a timeline timecode and explains the fallback chain among track_ids, track_id, and speaker, including the default of all dialogue tracks. project_path — needed to target the document — is left completely unexplained, which keeps it below a 5.

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

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

The first sentence gives a concrete verb ('Split') plus resource ('clip(s)') plus the operative parameter ('at a timeline timecode'), which distinguishes it from trimming, moving, or range-cut siblings. It never names an actual sibling tool (e.g., cut_time_range_tool or trim_clip_edge_tool) to draw the boundary explicitly, 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 description explains the track-targeting logic ('Pass track_ids for multi-track blade cuts. When omitted, uses track_id / speaker, or all dialogue tracks'), which is real invocation guidance. However, it gives no when-to-use / when-not-to-use versus the many related edit tools (cut_time_range_tool, trim_clip_edge_tool, ripple_delete_tool), and no prerequisites, so usage is only implied.

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