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

Annotations already flag this as a destructive, open-world write, but the description adds real substance: replacement discards the old picture, a "search" replacement always yields a different picture, and the result reports what the picture shows plus the piece count. It never contradicts the annotations. It stops short of stating reversibility or failure modes for a missing attachment/image_id.

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 purpose and the puzzle-only constraint are front-loaded, and each subsequent sentence covers a distinct source or the keep/replace rule. The prose is dense and quote-heavy, but no sentence is redundant with another.

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?

There is no output schema, yet the description says what the result reports (what the picture shows, piece count), which is exactly what an agent needs to chain calls. Combined with the source routing rules and the puzzle-state precondition, nothing essential is missing for a 6-parameter mutation.

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 100%, so both enums and all six parameters are already documented; the description largely restates the schema's own wording for "source" and "existing" ("Only the field of that source is used" appears in both). It does add one cross-field fact not in the schema — that a "search" replacement is always a different picture — which lifts it slightly above the baseline.

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 opens with a concrete verb and resource ("Put the picture of a puzzle") and immediately scopes it to the assembled image rather than question/answer images. It explicitly routes the sibling case to illustrate_items, so an agent can separate this tool from set_item_images and illustrate_items without opening a schema.

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 states the precondition ("Only for a puzzle (its state has 'puzzle')"), names the alternative for the excluded case (illustrate_items), and explains which source to pick for each situation. The "keep" vs "replace" guidance even quotes the user phrasings that justify replacement, leaving nothing to infer.

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