generate_video

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

With no annotations, the description carries the full burden and does disclose meaningful behavior: the result is saved to the workspace, optionally imported into Krita as an animation layer stack, and 'Generation can take several minutes' warns about long latency. It does not say what is returned (path? document handle?), what happens on backend failure, or whether partial artifacts are left behind.

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-loads the core action and side effects in the first sentence, then uses compact labeled fragments for backend, camera and style. The parenthetical asides and trailing '(No video model? ...)' note make it denser than ideal, but nearly every clause carries distinct information.

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 an 18-parameter generative tool with no annotations and no output schema, the description covers the workflow and backend routing well but omits return values, resolution/duration parameter behavior (width, height, seconds, max_frames) and the meaning of path/extra. An agent could call it with defaults but would be guessing on several knobs.

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 0% across 18 parameters, so the description must compensate, and it does for the high-ambiguity ones: backend, use_canvas, camera (full enumerated list of moves), style, character, model. However path, extra, width, height, seconds, max_frames and negative_prompt are never explained, leaving roughly half the surface undocumented.

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 and resource ('Make a video with a video model') plus the full lifecycle: saved in the workspace and by default opened in Krita as an animation. It also differentiates itself from siblings by naming camera_move as the local no-model alternative and by referencing generate_image semantics for style.

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?

Gives concrete selection rules: use_canvas=true means image-to-video for most backends and background-behind-avatar for HeyGen, and per-backend requirements (heygen needs script + avatar_id + voice_id; replicate/fal need a model id). The fallback 'No video model? camera_move animates the picture locally' names an alternative with its condition, but there is no explicit statement of when not to use this tool (e.g. cost/quality tradeoffs vs. render_video or import_video).

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