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

Annotations already say non-readonly, non-idempotent, open-world; the description adds the economics that annotations cannot express: credits are held, charged only as pictures are drawn, failed draws are free, and a mismatched price returns 409 with the current one. This is exactly the disclosure a credit-spending mutation needs.

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?

One front-loaded paragraph with no filler, leading with the action and cost. Slightly run-on phrasing around 'spends credits) credits is the price' costs it a point, but nothing is wasted.

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?

With no output schema, the description still tells the agent the tool is asynchronous, how to observe completion, and how billing behaves on partial failure. What the ready lookbook payload looks like is left to get_music_video_lookbook, which is reasonable.

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 goes further by explaining that credits must equal the agreed price (price.draw.credits) and that a stale value yields 409 with the current price. It adds real semantics about the credit parameter beyond the schema.

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 plus a scope qualifier: 'Draws the pieces not drawn yet', which implicitly contrasts with redraw_music_video_lookbook_piece and redesign_music_video_lookbook. An agent can tell what this does and which sibling handles the other case.

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 concrete follow-up flow ('Poll get_music_video_lookbook until status is ready') and price-matching precondition. It doesn't explicitly name redraw_music_video_lookbook_piece as the alternative for already-drawn pieces, but the 'not drawn yet' scoping effectively routes the agent.

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