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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false), so the bar is lower. The description adds real behavioral context beyond them by enumerating exactly what is produced (beats, per-beat components with alternatives, frame budget, an install command string, a renderable Remotion file) and noting that the film type is inferred. Given no output schema, this output disclosure is valuable.

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 dense sentences, front-loaded with the core action and outputs, followed by inference behavior. Every clause carries information about the produced artifact. Slightly long but no filler or repetition.

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?

With no output schema, the description carries the return-value burden and does so well by listing the deliverables. For a 4-parameter planning tool with strong annotations, an agent has enough to invoke it correctly. A note that it plans but does not render (routing to render-video-frames) would have completed the picture.

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 75% with descriptions for brief, length, and archetype already in the schema. The description restates that it 'takes a length and a format' and infers the archetype, which corroborates but adds little syntax beyond the schema. The undocumented 'format' parameter is not elaborated on in the description either, so it does not compensate for the coverage gap.

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 (Plans) and resource (a product film) and enumerates the concrete outputs: beats, one video component per beat, frame budget, install command, and a Remotion TransitionSeries file. This is far more informative than a generic 'plan a video' and lets an agent predict the artifact. It does not, however, name or distinguish itself from the related siblings like render-video-frames or get-motion-guide.

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 implies usage by describing what a one-line brief produces and that it infers the archetype from the brief, which hints at when it fits. But it never states when to choose this over siblings such as render-video-frames, or any preconditions/ordering. Guidance is implied rather than explicit.

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