Select Clips By Pattern

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

The description discloses that the operation modifies selection state but does not alter the timeline ('without changing the timeline') — a meaningful behavior beyond the annotations, which only provide generic flags (readOnlyHint=false, destructiveHint=false). It also mentions the return of a selection count alerting the agent to an output value. No contradiction with annotations.

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

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

Two sentences with no filler. The primary action is front-loaded, and the example sentence is both illustrative and practical. Every word earns its place, making it an efficient definition.

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

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

For a tool with 13 parameters and an output schema, the description adequately complements the schema by giving the overall selection pattern intent and the key side-effect of not changing the timeline. It does not detail every parameter (schema handles that) but covers the essential outcome and usage context. Minor gaps: it does not explicitly state that selection is replaced by default, though the add_to_selection parameter description does, so this is acceptable.

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 100% schema description coverage, the parameter meanings are fully documented in the schema. The description summarizes them as 'optional name, duration, time-range, track, and enabled filters,' which adds no new information beyond a high-level grouping. It does not compensate or extend the schema, but given full coverage, the baseline of 3 is appropriate.

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 precisely states the tool's function: selecting every Nth clip with an offset, constrained by optional filters, and reading back the selection count. It also includes a concrete example ('select every other clip on V1') and distinguishes from other selection tools like select_clips_by_name or select_all_clips by its pattern-based approach. The verb 'select' is specific and the scope is clearly defined.

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 identifies the target use case: repetitive pattern selections ('select every other clip on V1') and says it operates 'without changing the timeline.' However, it does not explicitly state when to use this tool over selection siblings or mention any when-not conditions. The context is clear enough for an agent to infer typical usage but lacks explicit routing to alternatives.

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