Product Aura

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

Goes well beyond the annotations: values are printed verbatim on images and persist for every later set, an empty value removes a fact, the call is free, and it returns 'the product with updated facts and missingFacts' (valuable since there is no output schema). This is consistent with the supplied readOnlyHint=false, idempotentHint=true, destructiveHint=false profile while adding persistence and cost context the annotations cannot express.

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?

Front-loaded with what gets written and where the keys come from, then the constraint, cost, and return. The example payload is genuinely useful for the nested facts object, but the single run-on opening sentence could be split for readability.

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?

No output schema exists, yet the description states the return shape (product plus missingFacts) and covers the nested facts object's key/value rules and deletion sentinel. What remains thin is the downside of not answering: it says images are made without those numbers, but not whether facts can be corrected later or which downstream calls re-print them.

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 only 50%, and the description compensates by explaining that fact keys come from missingFacts[].key, giving concrete key examples (dimensions, pack-count, key-ingredients), and defining the empty-string sentinel as deletion. The credentials example shows value formatting verbatim. product_id semantics are only implied by the return statement, not described in the description itself.

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?

Specific verb+resource: 'Saves product facts the person knows' plus a correction mode ('corrects a fact read from the label'). It anchors key naming to 'missingFacts[].key from create_product', which tells an agent exactly which keys this tool expects, though it never names edit_product as the nearest sibling for non-fact edits.

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?

Clear when-to-use: fill facts that create_product reported as missing, or fix a label-derived fact. It also states the fallback path ('Never make values up: ask the person, or skip (images are then made without those numbers)'), giving an explicit alternative to calling the tool with invented values, though it doesn't spell out when to prefer edit_product instead.

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 declare a non-read-only, non-destructive, non-idempotent, closed-world tool, and the description adds substantial context on top: default state (off), that nothing is charged when the Stripe link is issued, that the service is free, that each top-up counts as a normal pack purchase, and the exact error code returned while paused. These are behavioral facts the agent could not infer from the annotations or schema.

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 core behavior is front-loaded in the first sentence and each subsequent sentence carries a distinct rule (status read, card flow, consent, paused state) with no filler. It is dense and slightly run-on with parentheticals, but nothing is redundant.

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 5-parameter mutation tool with no output schema, the description covers the write path, failure mode, and consent requirement well. The remaining gap is the return shape when called with no arguments to check status — what the status report contains is not described.

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 only 20% (only `new_card` is documented), so the description must compensate, and it largely does: `threshold` is defined as a credits balance trigger, `monthly_max` as a per-month cap on top-ups, and `pack` as the thing bought automatically. `enabled` and the meaning of pack_s/m/l are left implicit, so it falls short of fully closing the 80% gap.

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 states a specific dual verb and resource — 'Shows or changes auto top-up' — and immediately defines the mechanism: balance below `threshold` triggers a `pack` purchase, capped at `monthly_max` per month. This is clearly distinct from siblings like buy_credits (one-off purchase) and get_credit_balance (read-only balance), so an agent can route without opening the 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 gives explicit mode selection ('Call without arguments to see the status'), a precondition (a saved card, or `new_card: true` to get a Stripe link), a consent rule ('Ask the person before turning it on'), and a blocked-state case (`available` false returns `auto_topup_paused`). It never names a sibling tool as an alternative, which keeps it just short of a 5.

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?

With readOnlyHint=false and openWorldHint=true already declared, the description adds real context beyond annotations: nothing is charged by this tool, payment happens out of band on a Product Aura page via Stripe, and the unauthenticated path returns one link per pack with an API key shown post-payment. It does not explain why the tool is non-idempotent (e.g. whether each call mints a fresh link) — the one behavioral 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 tight sentences, front-loaded with the return value and its variants, then the checkout mechanics, then the anonymous fallback — each sentence carries new information. Slightly dense phrasing around 'then it returns a link per pack' costs a little readability.

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?

The tool is a link-minting entry point with no output schema, and the description does well to sketch the returned link and the post-payment API key. But with 0% schema coverage and all three parameters optional, an agent still cannot tell what a bare call produces or whether plan/interval must be combined, leaving a real ambiguity for invocation.

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 0%, so the description must compensate, and it does partially: it decodes pack_s/m/l into 50/150/500 credits and explains that interval is month or year. It leaves the critical semantics unstated — whether pack and plan are mutually exclusive, whether interval only applies to plan, and what a call with zero arguments (required parameters: 0) returns.

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 names a specific verb+resource ('Returns a payment link') and enumerates both purchasable shapes with their exact enum values (pack_s/m/l with credit counts, creator/pro/business with month or year). An agent can distinguish this from siblings like list_packs, estimate_cost, or auto_topup without opening the 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?

Usage is implied rather than stated: it describes the checkout flow and the no-account variant, which tells the agent when the tool applies. However, it never says when to prefer this over auto_topup or list_packs, and there is no mention of prerequisites or which combination of the optional parameters is valid.

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 destructiveHint=true, readOnlyHint=false and idempotentHint=false; the description adds the crucial boundary of that destruction ('Images already being made finish as usual'), the cost ('Free'), the refund behavior, and what is returned. It stops short of stating whether the cancel is reversible or what happens on repeated calls, which matters given idempotentHint=false.

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?

Four short sentences, front-loaded with the action and scope, followed by the in-flight exception, cost, and return value. Every sentence adds a distinct fact with no repetition of the title.

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 single-parameter destructive mutation with no output schema, the description covers the affected subset, the unaffected subset, cost, refund semantics, and the return payload. Nothing an agent needs in order to call it correctly or explain the effect to a user 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 description coverage is 0% and the single parameter is an undescribed UUID, so the description carries the burden; it reinforces that the affected set is the one whose queued images are stopped but adds no format, sourcing, or validation detail. The parameter name plus 'format: uuid' makes it largely self-explanatory, so this lands at minimum viable rather than poor.

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 ('Stops the images of an image set') plus a precise scope qualifier: only those 'still waiting in the queue'. That scope detail separates it from generation/edit siblings like generate_image_set, redo_image, or delete_product without needing to name them.

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 description implies when to use it (you want to abandon queued work and recover credits) and implicitly excludes in-flight images, but it never explicitly says when to prefer it over alternatives such as check_image_set or regenerate_image, nor does it state prerequisites.

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, and closed-world, so the safety profile is covered. The description adds genuinely new context: the check is free (no credits), it evaluates per image and per set, and it emits pass/warn/info lines rather than binary failure. It stops short of saying what happens on invalid or unfinished image sets.

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, front-loaded with the action and scope, followed by the cost and return shape. Every clause carries information: rule coverage, price, and output format; nothing is filler.

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 non-destructive annotations and no output schema, the description adequately covers purpose, cost, and the shape of results (pass/warn/info per image and per set). It lacks only failure-mode behavior and explicit routing against check_marketplace_spec, which leaves a minor gap for a simple single-parameter read tool.

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 0% for the single image_set_id parameter, so the description must compensate. The phrase 'of a set' does convey that the argument identifies an image set, matching the UUID in the schema, but it adds no format, sourcing, or error semantics. With only one self-evident identifier, the gap is small but real.

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 uses a specific verb ('Checks') and resource ('finished images of a set') and enumerates the rule sources (Amazon main image, sizes, formats, Etsy 1 MB warning, Shopify limits). It does not explicitly name or contrast with the sibling tool check_marketplace_spec, so an agent must infer the split between the two.

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?

'Finished images' implies this runs after generation, which is useful implied context, and 'Free' signals no credit spend. However, there is no explicit when-to-use vs check_marketplace_spec guidance, no preconditions, and no statement about behavior when the set isn't yet complete.

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 the useful non-obvious facts that the call is free, needs no account, and returns pass/warn/fail with the measured value. It does not say what happens on malformed or oversized input, which is the remaining behavioral gap for a validator.

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 passage, front-loaded with the verb and the rule list, then the cost/account note, then the return shape. Every clause carries information; no filler or repetition of the title.

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 contract and does so ('pass, warn or fail per check with the measured value'), which is exactly what an agent needs to interpret results. Rules like 'zoom size' remain slightly underspecified in how they are measured, a minor gap for a validator.

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?

There is a single parameter with 100% schema description coverage, including accepted formats and the 15 MB ceiling. The description restates 'base64' but adds no format, encoding, or sizing nuance beyond the schema, so 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 and resource ('Checks one image (base64) against Amazon's published main image rules') and enumerates the exact rule set being evaluated. The singular 'one image' plus the rule list cleanly separates it from the sibling check_image_set, which operates on a set.

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 scope statement ('one image', base64 input) makes it clear this is the single-image path rather than the set-level check, and 'Free; no account needed' removes a common pre-call hesitation. It stops short of explicitly naming check_image_set or rate_image as the alternatives, so routing is implied rather than stated.

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 non-read-only, non-destructive, non-idempotent; the description adds genuinely new behavior: no credits are consumed, no new file is produced, and the copy becomes the target set's picked version, which implies a state change on the destination set. It does not say what happens if the destination set already has a picked version, leaving a meaningful side effect underspecified.

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 core operation, its constraints and the cost model are front-loaded in one sentence, followed by a single clarifying note. The trailing example is largely redundant with the input schema but takes only a line and does not obscure the purpose.

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 two-parameter copy tool with annotations present, the definition covers purpose, cost and destination constraints adequately. With no output schema, however, it never indicates what the call yields (e.g. whether a new generation identifier is returned), nor how an existing picked version in the target set is handled.

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 0%, so the description must carry parameter meaning. It partially does by tying image_set_id to the same product/platform/language constraint, but the example JSON only echoes the two field names and never explains that generation_id identifies the source finished image rather than the destination.

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 precise verb and resource (copies a finished image into another image set) plus the hard constraints of the operation (same product, platform and language). The 'Free: the same file' clause distinguishes it from generation siblings like generate_image_set or regenerate_image, so an agent can tell it apart without opening the 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 a concrete use case (build variant B of an A/B test) and an implicit precondition that the target set must share product, platform and language. It does not name an alternative such as pick_image_version or generate_image_set for when this is the wrong choice, so it stops short of full when/when-not 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 the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the bar is lower. The description still adds two meaningful facts beyond them: the call is free (relevant given credit-related siblings) and it returns the new folder with its id. It does not mention that repeated calls create duplicates, which the non-idempotent hint implies.

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, no filler, with the core action front-loaded and the cost/return facts following. Every clause carries information an agent would otherwise have to infer.

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 simple two-parameter creation tool with no output schema, the description covers what it does, the optional nesting, the cost, and the return shape. The remaining gap is failure behavior (invalid parent_id, name conflicts), which is minor but not stated.

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 only 50%: parent_id is documented in the schema, while name is not described anywhere. The description compensates partly by making explicit that parent_id is optional and should be sourced from list_folders, but it says nothing about the name parameter's meaning or the 80-character limit.

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?

"Creates a folder" is a specific verb+resource, and "optionally inside another one" states the nesting scope. It also points at list_folders for the parent, which orients the agent among siblings, though it does not contrast itself with any other creation tool (none exist here) beyond that reference.

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 description implies usage context by noting parent_id comes from list_folders and that the operation is free, which steers the agent away from estimate_cost/buy_credits style siblings. It does not state when not to use it, nor what happens on duplicate names or invalid parents.

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 only declare write/non-idempotent/non-destructive; the description adds real value on top: zero cost, per-image size cap of 15 MB, a cap of 5 extra images, the fact that extra angles improve accuracy, and a failure mode with prescribed follow-up. It does not address duplicate-product behavior or where the product lands, which is notable given sibling folder/move tools.

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?

Front-loaded with the creating action and input modes, and every clause carries information (limits, outputs, error path, worked example). The cost is a single very long sentence with nested parentheses that is harder to scan than it needs to be.

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: product id, the analysis fields (name, category, materials, colours, selling points, recipe, label facts), up to 5 missingFacts, and the ok flag. Only organizational behavior after creation is left unspecified.

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 already 100%, so the baseline is 3, but the description adds meaning the schema lacks: the 15 MB limit per photo, the accepted formats (JPG, PNG, WebP), that a data: URL prefix is acceptable, and that more angles improve analysis quality. The photos-vs-URL tradeoff is also made explicit, which the schema leaves implicit.

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 ('Creates a product') plus both accepted input modes (one or more photos, or a product page link) and the analysis produced. This clearly separates it from edit_product, which implies an existing product, and from list_products.

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 concrete workflow routing: the returned product id feeds answer_facts and plan_image_set, and on ok=false the agent is told to explain the problem and offer better photos before planning. It also flags the tool as free, which matters given siblings like buy_credits and estimate_cost. It does not explicitly exclude or compare against edit_product for products that already exist.

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 destructiveHint=true and idempotentHint=false, so the description's job is easier, yet it still adds real value: the effect on dependent image sets ('keep their images'), the fact that there is no credit cost ('Free'), and a required human confirmation step. That is meaningful disclosure beyond the annotation flags.

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?

Four terse sentences, each carrying a distinct fact: what it does, where the id comes from, side effects, cost, and the confirmation requirement. The destructive action and its prerequisites are front-loaded with zero filler.

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 one required parameter, no output schema, and full annotation coverage, the description supplies the missing pieces an agent needs: id provenance, downstream effect on image sets, cost, and the human-approval requirement. Only minor gaps remain around failure behavior for invalid or already-deleted kits.

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 0%, so the description must carry the load; it compensates by explaining where the brand_kit_id comes from (list_brand_kits), which is the key semantic an agent needs. The UUID format itself is enforced by the schema pattern, so no further detail is required for a single-parameter tool.

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 ('Deletes one brand kit') and points to the sibling list_brand_kits as the source of the id, which lets an agent separate it from list/read siblings. It lacks an explicit contrast to any alternative deletion path, but the scope is unambiguous.

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 a concrete prerequisite ('id from list_brand_kits') and a confirmation policy ('Ask the person first'), covering both how to prepare and when to pause. It stops short of stating when deletion is inappropriate versus other cleanup options such as cancel_image_set.

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?

Goes well beyond the annotations (which already flag destructiveHint=true, idempotentHint=false): it discloses collateral scope (image sets are removed too), what survives (downloaded images), cost implications ('Free'), a confirmation requirement, and the return value. These are exactly the facts an agent needs before committing an irreversible deletion.

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?

Five short clauses, each carrying distinct information — identity, collateral effect, non-effect, cost, prerequisite, return. Front-loaded with the action and no filler, despite the clipped telegraphic style.

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 single-parameter destructive tool with no output schema, the description covers consequences, cost, confirmation, and the return value ('Returns the deleted id'). Nothing material an agent needs before calling 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?

Schema description coverage is 0%, so the schema documents only type/format (uuid), not meaning. The description compensates by telling the agent this is a product id obtained from list_products, which is the key piece of semantic context the schema lacks. Minor gap: no note on behavior for an unknown or already-deleted id.

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 ('Deletes one product'), scopes it to a single item, and names the source of the identifier (list_products). An agent can immediately distinguish it from siblings like delete_brand_kit, cancel_image_set, or edit_product.

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 concrete usage context: the id comes from list_products, and 'Ask the person first' encodes a required confirmation step before invoking a destructive operation. It stops short of explicitly contrasting with alternatives such as edit_product or move_product, but the destructive framing makes the boundary clear.

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 it discloses the behaviors an agent actually needs: the edit produces a new version while the old one is retained (consistent with destructiveHint=false), it costs one image credit per result, and explicit/hateful/misleading instructions are refused at no cost. The cost and moderation-refusal details are not derivable from the annotations or schema and directly affect whether the agent should call it.

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 core action and scope front-loaded, examples immediately after, then cost/retention/refusal facts and the follow-up call. No filler and nothing buried.

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 non-idempotent mutation with no output schema, the description covers cost, retention of the prior version, failure mode, and the follow-up retrieval call, which is nearly everything an agent needs. The only gap is that it doesn't explain how multiple versions come back or how to choose among them, which the agent must infer from the schema and get_image_set.

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 instruction and generation_id are already documented, and the description reinforces the instruction's style ("short instruction", one sentence) with examples. The optional versions parameter (1-5 simultaneous variations) is never addressed in the description, and the phrase "the result is a new version" is singular, which slightly under-represents multi-variation use.

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 ("Changes") and resource ("one finished image") and clarifies the change scope with two concrete instruction examples ("warmer light, add a marble counter", "make the headline say Leak-proof"). It also pins down what is preserved ("Keeps the product and everything else the same"), which implicitly separates it from regenerate-style siblings, but it never names the close alternatives such as recolour_image_set or redo_image.

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?

Use context is clear: you need a finished image and a short corrective instruction, and the tool ends with an explicit next step ("Then call get_image_set."). There is no explicit when-not guidance or named alternative for cases where the agent should regenerate or recolour instead, so it stops short of a 5.

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 (readOnly=false, destructive=false, openWorld=false, idempotent=false), it discloses three non-obvious traits: only supplied fields are mutated, changes propagate to later image sets, and an empty fact value deletes that fact. It also states the cost is free and that the product is returned, though it omits failure behavior for invalid fact 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?

The mutation and partial-update semantics are front-loaded in the first two sentences, followed by cost, return value, and a compact concrete example. Every clause carries information and nothing is repeated from the schema verbatim.

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 six-parameter partial-update tool with no output schema, the description covers what can be changed, how to source fact keys, removal semantics, downstream effects on image sets, cost, and the return value. An agent has enough to invoke it correctly without further discovery.

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?

With only 67% schema coverage, the description compensates by translating friendly names to schema fields (kind→category, selling points→features, scene→setting) and adding meaning the schema lacks: features are short lines printed on images, capped at five, and facts are keyed from list_products with empty-value removal semantics. This is real value beyond the JSON Schema text.

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 specific verb and resource ("Changes a product's...") and enumerates exactly which attributes can be modified: name, kind, selling points, facts, and scene. That field-level enumeration clearly separates it from create_product, delete_product, and list_products, so an agent can select it without opening the 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 establishes clear context for use: partial update ("Only the fields given change") and the dependency on keys obtained from list_products for facts. It does not explicitly state when not to use it versus create_product or move_product, but the mutation-on-existing-product framing makes the boundary obvious.

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, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely new behaviour: the call is free, nothing is spent, and it also returns the balance. It does not cover any rate limits or response shape, which keeps it below 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?

Front-loaded with the outcome, then modes, then the routing instruction, then an example — a sensible order with no filler. The sentence fragmenting ("Free. Tell the person…") is terse to the point of being slightly clipped, but every clause carries information.

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 estimation tool with no output schema, the description covers what is returned (cost and balance), what it costs to call (nothing), and when to call it. It stops short of describing the return structure or how the estimate relates to actual charges, 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?

Schema coverage is 75%, so the baseline is 3, but the description adds real meaning by establishing that shots/locales/colours are alternative modes ("or with locales… or with colours…") rather than combinable inputs — something the per-field "Instead:" notes only imply. It also restates the shots default. The example payload reinforces the call shape.

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 — returns what an image set would cost — and immediately enumerates the three cost modes (shots, locales, colours) plus the balance. It distinguishes itself from generate_image_set, localize_image_set and recolour_image_set by framing itself as the pre-flight check for those tools.

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 instructs: "Tell the person the cost before generate_image_set, localize_image_set or recolour_image_set." That names the alternatives and the condition that selects this tool over them. The default behaviour (plan's ticked shots) is also stated, so the no-argument path is unambiguous.

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 say this is not read-only, not idempotent, and not destructive. The description adds important behavior beyond annotations: it spends credits, is all-or-nothing, and returns immediately while images take about 1–3 minutes. It does not describe failure modes or credit amounts, but the core asynchronous cost-bearing behavior is disclosed.

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 description is dense and front-loaded: purpose, shot behavior, add-to-set mode, timing, and next call are covered without filler. Every sentence contributes actionable information.

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 credit-spending asynchronous generation tool with no output schema, the description covers the essentials: cost, all-or-nothing behavior, approximate duration, and the follow-up retrieval call. It could be slightly more complete by explicitly directing agents to estimate_cost or checking credit balance, but the schema and sibling tools fill most remaining gaps.

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 high at 88%, so the schema carries most parameter meaning. The description still adds value by clarifying where shot keys come from and how to use get_image_set imageSet.moreShots when adding images to a finished set.

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 states a specific verb and resource: it 'starts making the images of an image set' and also supports adding images to a finished set. It clearly distinguishes itself from plan_image_set and get_image_set by explaining that shots come from the plan and that get_image_set is the follow-up call.

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 gives clear when-to-use context for the two modes: normal generation from plan shots and adding new shot keys from get_image_set imageSet.moreShots. It also says to call get_image_set afterward, but does not explicitly route the agent to estimate_cost or another alternative for checking credit cost.

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, and closed-world, so safety is covered. The description adds genuinely new behavior: it returns the account e-mail as well as the balance, defines the unit ('1 credit = one 2K image'), and states the call is free — none of which is in the annotations. Return shape details beyond that are absent, but no output schema exists.

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, front-loaded with what is returned, followed by the unit conversion and the cost note. Nothing is repeated from the title and no sentence is filler.

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 parameterless read with no output schema, the description covers what comes back and what a credit is worth, which is the information an agent needs to interpret the result. It stops short of describing the numeric format or whether balances can be negative/zero, a minor 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?

With zero parameters there is nothing to disambiguate, so the baseline is 4. The description correctly adds no per-parameter noise and instead spends its words on semantics of the returned value.

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 ('Returns the account e-mail and credit balance') and reveals an unexpected side output (the account e-mail) that an agent could not infer from the name. It does not explicitly contrast itself with siblings like get_credit_history or buy_credits, but the name-plus-description pairing makes the distinction clear enough.

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?

No when-to-use or when-not-to-use guidance is given, and no sibling is named as an alternative (e.g., get_credit_history for past transactions, buy_credits for adding funds). Only the trailing word 'Free.' implies it is safe to call without spending credits, which is a hint rather than 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 establish the read-only, idempotent, non-destructive, closed-world profile, so the description only needs to add context — and it does: newest-first ordering, the categories of entries returned, and the fact that the call is free. It does not describe pagination behavior or what fields each entry carries, which leaves a modest 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?

Two short sentences with zero filler: the primary behavior and entry types come first, then the practical use case. Every clause earns its place.

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 does the work of telling the agent what comes back by listing entry types and ordering, which is the essential information for interpreting results. It omits whether entries include timestamps or credit deltas and how to page beyond the limit, minor gaps for a one-parameter read tool.

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 single optional 'limit' parameter is fully documented in the schema, including its default of 50 and the maximum of 200. The description adds no further semantics about the limit or how it interacts with ordering, so the baseline of 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?

The description gives a specific verb and resource ('Lists the latest credit changes') and enumerates the entry types covered (images made, refunds, credits bought/added, expiries), which separates it from the balance-checking sibling. It never names get_credit_balance explicitly, so the differentiation is implied through the 'where did my credits go?' framing rather than stated.

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 supplies a concrete use case in the form of a user question ('where did my credits go?'), which gives an agent a clear trigger for selecting this tool. It stops short of naming alternatives such as get_credit_balance or stating when this tool is the wrong choice.

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, and non-destructive, so the safety profile is covered. The description adds genuinely useful behavior: download links expire after 15 minutes, the call is free, and a shot may receive one automatic free retry when text did not match. That is real value beyond the annotations, though the shape of the returned payload (including where 'done' lives) is not described.

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?

Front-loaded with the return contents, followed by the action guidance and the retry caveat; the sentence-length parenthetical status enumerations are dense but informative rather than filler. No sentence is pure boilerplate, though the run-on style makes it slightly harder to scan.

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 must carry return semantics, and it does a reasonable job listing statuses and check states. However, it references 'done is true' without establishing that a done boolean exists in the response, and gives no guidance on the size or lifecycle of previews, so an agent polling this tool has a small unresolved 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?

Schema coverage is 50%: the previews flag is documented in the schema itself, and image_set_id has no schema description. The description only obliquely reinforces the previews concept ('small previews of finished images') and says nothing about what image_set_id identifies or how to obtain it. Baseline 3 is appropriate since the schema does half the work and the description fills little of the remainder.

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 and enumerates what comes back: per-image status (queued, generating, done, failed), text-check state, previews, and time-limited download links. It is clearly a status/result retrieval tool, though it never contrasts itself with the near-identically named sibling check_image_set, leaving that ambiguity to be resolved elsewhere.

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 polling guidance ('Call again until done is true') plus cost expectations ('Free'), which tells the agent this is the tool to re-poll during generation. It stops short of naming alternatives such as check_image_set or cancel_image_set, so the routing between similarly named status tools is still inferred.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds value beyond them by disclosing the ordering rule (default first), the cost (free), and the default-kit inheritance behavior for new image sets. Pagination/volume limits are not mentioned, which is the only gap for a list operation.

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 ordering are front-loaded, and the second sentence carries the one non-obvious behavioral fact. The mid-sentence field enumeration is long but each field is informative given there is no output schema; slightly tighter grouping would be the only improvement.

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 full burden for return values and does so field by field, including hex palette ordering (main first) and font-name format (Google Fonts names). Combined with the default-kit semantics and cost note, an agent has everything needed to call and interpret this 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?

The tool takes zero parameters, so the baseline is 4; there is no parameter semantics to add. The description instead spends its budget on return-field meaning, which is the right allocation here.

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?

"Lists the person's brand kits, default first" gives a specific verb, resource, and ordering rule, and the field enumeration (name, website, palette, fonts, voice, logo) makes the payload concrete. It is trivially distinguishable from save_brand_kit and delete_brand_kit, the two sibling mutators on the same resource.

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 cost ("Free") and explains the consequence of the default kit: every new image set uses it unless plan_image_set names another kit or "none". That links this read to the plan_image_set decision point without spelling out an explicit "call this before plan_image_set" instruction, so a small inference remains.

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 and closed-world, so the bar is lower; the description still adds cost information ('Free') and result ordering ('tree order') that annotations do not cover. It omits empty-state behavior and whether any pagination or depth limit applies to the tree.

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, front-loaded with what is returned, then cost, then the workflow hook. Every clause earns its place and nothing is padded.

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-shape burden and does so explicitly (id, name, parentId, product count). Zero parameters plus full annotation coverage of the safety profile means 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?

The tool takes zero parameters, so the baseline is 4; there is nothing for the description to disambiguate. The field list it provides describes outputs rather than inputs, which is useful but sits outside this dimension.

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 ('Returns your folders') plus ordering semantics ('in tree order') and the exact returned fields, which cleanly separates it from siblings like list_products, list_packs and list_brand_kits.

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 concrete usage direction by pairing it with move_product and naming the organizing axes (store, platform, client). It stops short of stating when NOT to use it or how it relates to list_products, so it is clear context rather than explicit routing.

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, non-destructive, and closed-world, so the safety profile is covered. The description adds useful context beyond that: the call is free and requires no account. It does not disclose response shape or size, which matters for a tool that apparently aggregates packs, recipes, languages, and multiple pricing structures.

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 dense sentence front-loads the verb and resource, then enumerates contents and pricing details. The parenthetical pricing clauses (20% off, credits up front, 24-month validity) are business detail that could arguably be trimmed, but they are informative rather than filler.

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?

No output schema exists, so the description carries the burden of describing return values, and it does so at a category level only, with no structure, nesting, or size hints. For a zero-parameter read tool with full annotation coverage this is adequate, but an agent cannot anticipate the response's organization.

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?

Zero parameters, so the baseline of 4 applies. The description instead explains what the returned data contains, which is the relevant semantics for a no-input listing tool.

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 ('Lists the platform packs') and enumerates the concrete contents returned: shots, credit cost per shot, recipes, supported languages, and pricing tiers. An agent can tell this is a catalog/pricing discovery tool, distinct from transactional siblings like buy_credits or get_credit_balance, though it never names those alternatives.

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?

Adds clear context markers: 'Free; no account needed', which signals it is safe to call before any purchase or signup decision. It does not explicitly say when to prefer this over answer_facts or estimate_cost, but the catalog-listing scope makes the intended entry point reasonably clear.

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 and closed-world, so the bar is lower, yet the description still adds real context beyond them: newest-first ordering, exact payload contents, account-wide scope, and that the call is free. It does not mention result volume, pagination, or truncation limits on large accounts.

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 front-loaded sentence with no filler; ordering and payload are stated before the trailing cost note, and every clause carries information an agent can act on.

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 params and no output schema, the description carries the return-shape burden and does so by naming the four payload sections. It is nearly complete for a read-only lister; the missing piece is scale behaviour (pagination or result caps) for accounts with many products.

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 parameter meaning to add; the baseline of 4 applies. The description instead spends its words on return content, which is the more useful place for a no-arg tool.

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 ('Lists the account's products') and enumerates what comes back (image sets, category recipe, facts, missingFacts). The resource name alone separates it from list_brand_kits, list_folders, list_packs, and the create/edit/delete/move_product mutations, but no sibling is named explicitly.

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?

Usage is only implied: an agent infers it should call this to enumerate the account's products. There is no explicit when-not guidance (e.g. for a single product, or when a filtered listing is needed), and the 'Free' tag is the only cost-related steer versus credit-consuming siblings like generate_image_set.

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 (readOnlyHint=false, destructiveHint=false, idempotentHint=false), the description discloses the core behavioral trait the annotations cannot express: this operation spends credits, at 1 per text-bearing image per language, with text-free images copied free. It also notes each language becomes a separate image set and documents the return value (new image set ids) despite there being no output schema.

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?

It is front-loaded with the outcome first, then cost, then the required two-step workflow, then the example — a sensible order with no filler sentences. The single dense block runs slightly long and mixes cost, semantics and example in one paragraph, costing it the top score.

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 credit-spending mutation tool with no output schema, the description covers everything an agent needs: what is produced, what is preserved, the cost model, the mandatory dry_run confirmation step, what is returned, and the follow-up tool. There is no material gap left for the caller to guess at.

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 67%, and the description compensates by explaining that locales are target languages, that they each produce their own set, and by including a concrete example payload with image_set_id, locales and dry_run. It adds little about the uuid-shaped image_set_id, but that parameter is self-evident and fully constrained by 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 specific verb and resource ('makes a finished image set in other languages') and pins down exactly what changes — only the text on images is translated while numbers, units and names are kept. The amazon.com → amazon.de/fr example makes the transformation unambiguous and distinguishable from siblings like edit_image or copy_image_to_set.

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 ordered workflow: call with dry_run true first, tell the person the cost, then call without it to actually spend credits. It also routes the agent forward ('follow them with get_image_set') and points to list_packs for language codes, leaving nothing to inference about when and how to invoke it.

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 non-destructive, idempotent, closed-world mutation, so the bar is lower; the description still adds real value by disclosing that the call is free of charge and that image sets travel with the product rather than being orphaned. That child-resource side effect is exactly the kind of behavior an agent could not infer from the annotations.

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 dense sentence that front-loads the action, then the removal variant, then two short trailing facts about cost and image sets. No filler and nothing buried.

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 two-parameter mutation with no output schema, the description covers the action, both parameter intents, the omission case, cost, and the effect on child image sets. Nothing an agent needs in order 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 only 50% and product_id has no schema description at all, but the description compensates by stating product_id comes from list_products and by restating the omission semantics for folder_id in plain language. It adds the meaning of the null case rather than just repeating the field type.

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 ("puts a product ... in a folder") and covers both modes of the tool, including the removal case when folder_id is omitted. It also names the sibling sources of each id (list_products, list_folders), so the agent can distinguish it from edit_product or create_product.

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 clear operational context: where each id comes from and the exact condition under which folder_id is omitted (take out of every folder). It does not name an explicit alternative tool or a when-not-to-use case, 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?

Beyond the annotations, it discloses two useful facts: the operation costs nothing ('Free') despite sibling credit tools like estimate_cost/buy_credits, and that the underlying set code persists in file names, so naming has no effect on generated assets. The clearing-by-empty-name behavior is also disclosed. It does not address the idempotentHint=false claim (re-naming behaves deterministically in practice), a minor omission rather than a contradiction.

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, front-loaded clauses covering the action, an example, the clearing case, a side-effect caveat, and cost — essentially no wasted wording. The parenthetical '(PA-…)' is slightly cryptic but is the only marginally unclear phrase.

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?

A simple two-parameter, non-destructive mutation with annotation coverage and no output schema needs little more than this; cost, reversibility (empty name), and asset-immutability are all stated. Gaps are modest: uniqueness of names, behavior when exceeding the 80-character limit, and the response shape are unaddressed.

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 0%, so the description must carry meaning, and it does for the critical parameter: 'name' accepts a free-text label, with an example format and the special empty-string semantics that the schema cannot express. 'image_set_id' is left to its uuid format in the schema, with no hint about where to obtain it.

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?

Names a specific verb and resource ('Gives an image set a name') and immediately scopes the effect with an example ('Variant B: warm light') plus the clearing behavior for empty names. No sibling is named explicitly, so differentiation from tools like get_image_set or cancel_image_set is by purpose only rather than by explicit routing.

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?

'for A/B tests' hints at the intended context, and 'an empty name removes it' tells the agent how to undo a naming. However, there is no explicit when-to-use vs. alternative guidance (e.g., use get_image_set first to obtain the id, or use copy_image_to_set instead if a new set is needed).

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 only declare non-readonly, non-destructive, non-idempotent; the description adds the key behavioral fact that 'Every version stays stored', so the agent knows the operation is a pointer switch rather than data loss. It also lists the downstream consumers affected. It does not say how to switch back to a previous version except by re-picking, which is a minor 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?

Front-loaded with the effect of the call, followed by scope, persistence guarantee, cost, and an example — no filler sentences. The final 'Example: {...}' is slightly redundant given a one-field schema, but it is harmless.

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 single-parameter mutation with no output schema, the description covers what changes, what is preserved, what depends on the choice, where the id comes from, and cost. Only the return behavior and reversal procedure are unstated, which is a modest gap rather than a blocker.

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 0%, so the description must carry the parameter meaning, and it does: generation_id is identified as a generation id obtained from get_image_set, not an image id or set id. The inline example reinforces the single-field shape, though it adds no format detail beyond the schema's uuid pattern.

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 (make this version the one its set uses) and the exact resource/scope (per image within a set), plus what downstream artifacts follow the choice: ZIP, downloads, checks, translations. This is distinguishable from siblings like get_image_set or regenerate_image.

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 description names the source of the id ('a generation id from get_image_set') and resolves the main decision friction by stating 'Free', which tells the agent it is safe to call without cost concerns. It stops short of explicit when-not-to-use guidance or a stated path to undo the selection.

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?

Adds substantial context beyond the annotations: up-to-a-minute latency, zero credit cost, no generation yet, unfit shots dropped with reasons, per-shot credit cost, and plan.note when facts are missing. Repeating the schema's locale and brand-kit defaults is the only drag; some redundancy with the structured fields.

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?

Front-loaded with purpose and payload, and every clause carries real information (latency, cost, exclusions, defaults). The density comes at a cost: one long run-on paragraph of semicolon-chained parentheticals that is harder to scan than the content warrants.

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?

No output schema exists, so the description carries the return-values burden and does so: it names the plan structure, credits, balance and missingFacts. Only gap is that it never says how to retrieve the plan later (get_image_set / check_image_set) or what failure modes exist for an invalid product or approved-only premium format.

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?

Well above baseline: it explains how aplus_format and aplus_text interact ("fields" returns copy per image to paste into Amazon fields) and how missingFacts changes what shots are produced. It does restate a few schema-documented defaults (locale, brand_kit_id, model_* defaults) rather than adding to them.

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 ("Creates an image set for a product and platform pack") and immediately names the return payload (shot plan, balance, missingFacts). The clause "Free; nothing is generated yet" cleanly separates it from the generation siblings in the same tool family.

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 concrete routing rules: "answer_facts first to add them" for the withoutFacts gap, "see store_look" for shopify, and the brand_kit_id default/"none" override. It implies but never names generate_image_set as the follow-up step after planning, so the workflow is slightly less than fully explicit.

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 non-read-only, idempotent, non-destructive, closed-world behavior, so the bar is lower. The description adds genuine context beyond them: the exact rating values, the fixed reason vocabulary, the improvement purpose, and that the call is free of credit cost.

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 front-loaded sentence carries the action, the value mapping, and the reason vocabulary, followed by two short fragments that each add distinct information. Nothing is redundant or padded.

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, no-output-schema tool this covers the essentials — value semantics, the reason taxonomy, cost, and purpose. Only the origin of generation_id and any return behavior remain unstated, which are minor gaps at this complexity level.

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 0%, so the description carries the burden, and it does well by defining the two legal rating values and listing all six reason strings that the schema leaves as a free-form string array. The gap is generation_id, whose expected source (a previously generated image's id) is never explained.

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 — thumbs up (1) or down (-1) on one generated image — and enumerates the rating scale inline, so an agent knows exactly the action and payload. It is clearly distinguishable from siblings like send_feedback or pick_image_version.

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?

Usage is implied (rate a generated image to help improve results) and the 'Free' note tells the agent it costs no credits, which is a useful selection signal. However, there is no explicit guidance on when to prefer this over send_feedback or pick_image_version, and no stated prerequisite that the generation_id must come from a prior generation.

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, the description discloses the credit cost model, that dry_run returns cost without spending, that images without the product are copied free, that each colour becomes its own image set, and that new image set IDs are returned for follow-up. These details materially help the agent understand the operation’s side effects and downstream flow.

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 description is information-dense and front-loads the purpose, cost caveat, and example. The sentence structure is somewhat compressed with parentheticals and semicolons, but every sentence carries actionable information and nothing is redundant.

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 multi-step, credit-spending image-generation tool with no output schema, the description covers purpose, cost behavior, dry-run workflow, return value, and follow-up action. An agent has enough information to invoke it safely and 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?

With 50% schema coverage, the description compensates well for key parameters: it explains colours, hex, photo_base64, dry_run, and all_images behavior. It does not explain the nested 'note' field or the maxItems limit, but it adds substantial meaning beyond the schema for the parameters that drive correct invocation.

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 states a specific verb and resource: it makes a finished image set’s main image in other product colours. It also clarifies the exact scope ('only the product’s colour changes, the scene and text stay') and the variant behavior ('all_images true makes every image'), which separates it from generic image-editing tools.

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 description gives clear when-to-use context ('for colour variations and swatches') and explicit procedural guidance: call dry_run true first, report the cost, then call again without it. It does not name sibling alternatives or state when not to use this tool, but the usage sequence is unambiguous.

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?

With annotations declaring a non-readOnly, non-idempotent mutation, the description still adds meaningful behavior: the call is free, it is quota-limited (3/image plus a monthly account allowance), and it returns the new image id. The quota detail is especially valuable since a non-idempotent retry consumes allowance, and the description implies but doesn't state that retries cost quota.

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?

Front-loaded with purpose, then limits, then fallbacks, then parameter guidance and an example — a sensible information hierarchy with no filler. The prose is somewhat compressed and run-on, but every sentence carries operational content.

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-required-parameter mutation with no output schema, the description covers cost, quota limits, fallback tools, return value (new image id), and the input-gathering step. An agent has everything needed to decide and call correctly without guessing.

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 67%, and the description compensates by telling the agent to pass the user's own words as note and giving a full worked example covering all three required parameters. It does not explain the reason enum values beyond what the schema already lists, so it is incremental rather than exhaustive.

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?

A specific verb and resource plus the exact failure conditions it targets (product shape/label/colour/logo mismatch or wrong text). This makes it trivially distinguishable from regenerate_image and edit_image, which are named explicitly as the paid alternatives.

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 when-to-use condition, hard limits (3 per image, monthly allowance per account), and a named fallback (regenerate_image or edit_image at 1 credit) for when those limits are hit. It also instructs the agent to ask the user what is wrong first, which is actionable context, not just background.

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 non-read-only, non-idempotent, non-destructive behavior, but the description adds crucial context beyond them: each version costs the original image's credits (usually 1), new versions are placed next to the old ones, and it returns new generation ids. It does not cover failure modes or concurrency, but the cost and placement details are the important additions here.

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?

Four tight sentences, front-loaded with the core action, then cost, exclusions, and return flow. No filler or repetition.

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 credit-consuming generation tool with no output schema, the description covers what it does, what it costs, what it returns, and what to call next. It is complete enough to invoke correctly, with minor room for error-handling detail.

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 documented structurally. The description still adds meaning by clarifying that versions are 1–5 new versions made at once and that each one is billed at the original image's credit cost, which the schema does not state.

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: makes one image of a set again with the same prompt as 1–5 new versions. It explicitly distinguishes itself from edit_image (not for the main image on white) and names the sibling to use for that case, so an agent can tell the tools 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 when-to-use (to pick the best version via pick_image_version), when-not-to-use (not for the main image on white; use edit_image), and the expected follow-up call (get_image_set). Nothing is left to inference.

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 (readOnlyHint=false, destructiveHint=false, idempotentHint=false), the description discloses partial-update semantics (only fields sent change), that a website import scrapes the brand first, a human confirmation workflow, that the operation is free, and plan-dependent quota caps. It also states what is returned, which matters because no output schema exists.

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 create/update distinction is front-loaded and the example is placed last where it is useful. Some sentences are dense and multi-clause, and the aside about how the image model consumes fonts is contextual padding, but nothing is genuinely redundant.

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 12-parameter, zero-required tool with no output schema, the description covers the create/update modes, the import workflow, cost, quota, and return shape. Gaps remain around failure modes (bad logo payload, quota exceeded behaviour) and the dangling fontSampleUrl reference, but an agent has enough 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 92%, so the baseline is 3, but the description adds cross-parameter meaning the schema cannot express: brand_kit_id switches create vs update, and website only triggers a site read on a new kit. It also explains fonts_confirmed as a human-verified gate rather than a plain flag. One weak spot: it references a fontSampleUrl field that does not exist in the schema, which could mislead.

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 first clause names a specific verb and resource and immediately splits the two modes: create when no brand_kit_id, change when one is given. An agent can distinguish this from list_brand_kits and delete_brand_kit without opening any 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 gives concrete conditional guidance: with website and no brand_kit_id, read the brand from the site, show the person what was found including fontSampleUrl, then set fonts_confirmed true once they confirm. It also states the plan-based kit limits, which tells the agent when the call will fail. It stops short of naming sibling alternatives (e.g. use list_brand_kits to find an id), so it is strong but not exhaustive.

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=false, destructiveHint=false, idempotentHint=false and openWorldHint=false, so the safety profile is covered. The description adds one non-obvious behavioral fact — that the call is "Free" — which matters in a toolset full of credit-charging siblings like buy_credits and auto_topup. It says nothing about whether feedback is attributed/anonymous, rate limits, or what happens on repeated sends.

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 sentence with the destination front-loaded and the content hint in parentheses; "Free." is a compact, high-value addendum. Nothing is redundant, though the fragment style is slightly terse.

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 one-parameter fire-and-forget tool with no output schema, the essential information is present: what it does, where it goes, what to write, and that it costs nothing. Gaps remain around attribution, confirmation behavior, and the message length limit, which an agent would otherwise only learn from the schema.

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 single parameter has zero schema description coverage, so the schema provides only type and length bounds. The description partially compensates by specifying what the message should contain (what worked, what did not, what is missing), but gives no guidance on tone, formatting, or that the limit is 5000 characters.

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?

"Sends feedback to the Product Aura team" is a specific verb plus resource plus destination, and the parenthetical clarifies the expected content. No sibling tool overlaps with this action, so differentiation is implicit rather than stated.

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 parenthetical ("what worked, what did not, what is missing") implies when this tool is appropriate, i.e. any time the user wants to report on product experience. There is no explicit 'use this instead of X' guidance, though no obvious alternative exists in the sibling list.

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 mark this as a non-destructive, non-idempotent write with no open-world access; the description adds genuinely new behavior context by disclosing that it is "Free," that it doubles as a read when called empty, that updates are partial ("send only the fields to change"), and that it returns the saved look. It does not say what happens to fields omitted from a partial update or how reference-image replacement/removal interacts, which is the remaining gap for a non-idempotent write.

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?

Front-loaded with purpose, then scoping, then the read/write instruction, then a compact worked example — no filler sentences. The middle clause about brand kits and "own: false" is dense and slightly convoluted, but it is information-dense rather than redundant.

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 an 11-parameter, dual-mode tool with no output schema, the description covers purpose, mode selection, scoping, cost, and a return hint ("Returns the saved look"). Missing are the merge semantics of omitted fields and any detail on the reference-photo/remove_reference interplay, but neither is fatal for correct invocation.

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 already 91%, so baseline is 3; the description earns above that by explaining the scoping semantics of brand_kit_id (a brand without a look, and a brandless set, fall back to the account look) and by tying the fields together into a worked example with backdrop_color and ratio. It leaves several fields (remove_reference, reference_image_base64, faces, skin_tones) to the schema alone, which is reasonable given the high coverage.

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 pair and resource ("Shows or changes the store look") with the domain it applies to (shopify-pack images), and scopes it per brand kit vs. account-level look. An agent can distinguish this from list_brand_kits / save_brand_kit / delete_brand_kit without opening any 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?

Explicitly gives the two calling modes: "Call without fields to see it; send only the fields to change," which tells the agent exactly how to make this a read vs. a partial write. It also explains the brand_kit_id selection rule and the account-level fallback. It stops short of naming sibling alternatives (e.g. save_brand_kit) for related look/brand operations.

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