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

Annotations already declare destructive=true, openWorld=true and idempotent=false, and the description reinforces that with '[write, queued, priced]' – telling the agent the call is asynchronous and metered, which annotations alone do not. It also states the return payload ('image_id and image_uuid') and the polling requirement. It stops short of saying what a failed or in-flight job looks like, or what the cost unit is.

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?

The bracketed traits, then the action, then parameters, then alternatives and return — well front-loaded, with no filler sentences. It is dense to the point of being run-on in the parameter clause, but every clause carries information.

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?

No output schema exists, so the description compensates by naming the returned identifiers, and it explains the async workflow and the READY-character precondition the schema cannot express. The only shortfall for a 7-parameter mutation tool is the undocumented image_title and the hand-waved image_ai.

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, the description carries the full burden and does most of it: it explains image_source_url (public https address), image_prompt (1500 char cap, '[character1]' placeholder), image_aspect (concrete allowed values, though the schema lacks an enum), and character_assets ({character_uuid: asset_id}). Gaps remain: image_title is never mentioned and image_ai is defined only by cross-reference ('as in create_character_image').

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?

The description names a concrete verb and resource ('take the picture at image_source_url and put one READY character in place of the people in it'), plus the effect on the scene ('keeping the scene, light and background'), so an agent knows exactly what will be produced. It also explicitly contrasts with the sibling for moving pictures and references create_character_image for shared sub-objects.

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 routes to alternatives explicitly: 'For a video use create_replace_video' and 'Poll with get_character_image'. It also states the precondition for the input character ('one READY character'), which is the single most likely reason a call would fail.

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