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

Beyond the annotations (destructiveHint=false, openWorldHint=true), the description discloses operationally important traits: the preview is watermarked, the result id is a private handle valid 30 days, photos and results are deleted after 30 days, 1-300 photos are accepted, and fewer photos than cells causes repetition. It also warns that building can take up to a minute and can return a processing status, which is essential for correct async handling.

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 primary use cases are front-loaded, followed by input guidance and then behavioral caveats, so the ordering is sensible. It is dense and long, but the sentences each carry distinct information (triggers, inputs, repeat rule, retention, watermark, async fallback) rather than restating the schema.

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 nested-schema, async-generation tool this covers everything an agent needs: how to supply photos two ways, quantity limits, the watermarked-preview/paid-download distinction, the 30-day retention, and the polling fallback. Since an output schema exists, the description is not obligated to enumerate return fields, and its handling of the result lifecycle is more than sufficient.

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, but the description adds genuine meaning by disambiguating the two photo inputs (public links go in photo_urls, attached chat files in photos) and by stating the 1-300 photo range and the repeat behavior when photos are scarce. It does not add syntax detail for gap_pct, background, or the shape sub-fields, which the schema already covers.

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 (builds) and resource (photo collage) plus the supported shape families (heart, number, word, star, flower) and the output (watermarked preview), which lets an agent match the user's request without reading the schema. It also names sibling tools (get_shape_collage for polling, list_collage_shapes for options), distinguishing itself from both.

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?

Explicit trigger phrases are given: heart collage, birthday/anniversary number collage, 'photo collage in the shape of ...', collage from several photos. It also states the follow-up path when status is still processing (call get_shape_collage with the id) and points to list_collage_shapes for the option set, covering both when to use and what to do next.

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