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

Beyond the annotations it discloses the traits that actually matter for a call: the current image is replaced, the uploaded file itself is not kept, accepted formats with a minimum 512 px short side and 15 MB cap, centering when crop is omitted, and no plan requirement. The idempotentHint=true annotation is reinforced by the replace semantics described in prose.

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?

Dense and front-loaded, with the primary action first and constraints after. It is weakened by a run-on opening sentence with a missing period ('...in lists The artist image...') and by mentioning a CLI upload path that does not correspond to any parameter here.

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 mutation tool with a nested crop object and no output schema, the description covers formats, dimensions, size limit, crop coordinate system, default behavior, replacement semantics, and plan requirements. Nothing needed to invoke it correctly is missing.

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%, yet the description still adds real meaning: it explains that x/y is the top-left corner of the square, that size is relative to the image's short side, and that omitting crop centers the square, plus format and size constraints absent from the schema. That is meaningfully more than restating the parameter descriptions.

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 ('Upload or replace the artist's image') and pins down the exact field it affects (image_url on the artist). It also disambiguates from the character/video tools by saying the image is never shown to a model and that videos use list_characters, so an agent can rule out the wrong family of tools 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?

Clearly conveys when to call it: to upload or replace the artist picture, optionally with a crop, and notes 'Works without a plan' which removes a prerequisite the agent might otherwise assume. It never names remove_artist_image as the alternative for deletion, so the exclusion half of the guidance is implicit rather than stated.

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