render_edit

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

Annotations only declare non-readonly/non-destructive/non-openworld, so the description carries real burden and delivers: it is asynchronous ("as a job"), constrained ("One render of a name runs at a time"), consumes the clean voice once, and forbids using a finished edit as input. It does not explain what rendering destroys or overwrites or what the job result contains, but the added behavioral context is substantive.

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 the core action, but the body is a run-on of parenthetical fragments and embedded field lists that are hard to parse on first read. Much of it earns its place given the complexity, yet it could be tightened and ordered more clearly.

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 6-param tool with nested objects and no output schema, the description covers the recipe/changes distinction, the concurrency constraint, and the handoff to publish_edit, and hints at the async return ("a job"). It leaves open what the job result looks like and how to retrieve it, but the workflow is essentially complete.

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 already 100%, so baseline would be 3, but the description adds meaning beyond the schema: it enumerates recipe fields (name, cut, frame shapes, over, music, sfx, steps, cover), ties cut to rough_cut, and explains merge-patch semantics including list replacement and null removal. These are genuine additions rather than repeats.

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+resource ("Build an edit from a recipe") and frames the operation as producing a job, which distinguishes it from sibling publish_edit and check_edit. The additions "as a job, and check it" and the field-level recipe walkthrough make intent clear, though the sentence is dense enough that the core action is slightly buried.

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?

Clearly routes the agent: recipe for a first version, base+changes for a next version, and names the follow-up step ("Returns a job; then publish_edit"). It even gives an operational rule for comparison ("to compare two options, give the second a new name"). It stops short of explicit when-not-to-use or a contrast against get_edit_recipe/check_edit.

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