Render a timeline

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

Annotations only provide uninformative false hints, so the description carries most of the burden. It does disclose processing behavior: every clip is scaled/padded, in/out points and speed are honored, transitions, overlays, captions, and audio tracks are layered. However, it omits operational details such as whether rendering is synchronous or asynchronous, whether the output file is overwritten, or whether there are any side effects on input files. This is a moderate level of transparency but not rich enough to fully anticipate the tool's runtime 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 compact paragraph of about 100 words, front-loaded with the purpose, then explaining the use case and timeline semantics. Every sentence adds necessary context, and there is no repetition of the title or obvious filler. It could be tightened slightly, but it is well-structured and appropriately scoped for a complex tool.

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 the tool's complexity (large nested schema, 3 parameters) and the existence of a rich output schema, the description provides strong orientation: what the tool does, how it relates to the UI, and how the timeline is interpreted. It doesn't cover encode options or output_path, but those are self-explanatory given the schema and common sense. The main gap is the lack of mention of job/asynchronous behavior, but for a script-driven entry point this is a minor omission.

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 description does not mention any of the three top-level parameters (timeline, encode, output_path) by name, so schema coverage from the description is 0%. However, the description compensates by explaining the timeline structure in prose (clips, transitions, overlays, captions, audio tracks), which maps to timeline subfields. It does not address `encode` or `output_path` at all, leaving those to the schema's own descriptions. The schema itself is very detailed, so this is adequate but not exemplary.

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 is explicit: 'Render a complete edit — clips, transitions, overlays, captions, audio — in one pass.' It names the resource (a full timeline), specifies the action (render), and clearly distinguishes itself from the sibling tools that operate on individual aspects (e.g., add_transition, burn_captions, overlay_media). The opening sentence is unambiguous and specific.

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 states this is 'the entry point for driving the server from a script rather than calling tools one at a time.' This gives direct guidance on when to use it (fully composed timeline, scripted workflow) and contrasts it with the alternative of invoking individual tools. It also mentions it matches the local UI's timeline editor structure, providing additional context for 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.