render_carousel

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

Annotations only declare the generic write profile (readOnly=false, destructive=false, idempotent=false, openWorld=false). The description adds genuinely new behavior: rendering happens server-side, produces persistent media-library assets, and returns an ID rather than the images, so the caller must poll. It does not address what a re-render does to prior output or whether repeated identical calls duplicate media, which matters given idempotentHint=false.

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?

Three sentences, front-loaded with the action and artifact, then the async contract, then layout rules. No filler and no restatement of the title.

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 14-parameter, nested-object, async tool with no output schema, the description covers the essentials an agent needs: what is produced, where it lands, and how to retrieve the result. It could go slightly further on render failure behavior or how the returned ID is used beyond polling, but nothing critical is missing.

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 layout semantics not implied by the schema: slide 1 takes the cover layout, the last slide the CTA layout, and middle slides cycle content variants. That helps an agent reason about ordering and length. There is mild tension with the schema's claim that the 'type' enum pins cover/CTA, but not a hard conflict.

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?

"Render carousel slides into branded PNG images (server-side, pixel-perfect) saved to the media library" gives a specific verb (render), a specific resource (carousel slides), the output artifact (PNG in media library), and distinguishes it from siblings like generate_carousel or preview_post. The follow-up instruction to poll get_carousel_render names the related tool explicitly.

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?

It states the post-call workflow clearly (poll get_carousel_render until 'completed'), which is the main usage hazard for an async render. It also signals the input can come from generate_carousel via the schema, but the description itself never says when to use this versus generate_carousel or preview_post, and gives no 'when not to use' boundary.

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