vfx_bake

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

With no annotations, the description carries the burden well: it discloses file side effects and exact write paths (bakes/<out>.png, bakes/<out>.json), the recipe contents, alpha/colour-spread handling, supersampling and returned warnings plus a preview. It omits whether an existing bake with the same name is overwritten and gives no sense of render cost or time limits.

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 verb and output are front-loaded, but the body is a single sprawling sentence with triple-nested parentheses describing layouts and file naming, which is hard to parse on first read. Nothing is irrelevant, but the structure should have been split into discrete sentences or bullets.

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 10-parameter mutation with a nested values object and no output schema, the description covers the returns (paths, flipbook settings, warnings, preview) and the artifact layout thoroughly. The remaining gaps are overwrite semantics and cost, which matter for a tool that writes files.

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; the description still adds meaning the schema does not, notably the 'sharper than Roblox's 1024 cap' tiling use case and the bakes/<out>-<row>-<col> naming for tiles. It says nothing extra about ss, margin, mode, values or duration, so not a full 5.

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?

Opens with a specific verb and resource ('Renders a node into its final PNG') and enumerates the artifact variants (still, 2x2/4x4/8x8 flipbook, tiles x tiles). The word 'final' implicitly separates it from preview/render siblings, but it never names vfx_render or vfx_preview to make that distinction explicit.

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 a clear downstream step ('Upload it with vfx_upload') and implies use when you need exported assets rather than previews. It offers no explicit when-not guidance and no comparison against vfx_render or vfx_preview, leaving the agent to infer which sibling to pick.

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