Photo Mosaic & AI Collage Maker - Collager.ai

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is covered. The description adds useful behavioral context beyond that: the returned preview is watermarked and this is the polling companion to make_shape_collage's 'processing' state. It stops short of describing polling cadence or expiry behavior.

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?

One dense sentence that front-loads what is returned and the identifier form, then a second short sentence for usage. No filler and nothing redundant with 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?

With an output schema present, the description needn't enumerate return fields; it still signals that status and a watermarked preview come back. Combined with the explicit polling guidance, an agent has everything needed to call it correctly.

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% and there is a single parameter, so the schema fully documents the id, its pattern, and its origin. The description only echoes the id form (clg_...), adding no syntax or semantics beyond the schema; baseline 3 applies.

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 (returns) and resource (status + watermarked preview of a shape collage), plus the identifier form (clg_...). It clearly distinguishes itself from the sibling make_shape_collage, which creates the artifact this tool inspects.

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?

Explicitly names the trigger conditions: 'Use when make_shape_collage answered status "processing"' and 'or to show the collage again.' That routes the agent to this tool for polling and re-display rather than re-creating the collage, with no inference required.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so safety is covered. The description adds real domain context beyond that: each shape has a photo-count range (hearts 27-164) and photos fill a shape 'without repeats', which is a constraint an agent would not otherwise know.

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?

A single sentence, front-loaded with the verb and the sibling it serves, with no filler. The parenthetical shape list is long and dense, but every element is actionable information rather than padding.

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?

With no output schema and no parameters, the description carries the burden of explaining the return, and it does so at a content level (shape names plus photo counts). It stops short of specifying the exact return shape (e.g., whether the photo count is a single number or a range field), which is the only remaining gap.

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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline of 4 applies. The enumerated shape values are effectively the domain of the downstream make_shape_collage input, which is a useful bonus.

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 (Lists) and resource (the shapes make_shape_collage can draw), and enumerates the actual shape values, so an agent knows exactly what it will get back. It also names the sibling make_shape_collage, distinguishing it from get_shape_collage.

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?

Naming make_shape_collage makes the intended use clear: this is the reference lookup that supplies valid shape values to that tool. However, it never states explicitly when to call this versus get_shape_collage, nor any precondition, so it stops short of full routing guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds non-obvious behavioral context beyond that: the response includes example images and enumerates the available looks, telling the agent this call produces visual reference material rather than a list of text keys.

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?

Two sentences with no filler: the first defines the output, the second gives the routing rule. The purpose and the next-step guidance are front-loaded and immediately actionable.

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?

With no output schema, the description carries the return-value burden and does so by indicating the response contains example images and the enumerated style options. For a zero-parameter, read-only listing tool, nothing an agent needs to select or invoke it 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?

The tool takes zero parameters, so there is no argument syntax for the description to clarify. Baseline for a parameterless tool is 4, and nothing here misrepresents the input contract.

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 ('Shows the looks of a Collager.ai photo mosaic') and names the concrete style variants (soft classic, clean subject, stronger mosaic, uniform/mixed tile sizes). The parenthetical definition of a photo mosaic also disambiguates it from the shape-collage siblings (list_collage_shapes, get_shape_collage).

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?

Explicitly says to use it 'before start_photo_mosaic when the user wants to choose a style,' which names the downstream sibling and the triggering condition. It stops short of noting when this call is unnecessary (e.g., style already chosen), so it is clear context rather than full when/when-not coverage.

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

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.

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

Annotations already cover safety (readOnlyHint, idempotent, non-destructive, not open-world), and the description adds substantial extra context: the work happens on collager.ai, the user uploads and picks a style, the preview is watermarked, it takes minutes, and 100-2000 photos is the sweet spot. This tells the agent the tool itself performs no heavy work and what the downstream flow looks like.

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?

Three sentences, front-loaded with the core action ('Gives the link where the user builds a photo mosaic'), followed by the mechanics and then the trigger. Efficient with no filler, though the example list could be trimmed without loss.

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 zero-required-parameter, annotation-covered tool with no output schema, the description covers the return value (a link), the downstream workflow, photo-count guidance, and the trigger condition. Nothing essential to calling 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?

Only one optional parameter (occasion) with 100% schema description coverage, so the schema already fully documents it. The description's occasion-like examples (wedding, team, school year) loosely align but never explain the parameter's role in tailoring tips, adding nothing beyond the 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 concrete verb and resource: it returns the link where the user builds a photo mosaic, then defines what a photo mosaic is (one main photo recreated from many small photos). It does not explicitly name the sibling it contrasts with (make_shape_collage), so it falls just short of full sibling differentiation.

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?

The final sentence gives a clear trigger: 'Use when the user wants a photo mosaic or a picture made of many photos.' There is no explicit when-not or named alternative (e.g., shape collage vs photo mosaic), but the usage context is unambiguous.

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