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

The description adds substantially beyond the annotations: the call is paid from the user's credits, max_credits must reflect the price the user agreed to, and an unanswered call may already be running, so list_photos should be checked before retrying. That is exactly the non-idempotent, credit-consuming side effect an agent needs to know, which the readOnlyHint/destructiveHint flags alone do not convey.

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 core action is front-loaded and every sentence carries functional information: constraints, pricing source, and retry safety. It is a dense single block with parenthetical asides that could be split for easier scanning, but there is no filler.

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 three-parameter, no-output-schema mutation tool, the description covers cost handling, input constraints, and recovery from a lost response. The only gap is that it never indicates what the agent gets back or where the resulting photo appears, though the list_photos hint partially covers discovery.

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%, so the description carries the full burden and does: photo_id is the destination photo, with_photo_id is the source subject (not a selfie, not photo_id itself), and max_credits is the price the user agreed to, with named sources for that value. All three required parameters gain meaning not present in the bare integer 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 effect: takes the main subject from another of the user's photos and inserts it into a target photo while preserving scene, framing and light. The photo_id vs with_photo_id relationship is spelled out. It does not explicitly distinguish itself from near-siblings such as replace_background or edit, which keeps it from a 5.

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 concrete when-to-use context (a subject or person cutout works well) and explicit when-not conditions: with_photo_id may not be a selfie and may not equal photo_id. It also routes the agent to get_shoot or list_photos to obtain the agreed price and to list_photos to check whether a prior unanswered call already started. It lacks direct comparison against alternative sibling tools.

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