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

The description adds meaningful behavior beyond the annotations: renders go through the Scene composition under the hood, passing node_id attaches the render automatically, it republishes a live form, and wait=true blocks while wait=false returns a job ID. It also warns that a render is not done until attached to the node. These details align with the destructiveHint=true annotation and clarify side effects.

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 longer but every section earns its place: purpose, prerequisite call, tool-selection routing, and side-effect warning. It is front-loaded with the core purpose and keeps the most important behavioral guidance near the end without 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?

For a complex tool with 8 parameters, nested controls objects, output schema, and many siblings, the description covers selection criteria, workflow ordering, side effects, and async behavior. Nothing an agent needs to correctly call this tool is missing; return values are already covered by the output schema.

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 100%, so the baseline is 3, but the description adds useful context: controls are template-specific and discovered via clipform_list_video_templates, and node_id/form_id together trigger automatic attachment. The prose about 'small controls object' and the skip-manual-steps warning reinforces parameter intent beyond the schema fields.

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 a specific verb and resource: 'Render a curated video template ... to MP4 or PNG from a small controls object', and immediately distinguishes it from hand-assembling Scene layers. It also names sibling alternatives like clipform_generate_video and clipform_render_composition, so an agent can tell them apart without opening their schemas.

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?

Explicit when-to-use guidance is provided: reach for a video template first for form/quiz beats, use clipform_generate_video for narrated/audio-synced montages, and use clipform_render_composition only when neither fits. It also gives a concrete workflow — call clipform_list_video_templates first — and explicitly tells the agent what not to do (don't poll clipform_check_render, don't manually chain upload+attach).

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