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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds real behavioral context: the response is a browsable menu with a real example, includes per-shape photo capacities, and notes that photos fill shapes 'without repeats'. It stops short of describing response structure or error behavior, but the added value over annotations is substantial.

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, no filler, and the purpose is front-loaded before the invocation guidance. The long parenthetical shape enumeration is dense but carries genuine information about output scope.

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 input parameters and no output schema, the description carries the return-value burden itself and does so: it says what the menu contains, that examples are included, and what the photo capacities mean. An agent has everything needed to decide to call it and to interpret what comes back.

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 and the schema is an empty closed object, so there is nothing for the description to disambiguate. Baseline for a no-parameter tool is 4; the description correctly implies a parameterless, call-and-read operation.

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 (shows/lists) and resource (the menu of Collager.ai collage shapes), then enumerates the concrete shape families (hearts, numbers, words, circle, star, flower, grid, custom mask) and their photo-count ranges. It explicitly links the list to the sibling make_shape_collage, so an agent can tell the two apart without opening either 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?

Gives explicit trigger conditions: 'Call it first when the user only mentions Collager.ai, says hello to it, or asks what it can make.' This is a concrete routing rule rather than an implied one, and it positions the tool ahead of the sibling collage tools in the flow.

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 declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds useful behavior beyond that: what the response contains (example, cell count, background, how to attach photos) and the handoff sequencing to make_shape_collage. It stops short of saying whether the plan is persisted or paginated, so not a 5.

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 short sentences with the purpose, the trigger and the follow-up ordered front to back. Every clause carries information an agent needs; nothing is repeated from 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 read-only preview tool whose complex nested shape object is fully documented in the schema, the description supplies what the schema cannot: the workflow position and the carry-forward rule. No output schema exists, and while it lists the kinds of content returned, some detail on the plan output would make it fully self-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% and the nested shape object already carries examples and enum semantics, so the schema does the heavy lifting. The description only adds the rule that the same shape and background must be reused in make_shape_collage, which is a workflow constraint rather than new parameter meaning.

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 plan (shape, photo count, background) for the chosen collage, plus a real example and attach instructions. It is clearly distinguishable from make_shape_collage, which is named as the separate render step.

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 an explicit trigger (user picked a shape but has not attached photos yet) and an explicit next step (after attaching or sharing links, call make_shape_collage with the same shape and background). The alternative and the condition selecting it are both named.

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 a safe, read-only, idempotent, closed-world call; the description adds real substance on top by explaining that the user does the uploading and style selection on the external site and gets a watermarked preview in minutes. That clarifies what the tool does NOT do (build the mosaic itself), which the annotations cannot express. It stops short of stating whether the link expires or is per-user, a minor remaining gap.

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 outcome (the link) before the mechanics and the routing rule. Dense but every clause carries information; the parenthetical photo-count and audience list is slightly long but genuinely helps the agent judge fit.

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 correctly fills that gap by saying the return value is a link and describing what the user will see there. Preconditions, alternatives, and the human-in-the-loop flow are all covered, so an agent can call this correctly without further context.

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 both parameters are already documented, and the description mainly echoes the optional style/occasion semantics. It does add a small amount of meaning, e.g. that occasion is only used to tailor tips and that the site previews styles regardless, but that is largely redundant with the schema text. Baseline 3 is appropriate.

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 action (returns the link where the user builds a photo mosaic) plus a one-line definition of what a mosaic is and its photo-count sweet spot. This is clearly distinct from list_mosaic_styles and the shape-collage siblings, which are named or implied elsewhere in the description.

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?

"Call it only after the user has decided to make a photo mosaic; to show the options first, use list_mosaic_styles" gives an explicit precondition, an explicit exclusion, and the exact alternative to route to. Nothing is left to inference about ordering.

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