Create an Approved Poster

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

Annotations only declare the safety profile (not read-only, idempotent, non-destructive, open-world); the description adds the material behavior: this costs credits, it requires a pre-configured credit limit, it is approval-gated, and a planning/generating response is a pending task rather than a finished poster. This goes well beyond the structured fields.

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, all load-bearing, with the highest-stakes information ('PAID ACTION') front-loaded. No restatement of the name or 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 an async, paid creation tool with no output schema, the description covers cost, approval prerequisites, idempotent retry, and the pending-vs-finished distinction. The one gap is that it never points the agent at get_poster/advance_poster for tracking the pending task, though the sibling names are visible.

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?

With 0% schema description coverage and a nested request object, the description carries the load and does explain the key fields semantically: prompt and selection must be the quoted ones, quotedCredits must match the user-approved quote, and confirmed is effectively the 'user approved' gate. It does not explain the remaining request fields (model, vendor, quality, styleId, aspectRatio), so it is meaningful but not exhaustive.

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 (submit a quoted request that creates a poster) and flags it as a paid action up front. It implicitly ties to the quoting flow via 'the exact quoted request' but never names the sibling quote_poster, so the differentiation from quote_poster/advance_poster is left to inference.

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?

Explicit gate: submit only after the user approves prompt, selection and quoted credits, and only within the operator-configured per-poster credit limit. It also states the recovery rule (reuse the identical requestId and payload after uncertainty; never silently create a replacement task), which is exactly the when/when-not guidance an agent needs.

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