Plan a Video

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

Annotations already declare readOnly/idempotent/non-destructive and the description is consistent with a pure planning call. It goes beyond them by disclosing the full return shape (beats, alternatives, frame budget, install command, TransitionSeries skeleton with demo copy) and the fact that the skeleton renders with placeholder copy that must be replaced. Minor gap: no mention of failure modes when a brief cannot be mapped to an archetype.

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 what it produces, then inference/override behavior, then the workflow position. Three tight paragraphs, no filler, and the actionable instruction (load each component, replace demo copy) comes last where it belongs.

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?

There is no output schema, so the description carries the burden of describing the return value, which it does in concrete terms down to the file name and the TransitionSeries structure. Combined with the follow-up tool instruction, an agent has everything needed to call it and use the result.

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 80% and already documents brief, length, and context, but the description adds genuine semantics: archetype is inferred from the brief and can be overridden, and length/format act as overrides on the archetype's default. It does not add anything beyond the schema for the brief itself, which is fine given the schema text.

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 (plan a whole product film) plus the resource and the exact artifact set produced: beats, components with alternatives, frame budget, install command, and a src/Film.tsx skeleton. It is clearly distinct from render-video-frames (execution) and get-motion-guide (per-component docs) among the 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?

'Use it before writing a Remotion composition' gives an explicit sequencing rule, and 'Then load each component with get-motion-guide({ component })' names the follow-up tool and the hand-off. It also states that archetype/length/format are overrides of inferred defaults, so the agent knows when to leave them out.

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