batch_create_clips

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

No annotations are provided, so the description carries the full disclosure burden — and it mostly delivers. It clearly states this is a batched export (multiple clips at once), that settings auto-load from session, that it produces a specific output spec, and that async_mode renders in background with polling. The only gap is side effects: it doesn't explicitly say whether it mutates state, overwrites existing outputs, or requires the Web UI (though async_mode mentions 'Requires Web UI running'). The precedence rule is a behavior, not just a parameter detail, and it is disclosed. Strong for a tool with zero annotation coverage.

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

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

A compact, front-loaded definition. The purpose and both usage paths appear in the first two lines; the precedence rule is a single tight sentence; the output spec is one line. No fluff, no repetition of what schema descriptions already state. Every sentence earns its place and is scannable.

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 batch tool with 8 parameters and zero annotations, the description explains the three selection modes, the precedence rule, session-state auto-loading, the output format, filtering behavior, and the async path (including that it requires the Web UI and that Claude should poll job_status for progress). The only residuals are the exact job_status polling mechanics and what happens in synchronous mode when no selection is given, but these are minor given the richness of the schema and the description. Strong coverage overall.

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

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

Schema description coverage is 100% — every parameter (including nested ones) has a description in the JSON schema. Baseline is therefore 3 even with no extra detail, and the description adds meaningful value beyond that: it explains precedence among the three way parameters, notes that clips/clip_numbers/export_selected are alternatives, and clarifies the clean_fillers default comes from studio settings. The nested per-clip fields are fully described in the schema already. The description does add semantics beyond the schema, but the schema already carries high coverage, so a 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 opens with an explicit verb and resource ('Export multiple clips at once as finished vertical shorts') and establishes this as 'STEP 3' in a pipeline, which clearly distinguishes it from its siblings like create_clip (which likely handles single clips) and export_to_davinci_resolve (which targets a different output path). The mention of resolved output characteristics (9:16 vertical crop, captions, normalized audio, H.264 MP4) leaves no ambiguity about what the tool produces.

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 spelled out explicitly: pass export_selected=true for all, clip_numbers for specific ones, or clips for custom definitions. The precedence rule ('clips wins, then export_selected, then clip_numbers') and the auto-loading from session state remove guesswork. The 'EASIEST' callout gives a direct recommendation. This is one of the most actionable usage sections possible.

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