apply_render_batchValidate a reviewed digest plus explicit confirmation, then submit one native render batch of images; no retries.
Validate the same reviewed digest plus explicit confirmation, then submit one native batch. Direct create_batch also needs confirmation but does not require a digest. No retry.
| Name | Required | Description | Default |
|---|---|---|---|
| account | No | ||
| confirm | No | ||
| payload | No | ||
| payload_file | No | ||
| preview_sha256 | Yes |
Changes observed during successful MCP inspections.
v2.0.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, idempotentHint=false, openWorldHint=true. The description usefully adds that explicit confirmation is required and that there is "No retry", which sharpens the non-idempotency warning. It stops short of stating what the submission actually creates/destroys or any cost implications, so it only partially exceeds the annotation baseline.
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 short sentences, front-loaded with the primary action and followed by sibling contrast and the retry caveat. Tight and waste-free, though the phrasing is telegraphic rather than explanatory.
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 destructive, non-idempotent tool with deeply nested payload objects, 0% schema coverage, and no output schema, the description is too thin. It omits the preview->apply workflow relationship, the payload vs payload_file choice, and what a successful submission yields, all of which an agent needs to call this correctly.
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 5 parameters. The description touches only two of them -- the digest (preview_sha256) and explicit confirmation (confirm) -- and says nothing about account, payload, or payload_file, or why both an inline payload and a payload_file exist. The bulk of the parameter surface is undocumented in both schema and description.
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 ("validate ... then submit one native batch") and explicitly distinguishes itself from the create_batch sibling by the digest requirement. It does not name preview_render_batch, which is the presumed source of the digest, so the sibling differentiation is only partial.
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?
Names an alternative (create_batch) and the exact condition that separates it ("does not require a digest"). However, it never explicitly states the prerequisite step of calling preview_render_batch first -- the agent must infer "the same reviewed digest" from context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.