streetshirts

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

Annotations already declare destructiveHint=true, idempotentHint=false, and openWorldHint=true, and the description adds no context on what gets overwritten, whether the session design is mutated, or auth/capability implications. The only behavioral content is the otherwise opaque warning about confusing an upload with an existing-image edit target.

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 no filler, and the core action is front-loaded. The final sentence is terse to the point of being hard to parse, which costs a point.

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 destructive, open-world mutation with a large aliased options object, the description is thin: it neither warns about side effects on session content nor explains the placement/coordinate options that distinguish correct calls. Schema coverage compensates for parameters, keeping it at minimum-viable rather than inadequate.

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% and the nested placement/asset semantics are documented in the schema itself, so the baseline of 3 applies. The description adds nothing about the very large options surface (coordinates, scale, placement spaces, asset reuse) beyond what the schema states.

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: adding uploaded or existing artwork to an area. This clearly separates it from add_text, add_keyline, and replace_image in concept, though it never names a sibling 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?

'Use the returned asset or the supported imageFile transport' gives a routing hint for two input paths, and the last sentence hints that this is not the same as an existing-image edit (replace_image). However, no sibling is named and no explicit when-not conditions are given, so selection still requires 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?

Annotations already declare destructiveHint=true, openWorldHint=true, and idempotentHint=false, so the safety profile is covered. The description adds meaningful behavioral detail about mode-dependent colour behavior and width defaults, though it does not itself explain the destructive overwrite risk noted in the 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?

Three short sentences, front-loaded with the core action and followed by mode guidance. Every sentence carries useful information and there is no redundant 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?

The description is sufficient for invoking the tool: it explains the target, the two border modes, colour format, and width behavior. Annotations and schema cover the destructive nature, nested options, session token privacy, and required fields, so only minor contextual gaps remain.

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 the schema already documents all parameters. The description reinforces borderMode and borderWidthMm semantics, especially the 3mm default and explicit-width requirement for high_contrast, but adds little beyond the schema's existing parameter descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: apply a keyline to explicit elementId and areaId. It is clear what the tool does, but it does not differentiate this tool from any sibling or name an alternative border-related operation.

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 provides useful mode-selection guidance for thin_detail versus high_contrast, but it does not say when to use add_keyline versus other tools or when to avoid it. Usage is implied rather than explicitly scoped against alternatives.

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=false, destructive=true, openWorld=true, and idempotent=false, so the safety profile is covered. The description adds useful behavioral context beyond that: it creates a separate object, preserves the user's exact wording, and warns against reusing an elementId. It does not explain the exact destructive scope, but annotations carry that burden.

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 three tight sentences with no waste. The core action is front-loaded, followed by the exact-wording constraint and the key alternative to update_text.

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 creation tool with a large nested options schema, the description covers the essential semantics: new separate object, preserve wording, and use update_text for edits. The schema is fully described, so parameter detail is not missing, but the description does not mention the returned new element ID or destructive/session caveats, which would improve completeness.

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 the schema already documents the parameters in detail. The description mentions the specified print area and existing text/font/style options, but it does not name parameters or explain placement, coordinateSpace, or the many option aliases. The baseline of 3 is appropriate because the schema does the heavy lifting.

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: create a separate new text object in a specified print area. It also explicitly distinguishes this from update_text, so an agent can tell whether to add a new object or edit an existing one.

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 explicit usage guidance: do not reuse an existing elementId, and use update_text to edit an existing object. This names the key alternative and the condition that selects it, leaving little ambiguity for the core add-vs-edit decision.

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, destructive, open-world and non-idempotent; the description adds genuinely new context: the image is illustrative, the saved design remains authoritative, results may come back pending, and a bounded allowance is consumed. It does not explain what the response contains (image URL, pending handle), which keeps it from a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tight sentences, front-loaded with the action, then the authority caveat, then the async/allowance note. No filler, though 'may return pending work' and 'bounded allowance' are compressed to the point of being slightly vague.

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 mutation-style tool with no output schema and a large free-form nested options object, the description covers the important semantics (non-authoritative output, pending results, quota) but never characterizes the return value or how to obtain the finished image, leaving a real 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 description coverage is 100% and the schema itself documents subject, sessionToken, requestId and the nested options blob (including overwrite and public-URL-fetch caveats). The description adds no parameter-specific meaning, so the 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: render the current design being worn via an AI photoshoot, plus a clarifying caveat that the output is illustrative only. It does not name a sibling (e.g., preview_design) to disambiguate, so it falls short of a 5.

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: 'show the current design being worn' suggests a mockup/visualization use case, and 'illustrative image; the saved garment design remains the print authority' tells the agent not to treat the result as the source of truth. There is no explicit when-to-use vs. preview_design or generate_artwork.

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 useful behavior beyond annotations: coordinateSpace semantics, preserving y and other geometry during horizontal centring, and separation of text alignment from box position. However, despite destructiveHint=true, it does not describe what may be overwritten or mutation consequences; the schema notes overwrite risk, but the tool description itself omits that important behavioral context.

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 front-loaded sentences, each carrying a distinct point: the alignment mechanism, a centring example, the text-versus-box distinction, and a preservation caution. There is no filler and the most important constraint appears first.

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 complex, open-world, destructive tool with no output schema, the description covers the essential calling semantics and preservation behavior. It is less complete on mutation consequences, but the destructive annotation and rich input schema supply much of that missing context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already documents most parameters, but the description adds real meaning with a concrete placement example ({x:0.5}) and explanation of coordinate-space behavior. It does not explain many alias or batch fields, but those are covered 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 action (align the target element) and mechanism (explicit placement coordinates in the existing coordinate space), and distinguishes it from text alignment. It does not explicitly contrast with nearby siblings like move_element, resize_element, or rotate_element, so sibling differentiation is partial.

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?

Explains that an instruction alone does not set alignment, gives a concrete print_area centring example, and advises preserving intentional off-centre placement unless the user requests a change. It lacks explicit naming of alternative tools for repositioning, but the usage context and a key when-not condition are 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?

The description adds real behavior beyond the annotations: edits are applied in order with state passed between them, one final preview is rendered, and content 'may overwrite or delete' (the annotations already declare destructiveHint=true, so this is additive reinforcement rather than the only signal). It does not say how failures mid-batch are handled, which matters for a destructive, non-idempotent tool.

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 sentences, front-loaded with the distinction that matters most (batch vs standalone), then capability list, then input rules, then exclusions. The middle capability enumeration partially duplicates the enum list in the schema, but the ordering is sensible and there is little 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 tool with 47 enum branches, no output schema and destructive semantics, the description correctly delegates detail to the schema branches while covering ordering, single-preview rendering, shorthand limitations and excluded operations. It does not describe what the response contains per item or whether partial success is reported, which is the 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 100%, so baseline is 3; the description earns above that by adding a constraint the schema implies but never states — only explicit elementId/areaId with native text/asset/placement/options objects are accepted, and standalone shorthand is not normalized. It also points the reader to the per-branch mapping between enum names and their standalone counterparts.

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 ('Apply an ordered list of the individually exposed design tools to one design') plus the key scope trait: state is chained between edits and only one final preview is rendered. An agent can distinguish it from single-operation siblings like move_element or delete_element 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?

Explicitly routes away from the batch for uploads, product selection, variants, saving, checkout and email, and warns that standalone workflow shorthand is not normalized inside a batch. It does not spell out the inverse case (when a batch is preferable to two standalone calls beyond the single-preview hint), so it falls short of the highest bar.

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, openWorldHint=true and non-idempotent, and the description corroborates them with 'Edits can overwrite content' and the clarification that this is not an arbitrary external-tool dispatcher (consistent with openWorldHint). It adds real context beyond annotations — recipe-based compound repairs and the instruction to preserve the user's exact wording and target element/print area — though it does not describe the response or failure behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action, then scope boundaries and exclusions — a sensible order. The capability enumeration partly duplicates the sibling tool names and is the densest part, but it earns its place by telling the agent which intents this dispatcher absorbs.

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 broad, high-parameter dispatcher with nested objects and no output schema, the description supplies the essential framing: what it covers, that it mutates and can overwrite, that operation selects a recipe, and which tools to use instead. The remaining gap is return/verification behavior, which matters given destructiveHint=true and the availability of preview_design and validate_design.

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 baseline is 3, but the description adds meaning the schema lacks: 'operation selects a design recipe, including compound image/text repairs' explains the otherwise undocumented `operation` field, and 'Preserve the user's exact instruction and intended element/print area' guides how to fill the free-form instruction and element/area targeting. The many advanced/alias fields remain unexplained, so it stops short of 5.

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 ('Apply the existing natural-language edit to the current design') and enumerates the capability domains it covers (text, image replacement, sizing, positioning, background removal, crop/flip, contrast, keyline, emoji). It explicitly distinguishes itself from the individually named sibling tools and from upload/generation/photoshoot/email/checkout tools, so an agent can place it in the toolset 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?

Explicit exclusions are given ('Use the separate upload, artwork-generation, photoshoot, email and checkout tools for those actions') and the tool is scoped away from being a generic dispatcher. However, it says the covered capabilities 'also have individually named tools in this list' without saying when to prefer change_design over add_text/update_text/crop_image etc., leaving the primary routing ambiguity unresolved.

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 key contribution is the mitigating fact 'Existing artwork is preserved' plus the confirmation checkpoint before saving/checkout. It still omits that supplied design patches can overwrite session content and that openWorld rendering may fetch external URLs, but against full annotation coverage the added context is solid.

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 the core action, then the preservation guarantee, then the operational caution. No filler, though 'Use live product values' is slightly vague for the space it takes.

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 mutating session-edit tool with a heavily documented schema and full annotations, nothing essential is missing: it covers scope, preservation of artwork, and the confirmation gate before persistence. Return-shape detail is legitimately delegated to the session/catalogue payload described in 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?

Schema description coverage is 100%, so the baseline is 3. The description names the editable dimensions (product, colour, sizes, quantities, print areas) but does not clarify the size/sizes and color/colour alias pairs, the meaning of areaId versus printAreas, or what the nested items/product objects accept.

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 pair ('choose or change') plus the exact resource set: product, garment colour, sizes, quantities, print areas. An agent knows this is the configuration-editing tool, distinct from creation tools like create_design or discovery tools like discover_products, though 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?

'Use live product values; confirm final sizes and quantities before saving or checkout' implies sequencing (use before save_design/create_checkout) but never states when to pick this over change_design or when to run discover_products first. Usage is inferred from the workflow hint rather than spelled out.

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 meaningful behavior beyond annotations: it does not pay or place an order, and it should only be used when the user wants a purchase link. It also explains design omission and exact-design-object requirements, though it does not fully explain the destructive session-overwrite implication already hinted by destructiveHint=true.

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 is front-loaded, then usage constraints and design-object handling follow in a compact sequence. Every sentence contributes actionable guidance without 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 complex, nested, destructive/open-world tool, the description covers the main action, usage condition, design payload integrity, and the no-payment caveat. It stops short of describing the return value or explicitly warning about session-content overwrite, but the schema and annotations fill much of that 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 100%, so the baseline is 3, but the description adds important semantics for the options.designs path: omit designs to use approved session designs, or pass exact complete returned design objects and do not reconstruct name/size-only entries. This materially reduces misuse of the nested design payload.

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: save selected session designs and create one Shopify basket/checkout link with names, sizes and quantities. It clearly distinguishes this from design-editing siblings by emphasizing the purchase link outcome.

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 clear usage condition: 'Only create it when the user wants a purchase link', and clarifies that omitting designs uses approved session designs. It does not explicitly name alternatives such as preview_design or validate_design, so it falls short of a full 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?

Annotations declare destructiveHint=true and non-idempotent, and the description adds real value beyond them by disclosing that the new design is blank, inherits no artwork, and that the advanced replaceDesigns:true flag replaces the session design collection. That replacement warning is exactly the kind of destructive consequence the agent needs.

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 the core action and inheritance caveat, followed by the advanced replace warning. 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?

Covers the essentials for a destructive, nested-parameter mutation with no output schema: what it creates, what it does not inherit, and the collection-replacement side effect. It could still be clearer about what is returned, but annotations plus the options description carry most of the load.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already documents all four parameters, making 3 the baseline. The description only loosely maps to the options fields (product, colour, size, quantity, print areas) and introduces the undocumented replaceDesigns flag, adding marginal meaning.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Create another independent blank design in this session') and distinguishes it behaviorally from related tools by noting it does not inherit artwork from the active design. It does not name sibling alternatives like create_design_variants or load_design, so it stops short of a 5.

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 context is only implied: it is for adding a fresh blank design in an existing session. There is no explicit 'use this instead of X when...' guidance against the many sibling design tools, though the 'does not inherit artwork' line helps rule out copying scenarios.

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?

The description goes beyond the destructiveHint by specifying exactly what is replaced: existing name/number text objects. It also explains that the tool does not create those objects itself and clarifies append versus replace behavior, which is the key mutation semantics an agent needs.

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 but well front-loaded: purpose first, then prerequisites, then mutation behavior, then checkout guidance. Every sentence carries operational value for this destructive, nested-parameter tool.

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 complex, destructive nested-object tool, the description covers the critical preconditions and replacement behavior. It does not describe return values, but the schema and sibling workflow give partial coverage; the missing return-shape guidance keeps it just below complete.

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 high, so parameter meanings are already well documented. The description still adds useful semantic guidance for areaId, variants fields, and append, though it does not add much beyond the schema for subject, sessionToken, or requestId.

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: cloning the active/base design into personalised designs. It distinguishes the tool from text-creation siblings by explicitly saying it does not create name/number text objects and that add_text is required for missing templates.

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 prerequisites and alternatives: ensure separate name and number templates exist, use add_text for missing templates, set append:true to retain existing session designs, and pass only complete intended designs to checkout. This is explicit when-to-use and how-to-prepare 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 destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the safety burden is partly covered. The description adds that print-area context is preserved, but it does not explain the extent of mutation, reversibility, or that supplied design patches can overwrite session content.

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 a single front-loaded sentence with no filler. The core action appears immediately, and the print-area constraint is included without unnecessary exposition.

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 description is adequate given the rich schema and destructive annotations, but it is thin for a complex nested-options mutation tool. It does not clarify what 'existing crop options' means or how the crop interacts with session content, leaving the schema and annotations to carry significant context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description references 'existing crop options' and 'print-area context,' which loosely maps to the options object, but it adds no concrete detail about crop fractions, placement, or required session identifiers beyond what the schema already provides.

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: 'Crop the selected image.' It also scopes the operation by mentioning existing crop options and print-area context, so an agent can distinguish it from siblings like flip_image or resize_element. It stops short of explicitly naming 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?

Usage is implied by 'Crop the selected image,' but the description does not explicitly say when to choose this over flip_image, rotate_element, or resize_element, nor does it state when not to use it. The print-area constraint provides some context but not routing guidance.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: deletion must target an explicitly intended element, ambiguity must be resolved first, and simulated removal via hiding/resizing is forbidden. It does not address permanence or recovery, but the core behavioral pitfalls are 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?

Two tight sentences: the first defines the action and its scope, the second defines the correctness constraint. No filler, no repetition of the title, and the constraint is front-loaded enough to be read before invoking.

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 destructive, non-idempotent mutation with full schema documentation and no output schema, the description covers the essential correctness requirement (unambiguous, explicit target) and one dangerous anti-pattern. It leaves out whether the session/design state reflows or whether an undo path exists, but the annotations already signal destructiveness.

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%, including the nested options object with elementIds, allText, allImages, and targetAreas, so the schema carries the parameter burden. The description adds nothing about which option to use (e.g., elementId vs. elementIds) and merely restates that 'selected elements' are supported. Baseline 3 applies when the schema is fully documented.

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 ('Delete') and a precise resource ('text/image element or selected elements'), which an agent can distinguish from sibling mutations like move_element or remove_background. It does not explicitly name a sibling alternative, keeping it just short of a 5.

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?

"Resolve an ambiguous target before deletion" gives a precondition, and "do not hide or shrink it to simulate removal" rules out a fake-delete workaround. However, it never says when to prefer a different tool (e.g., remove_background versus deleting an image element), leaving the alternative-selection gap implied rather than 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 readOnlyHint, idempotentHint, destructiveHint=false and closed-world, so safety is covered by structured data. The description adds genuinely new behavioral context: the catalogue is "live" (real-time data), no design session/state is needed, and it enumerates return content (colours, sizes, print areas, recommendations) despite there being no output schema. Pagination and rate/limit behavior remain unstated.

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?

Purpose is front-loaded in the first sentence and the closing "No design session is required" earns its place. The middle sentence, however, duplicates the query field list already fully documented in the schema, and the description is thin on anything the structured fields do not already say.

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 partially carries the return burden by naming catalogue attributes and recommendations, which is helpful. It still omits pagination/limit semantics, result shape, and any differentiation from choose_product, leaving meaningful gaps for a catalogue-discovery tool with a nested, free-form query object.

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% for the single nested query object, and the description merely re-lists the same field names (search, category, fit, quality, country, market, locale, quantity, sort, limit) without adding syntax, defaults, value constraints, or interaction rules. Baseline 3 for high-coverage schema plus a pure restatement.

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?

"Read the live garment catalogue, colours, sizes, print areas and recommendations" gives a specific verb (read) and resource (garment catalogue) plus the payload it covers. It does not, however, explicitly separate itself from the obvious sibling choose_product, so the agent must infer the browse-vs-select boundary.

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 design session is required" establishes a prerequisite/context (usable without start_design_session), which implies this is the pre-session browsing step. But there is no explicit when-to-use, when-not-to-use, or named alternative (e.g. choose_product vs discover_products), so routing 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?

Annotations already declare destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the safety profile is partly covered. However, the description adds no behavioral context: it does not explain what makes duplication destructive, whether the original remains, whether existing placement is overwritten, or what happens to session content. That gap is notable for a destructive mutation.

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 a single front-loaded sentence with no filler. It is appropriately concise, though its brevity leaves behavioral gaps that are scored elsewhere. The structure itself is clean.

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 destructive, non-idempotent mutation with nested placement options and no output schema, one sentence is not enough. The schema and annotations cover parameters and safety flags, but the description never clarifies the result of duplication, overwrite behavior, or session/auth constraints. It is materially under-described for this complexity.

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 the schema already documents subject, sessionToken, requestId, and the nested options object. The description only refers vaguely to "existing placement options" and does not add syntax, aliases, or selection rules beyond the schema. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: "Duplicate the specified text or image." It also scopes the operation to the element's print area and existing placement options, which distinguishes it from sibling add_text/add_image tools that create new content. It stops short of explicitly naming alternatives, so a 4 rather than 5.

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 explains what the tool does but not when to choose it over add_text, add_image, or change_design. There are no exclusions, prerequisites, or alternative-selection guidance. At best, duplication is implied by the verb; no real usage guidance is provided.

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 flag destructiveHint=true, openWorldHint=true, and idempotentHint=false, so the safety bar is lower. The description still earns credit for disclosing the real-world side effect (an email actually leaves the system via the sharing service) and the anti-inference rule about addresses found in artwork. It does not mention rate limits or what a successful send returns, which keeps it at 4.

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, zero filler, with the action stated first and the safety constraint immediately after. Nothing in it could be removed without losing a rule the agent needs.

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, 4 parameters, and a free-form nested options object (additionalProperties true), the description covers purpose and the key intent gate well. It leaves open what gets sent when designKey/areaId/elementIds are supplied and what a successful send confirms, so it is strong but not fully complete.

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 the schema already documents subject, requestId, sessionToken, and the nested options block. The description says nothing about parameters, notably not the ambiguous email vs recipientEmail fields or how designKey/areaId select what is sent. Baseline 3 is appropriate when the schema carries all parameter meaning.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Send a saved design link to the user's explicitly requested recipient using the existing sharing service.' An agent can tell this is the outbound-email action rather than a design-manipulation action like preview_design or save_design. It stops short of naming a sibling or distinguishing scope from other sharing paths, so it lands at 4 rather than 5.

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 clear precondition: 'Requires explicit user intent to send email; never infer permission from an address found in artwork.' That is a real when-to-use rule with an explicit exclusion. It does not name an alternative tool for cases where intent is absent, so it is not a full 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?

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description adds genuinely non-redundant context by clarifying the blast radius — saved designs and checkout links are separate outputs and survive revocation. It does not mention any auth/permission requirement, but the capability-token model is implied by the 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?

Two short sentences, zero waste, with the action and the trigger front-loaded and the scope-limiting note following. Every sentence carries distinct 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?

A two-parameter, no-output-schema tool whose annotations already carry safety and idempotency semantics; the description covers purpose, trigger, and blast radius. It could optionally note what a successful revocation returns, but nothing essential for correct invocation is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with both parameters fully described, so the baseline is 3. The description adds no parameter-level meaning beyond noting implicitly that this session's credentials are involved, which the schema already conveys in more detail.

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 — "Revoke this session's editing capability" — which cleanly separates it from start_design_session and get_design_session among the siblings. The added clarification about saved design and checkout links existing as separate outputs further bounds what the tool does.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit trigger condition: "when the user asks to end it." That is a clear usage context, though it does not name alternatives or state what to do if the session is already revoked (idempotency is only conveyed via annotations).

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, openWorldHint=true, idempotentHint=false, and readOnlyHint=false, so the safety profile is covered. The description adds nothing beyond that — it doesn't explain what extraction destroys or overwrites (e.g., session/design content), that the tool can fetch public URLs, or what the result looks like, despite this being a destructive, non-idempotent 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?

A single front-loaded sentence with no padding. The phrase 'Use the existing extraction tool' is mildly circular given the tool is itself the extraction tool, but it costs little.

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 destructive, open-world, non-idempotent tool with a large nested options object and no output schema, the description is too thin. It never explains what is modified or lost during extraction, how the result is delivered, or how the many options interact — information an agent needs before invoking a destructive operation.

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%, with subject, sessionToken, requestId, and the nested options object all documented in the schema. The description's 'supplied garment mockup' hints at the subject/asset relationship but adds no syntax or semantics beyond the schema, so the 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 clear verb and resource: 'recover printable artwork from a supplied garment mockup.' An agent can tell it is an extraction/recovery operation on mockup images. However, it does not distinguish itself from plausible siblings like generate_artwork, remove_background, or sticker_cutout, so an agent must infer the boundary.

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 sentence only says to 'use the existing extraction tool'; there is no when-to-use vs alternatives guidance, no prerequisites beyond the implied session, and no exclusion of sibling tools. An agent has no routing signal for choosing extract_artwork over generate_artwork or remove_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 destructiveHint=true, readOnlyHint=false and idempotentHint=false, so the safety profile is covered by structured data. The description's added value is structural — exactly which nested path carries the direction — but it never says the edit mutates the session design, whether it is reversible, or that a preview/save is needed afterward.

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 followed immediately by the argument placement detail. Dense but every clause carries information; only the second sentence's phrasing could be slightly tighter.

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?

There is no output schema, but the description plus a fully documented schema and full annotations cover what an agent needs to call this correctly. Remaining gaps (reversibility, session persistence) are nice-to-have rather than blocking for a single-field image transform.

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 baseline would be 3, but the schema's deeply duplicated nesting (options.options.direction, with many unrelated sibling fields) is genuinely confusing. The description disambiguates by naming the public options level for areaId/elementId and the nested options.options.direction path, which meaningfully reduces mis-invocation risk.

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 (flip the selected image) plus the two supported axes (horizontal/vertical). It does not name sibling operations it might be confused with (rotate_element, invert_image, crop_image), so an agent must infer the boundary, but the operation itself 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?

"The selected image" implies an element must already be selected and an areaId/elementId supplied, which is useful context. There is no explicit when-to-use vs. when-not, and no mention of choosing flip over rotate_element or invert_image, so the routing guidance is only implied.

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?

"Bounded allowance" discloses a quota/cost constraint and "can return pending work" discloses async/polling behavior — both are useful beyond the annotations. However, destructiveHint=true is never explained: the description doesn't say generation can overwrite existing design content, which is the single most important behavioral fact for an agent calling this.

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 the core action, then usage hints, then behavioral caveats. No filler, though the middle sentence's phrasing slightly buries the parameter hint.

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 should at least sketch what comes back (asset, pending status), and it only gestures at pending work. The destructive side effect and the cost of burning allowance on a bad prompt are left implicit, which is a real gap for a mutation 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 description coverage is 100%, so the schema already documents requestId polling semantics and sessionToken. The description adds workflow meaning by grouping applyToDesign, singleResult and areaId as the "apply to shirt" combination, but contributes nothing about subject, sessionToken, or prompt.

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 sentence gives a specific verb+resource ("Generate artwork from a prompt") plus the backing service, so an agent knows this is a text-to-image generation call. It doesn't distinguish itself from adjacent siblings like ai_photoshoot, extract_artwork, or upload_image, so it falls short of a 5.

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 applyToDesign, singleResult and areaId when applying it to a shirt" gives some situational guidance, but there is no when-not guidance and no named alternative for plain image insertion or photoshoot-style generation. Usage is implied rather than framed as a decision rule.

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?

The description does real work beyond the annotations: it explains why a "check" call is annotated readOnlyHint=false and destructiveHint=true by disclosing that pending checks "recover and resume stalled work, including its original edits, image retrieval or email send." It still does not say what specifically can be lost or duplicated when a stalled action resumes, but the side-effect disclosure is meaningful.

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 what the tool is, then the side-effect caveat, then the operational rule. Nothing is wasted and the polling instruction lands last where it matters most.

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 burden for return values and it leaves "terminal" undefined — an agent is not told what statuses or fields signal completion versus failure. The invocation guidance is complete, but interpreting the response is left to inference.

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 the requestId reuse rule and sessionToken secrecy are already documented. The description only reinforces requestId reuse ("Pass its original requestId") and gestures at session scoping with "in this session"; it adds little syntax or meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ("Check a request submitted in this session") and clarifies via the polling line that this is a status/polling operation, not a session listing. It distinguishes itself from get_design_session only implicitly through the requestId/request framing, without naming the sibling.

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?

"Poll until terminal before starting another edit; a queued job is not a completed design" gives clear sequencing guidance, and "Pass its original requestId" tells the caller which identifier to reuse. It does not explicitly contrast the tool with get_design_session or say what to do after a terminal non-success state.

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, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds useful context: it reads live session state (not persisted design data) and requires a private, expiring sessionToken, implying an auth-like capability requirement.

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 compact sentences, no waste: what it reads, what it's for, and what it needs. Purpose and scope are front-loaded before the prerequisite.

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?

There is no output schema, so the description carries the burden of describing returns; enumerating designs, elements, print areas, previews and the last changed object covers the content an agent needs. It stops short of describing the shape/nesting of those objects, but that is minor for a simple read.

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% and both parameters are documented in-schema as coming from start_design_session. The description only echoes that they are required, adding no format, expiry, or validation detail beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Read') and enumerates the resource scope precisely: this session's designs, elements, print areas, previews and last changed object. An agent can tell it's the session-read tool, though it never explicitly contrasts with the nearby get_design_request sibling.

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 it to resolve an edit's target' gives a concrete triggering scenario, and the second sentence states the prerequisite inputs (subject, sessionToken). No when-not guidance or named alternatives, 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?

Annotations flag this as destructive (destructiveHint=true, readOnlyHint=false), so the agent knows it mutates state, but the description adds nothing about irreversibility, whether the original can be restored via restore_original_image, or what 'the selected image' means when options.elementId/imageFile also exist. For a destructive mutation the bar is higher than a single generic sentence.

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 short sentence with no waste, but 'using the existing image tool' contributes no information and the brevity comes at the cost of substance rather than being efficient.

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 destructive, session-scoped mutation with a deeply nested options schema and no output schema needs to say what happens to the image, whether it is reversible, and what the caller gets back. None of that is present.

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% and the nested options/placement objects are documented in the schema, so baseline 3 applies. The description adds no meaning: it doesn't clarify how the 'selected image' resolves against elementId, elementIds, or imageFile, which is the one thing the schema leaves ambiguous.

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 ('invert ... image's colours'), so the operation itself is unambiguous. However, it doesn't distinguish itself from adjacent image-editing siblings such as flip_image, remove_background, or crop_image, and the trailing 'using the existing image tool' is ambiguous filler.

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 indication of when to use this rather than flip_image, remove_background, or replace_image, and no prerequisites (e.g., that an image element must already be selected in the current session). The agent is left to infer everything about selection conditions.

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 flag destructiveHint=true, openWorldHint=true and idempotentHint=false; the description reinforces mutability only indirectly via 'editable session state'. It never states that existing session content can be overwritten, never mentions that external URLs are fetched, and never mentions the private session token — details that live only in the schema, not the description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no waste, and the core action is front-loaded before the co-existence note. 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?

For a destructive, open-world tool with a large nested options object full of aliases and no output schema, the description is thin: it does not explain what is returned, what happens to already-loaded designs, or how the options aliases differ. It covers the happy path but not enough for confident 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 100%, so baseline is 3. The description adds the useful format signal that either a design key or a saved-design URL is accepted, but it gives no guidance on the alias cluster (key/keys/designKey/designkey/designKeys) or on areaId/elementId selection.

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 (load) and resource (SSD design key / streetshirts saved-design URL) and the effect (into editable session state). An agent can tell this opens an existing saved design rather than creating one, though it never explicitly contrasts with change_design or get_design_session which sit right next to it.

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?

'Different saved designs can coexist in one session' is a usage hint implying this may be called repeatedly, but there is no explicit when-to-use, when-not-to-use, or named alternative (change_design, preview_design, get_design_session). Usage must be 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 destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds real value with "Preserve other elements and areas," scoping what the mutation does not touch, but it never says what is replaced (the element's prior position/size) or how the session state is affected.

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 action is front-loaded in the first sentence, which is good. The trailing sentence about "batch compatibility name update_element" is opaque jargon and "Advanced element, text and asset patches" reads as filler that dilutes an otherwise short definition.

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?

This is a destructive mutation with a large nested options object and no output schema, and the description does not cover the response shape or recovery path. It does at least tie the element patch to the existing editor and the required session/subject/idempotency fields are documented in the schema, so it is adequate but thin for the complexity.

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% including a detailed placement description, so the schema carries the load. The description only points at "x/y or placement options" and a follow-up instruction, adding no format, unit, or coordinate-space detail beyond the schema baseline.

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?

"Move the target element within its print area" gives a specific verb and resource, and the "within its print area" scope implicitly separates it from move_to_print_area. It never names a sibling explicitly, so an agent must infer the boundary from the phrasing alone.

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 the existing x/y or placement options" and "interpret an unambiguous follow-up from session state" give invocation hints, but nothing says when to prefer this over align_element, resize_element, rotate_element, or move_to_print_area. Usage is implied rather than routed.

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 flag destructiveHint=true, openWorldHint=true, and non-idempotent, so the safety profile is carried entirely by structured data. The description itself adds nothing about what destruction occurs (is the element removed from its source area? overwritten?), nor about session/network side effects that the annotations only hint at.

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 short sentence with the action front-loaded, which is good, but the trailing clause 'with the existing destination/target-area options' is filler that conveys no actionable information. It is concise without being dense.

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 destructive, non-idempotent mutation with a deep nested options object and no output schema, the description omits what state changes (source area handling, whether the move can be undone, what a successful result contains). An agent could call it correctly on shape alone but not predict its effects.

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 the schema already documents subject, requestId, sessionToken, and the nested options including the placement coordinate-space semantics. The phrase 'destination/target-area options' loosely points at targetAreas/areaId, but adds no syntax or constraint detail 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?

The description names a specific verb (move) and a specific resource (an element, into a named print area), which is more precise than the generic title. It does not, however, distinguish this from the sibling move_element, so an agent must infer the difference from the name alone.

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?

There is no explicit guidance on when to use this versus move_element, nor any stated preconditions such as needing an active session with a selected element. The only usage signal is the implicit 'between print areas' framing carried by the title.

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 destructiveHint=true and openWorldHint=true, yet the description says nothing about what can be destroyed; the fact that supplied design patches can overwrite session content and that public image URLs are fetched sits only in the schema's options text, not the description. It also omits the requestId retry/polling semantics that govern repeated calls, leaving the safety-relevant behavior undocumented at the description level.

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 the core action front-loaded and no filler. The second sentence is a genuinely useful handling instruction ('Display the returned preview URL') since there is no output schema, though it is phrased as a customer-facing directive rather than agent guidance.

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 usefully tells the agent the call yields a preview URL. But for a tool flagged destructive and open-world with a nested options bag, it omits the state-overwrite risk and the network-fetch behavior, which are the main things an agent must anticipate; the schema carries that burden instead.

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%, and the schema already explains subject, requestId, sessionToken and the options bag in detail. The description adds no parameter-level meaning beyond what the schema provides, 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?

States a specific verb ('Render') and resource ('garment preview') scoped to 'the active design and chosen product', which distinguishes it from create_design, save_design, and ai_photoshoot. The prerequisite context ('existing', 'active design', 'chosen product') makes the operation identifiable without opening the schema, though it does not name any sibling 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?

Implies when to use it (a design session is active and a product is selected and the customer wants to see the garment), but never states exclusions or names alternatives such as get_design_session or ai_photoshoot. Usage is inferable rather than specified.

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, non-idempotent, and openWorld, so the safety profile is covered. The description adds a small amount of behavioral context — the workflow auto-selects a method and "preserves the box," and it produces a garment preview — but it never warns what is destroyed, whether the change can be undone via restore_background, or that supplied design patches can overwrite session content.

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 the action and followed by side effects and the resulting preview. It is efficiently sized, though the repeated word "existing" and the loose "workflow" framing cost some precision.

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?

This is a destructive, non-idempotent mutation over a rich nested options object with no output schema, yet the description says nothing about reversibility (restore_background exists as a sibling), permission or session requirements, or what the returned preview contains. For a destructive image-editing tool, that leaves real 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 description coverage is 100%, so the baseline of 3 applies; the required subject/sessionToken/requestId and the nested options object are documented in the schema. The description itself adds no meaning about method, feather, colorKeyHex, or the nested options.options fields, and does not explain the relationship between the prose 'preserves the box' and preserveImageBox.

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 conveys the resource (a target image) and an implied verb (background removal) plus a preview step, but phrases it vaguely as using "the existing background-removal workflow" that "chooses the appropriate existing image method." It never distinguishes the tool from close siblings like restore_background, sticker_cutout, or extract_artwork, so an agent cannot tell exactly which cutout operation this is.

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?

There is no statement of when to use this versus restore_background (the inverse), sticker_cutout, or extract_artwork, and no prerequisites such as needing an existing image element or an active session. Usage must be inferred entirely from the name.

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, openWorldHint=true, and non-idempotent behavior, so the safety profile is covered. The description adds only a faint scope claim ('retaining the intended text and print-area scope') and says nothing about what session content gets overwritten, that rendering may fetch external image URLs, or that a session token is required — details that live in the schema, not 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?

It is a single sentence with no filler, which is good, but the opening is loaded with internal jargon rather than a concrete statement of what happens to the emoji characters. Efficient in length, weak in information density.

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?

This is a destructive mutation with a large nested options object (area scoping, element targeting, replacement arrays, platform selection) and no output schema. One sentence of jargon-heavy prose is not enough to tell an agent how the nested targeting fields interact or what the tool leaves untouched.

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%, including per-property descriptions for subject, requestId, and sessionToken, so the schema carries parameter meaning on its own. The description mentions no parameters and adds nothing about the nested options object, so the 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?

The description pairs the verb 'Replace' with the resource 'emoji text' and gestures at the outcome (approved emoji image workflow retaining text and print-area scope). However, it is phrased in internal jargon ('streetshirts' existing approved emoji image workflow') and never clarifies how this differs from siblings like replace_image, update_text, or add_text, so an agent must infer the boundary.

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?

There is no statement of when to choose this tool over replace_image or update_text, no prerequisites beyond what the schema enforces, and no exclusions. The only implicit guidance is 'retaining the intended text and print-area scope', which is a constraint rather than a routing rule.

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 related traits. The description adds meaningful behavioral context beyond that: it preserves the existing box by default unless a new placement is requested, and it overwrites current image content. It does not discuss reversibility or permissions, but adds solid value over 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?

Three sentences, front-loaded with the core action and followed by the overwrite warning and prerequisite. No wasted words.

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 description covers the essential action, destructive behavior, default box preservation, and a prerequisite for target/print-area resolution. It is reasonably complete for a mutation tool without an output schema, though it could mention sibling alternatives or restoration behavior.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the input schema already documents parameters thoroughly. The description adds a little semantic context about image-box preservation and optional new placement, but not enough to exceed the baseline for high schema 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?

The description states a specific verb and resource: replace the target's current artwork using an uploaded image. The overwrite language ('This overwrites the selected image content') implicitly distinguishes it from add_image, though it does not explicitly name that sibling.

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 provides a useful prerequisite ('Resolve the target and print area first') but does not say when to use this versus add_image, upload_image, or restore_original_image. Usage is implied by the overwrite semantics rather than explicitly guided.

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 destructiveHint=true and idempotentHint=false, so the description should clarify what a resize overwrites (e.g., that unspecified dimensions are preserved or replaced) and whether the current artwork scale is lost. Instead it only notes that 'Core already converts' physical units — useful but not the mutation semantics an agent needs before an irreversible edit.

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 the action and then the unit rule and a worked example. No filler; only the somewhat loose term 'target' costs it a perfect 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?

This is a complex destructive mutation with 20+ nested options, alias fields, and a nested placement object, yet the description covers only the centimetre/millimetre case. It never explains single-vs-multiple element targets, how x/y/scale combine with width/height, or what 'the specified print area' means relative to areaId/areaIds/targetAreas — all left to 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?

Schema description coverage is 100%, so baseline is 3. The description does add real value by explaining that widthCm/heightMm are converted by Core and by giving a concrete call example, but it says nothing about the scale/scalePercent/width/placement.size families or the plural ID aliases.

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 ('Resize the target in the specified print area'), which is clear on its own. However, it never distinguishes itself from the sibling resize_group, and 'target' is left undefined even though elementId/elementIds/targetElementIds all exist.

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 statement of when to use this instead of move_element, resize_group, move_to_print_area, or align_element — all of which overlap. The only guidance is a unit-choice hint ('for physical dimensions use widthCm/heightMm'), which is parameter selection rather than tool 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?

Annotations already declare destructiveHint=true, idempotentHint=false and openWorldHint=true, so the safety profile is covered. The description adds real value with 'preserving their relative layout' (aspect/positional preservation), but says nothing about what is destroyed or overwritten by the mutation, which matters given destructiveHint=true.

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: purpose first, then sizing syntax, then selection semantics. No filler and each sentence carries 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 destructive mutation with rich annotations and no output schema, the description covers intent, sizing modes and selection scope adequately. It stops short of describing the effect on the resulting layout response or how it behaves with areaIds/targetAreas when multiple print areas are supplied.

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%, but the description still adds genuine meaning beyond the raw property list: it pairs widthCm/heightCm as group bounds, explains scale vs scalePercent as equivalent units, and clarifies that omitted elementIds selects every element in areaId. It leaves the numerous aliases (width/height, placement, areaIds, targetAreas) unaddressed.

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+resource (resize group of elements) and scope ('all or selected elements together'), which implicitly distinguishes it from the single-element sibling resize_element. The phrase 'in one print area' is slightly at odds with the schema's areaIds/targetAreas plurals, leaving the multi-area story ambiguous.

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 guidance on the two sizing modes (widthCm/heightCm for group bounds vs scale:0.8 / scalePercent:80) and the selection rule for elementIds. It does not say when to prefer this over resize_element or move_to_print_area, so no explicit exclusions.

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 beyond the annotations by disclosing consequences: crop/flip modifiers are cleared, pixel dimensions reset, placement preserved, and the image source is replaced by the current original. It does not mention irreversibility or failure modes even though destructiveHint=true and idempotentHint=false, so it stops short of full disclosure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, front-loaded with the effect and ending with the sibling routing rule; every sentence earns its place. The middle sentence is dense but not 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?

Given a deeply nested options schema and no output schema, the description supplies the operation semantics an agent needs and no return-value explanation is required. Minor gap: no note on what the call returns or how to recover after a destructive restore.

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 the schema already documents subject, sessionToken and requestId. The description adds only 'Pass elementId and areaId', which are optional nested fields rather than the required top-level parameters, so it adds marginal value and slightly muddles where those arguments belong.

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 ('Undo background removal on the selected uploaded image') and then enumerates what is restored, cleared and preserved. It is clearly separable from siblings like remove_background and restore_original_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?

Names the alternative sibling explicitly and gives the selecting condition: use restore_original_image when retained-original recovery with crop/flip preservation is intended. That is the exact discriminator an agent needs between two near-identical-sounding restore tools.

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, idempotentHint=false and openWorldHint=true, and the description's 'preserving the authored placement' usefully tells the agent that geometry survives the operation. However, it never states that the current (possibly edited) image content is replaced and unrecoverable, which matters for a destructive, non-idempotent call.

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; scope and the key preservation guarantee come first.

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 destructive, non-idempotent mutation over a deeply nested option object, the description omits return behavior, failure modes when no original is retained, and whether repeated invocations or non-idempotency matter. The one sentence it does have is accurate, but the destructive profile is left largely to the annotations.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema carries the parameter burden and baseline 3 applies. The description names elementId and areaId and stresses they must be supplied explicitly, but adds no meaning to areaId's front/back/left/right values or to how they interact with the retained content.

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: restoring retained original image content, scoped to an element and print area. It is distinguishable from most siblings, but never contrasts itself with the closest relative, restore_background, so the agent must infer which restore applies to which retained content.

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, prerequisites, or alternative is given; the only guidance is the adjective 'explicit' before elementId/areaId. Nothing tells the agent when restoration is appropriate versus replace_image or restore_background, nor what happens if the element has no retained original.

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, idempotentHint=false and openWorldHint=true, so the description's job is to add context — but it doesn't. Critically for a non-idempotent rotation tool, it never says whether the rotation value is absolute (set to N degrees) or cumulative (rotates by N each call), nor whether the change is reversible or requires the element to be in a print area first. The one useful detail added is that the element must already exist and be in its print area.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single sentence with the action front-loaded; it is not padded. The closing clause "using the existing rotation/placement options" is vague filler that doesn't earn its place, keeping it below a 5.

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?

This is a destructive, non-idempotent mutation over a deeply nested options object with no output schema, so the description should carry more: it says nothing about angle units, accumulation across calls, or what the response returns. It is adequate for identifying the action but not for calling it correctly on complex layouts.

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 the schema already documents subject, sessionToken, requestId and the nested options/placement objects, making 3 the baseline. The description's only nod to parameters is the vague "existing rotation/placement options", which adds no meaning about units (degrees vs radians) or which option field carries the angle.

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 ("Rotate the specified existing element") plus its scope ("in its print area"), so an agent can tell it apart from add_*, delete_*, or update_* tools. However, it never distinguishes rotation from the closely related siblings move_element, resize_element, align_element, or flip_image, and the trailing phrase "using the existing rotation/placement options" muddies rather than sharpens the purpose.

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?

There is no guidance on when to use this tool rather than move_element/resize_element/flip_image, no mention of prerequisites such as an active design session or an element already placed in a print area, and no exclusions. The only implied usage is "an element already exists and you want to spin 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 readOnlyHint=false, idempotentHint=false and destructiveHint=false; the description adds substantive context beyond them by stating that saved results get 'immutable saved keys' and visual-editor links, reinforcing that each save creates a new artifact rather than overwriting. Missing are failure modes, permission requirements and behavior of the many options aliases.

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, zero filler. The primary mode is front-loaded, the batch alternative follows, and the return payload plus the prerequisite close it out.

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 compensates by naming what comes back (immutable keys, editor links), and it points to 'the full designArgumentSchema' rather than re-documenting the large nested options object. It could say more about what a successful versus rejected save looks like given the openWorldHint and nested-object complexity.

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 schema itself documents designs, variants and the session/requestId semantics, so the description can lean on it. The one added nuance is that sizes and quantities must be final/production-grade, which is not stated in the schema, but the descriptions of the remaining options fields still come entirely from the schema or not at all.

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 plus resource ('Save the active design') and enumerates the multi-output path via designs/variants/saveAllDesigns. It does not explicitly name which sibling tools come before it (preview_design, validate_design, create_checkout), so sibling differentiation is only partial.

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 clearly splits two usage modes: single 'active design' save versus batch save by supplying designs/variants/saveAllDesigns, and adds a concrete prerequisite ('Final production sizes and quantities must be supplied'). It stops short of stating when not to call it or which sibling precedes it in the workflow.

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 the generic profile (readOnly=false, destructive=false, non-idempotent). The description adds real context beyond that: the session is private and expiring, the token grants access and must not be published, and one session can hold multiple designs and a team basket.

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 core action, then the token-handling and scoping details. Four short sentences, each carrying distinct information (action, retention, security, capacity); no 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 no params and no output schema, the description usefully names the two key return values and the session lifecycle (expiring) plus token sensitivity. It stops short of describing expiry behavior or failure modes, but for a parameterless creator this is close to complete.

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 and 100% schema coverage, so the baseline is 4. The description references returned values (subject, sessionToken) rather than inputs, which is appropriate since there is nothing to parameterize.

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 (Start) plus resource (design session) and adds distinguishing scope: private, expiring, guest. An agent can tell this apart from end_design_session and get_design_session without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The line about keeping subject/sessionToken 'for every follow-up' implies this is a prerequisite step for later calls, but no alternative or when-not condition is named (e.g., vs get_design_session or end_design_session). Usage 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 destructiveHint=true, readOnlyHint=false, openWorldHint=true, and idempotentHint=false, so the agent knows this mutates state. The description adds the useful detail of what is removed (a flat surrounding page or image box), but says nothing about the effect on the design/session, reversibility, or the warning that supplied patches can overwrite session content (which lives only in the 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?

A single efficient sentence with the effect front-loaded. Minor waste in the phrase 'the existing sticker-cutout operation', which conveys nothing actionable.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

This is a destructive mutation with a large nested options object and no output schema. The description does not say what the tool returns, whether the change applies to the live design or only a preview, or how it interacts with the session — all of which an agent needs before invoking a destructive operation.

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 the baseline is 3. The description's only parameter-adjacent signal is 'selected artwork', hinting at element selection, but it adds no meaning for the many behavioral options (feather, tolerance, paddingPx, colorKeyHex, preserveImageBox, applyToDesign) that an agent must choose correctly.

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 effect: it removes a surrounding flat page or image box from selected artwork, which is more specific than the title alone. It does not, however, differentiate itself from close siblings such as remove_background, extract_artwork, or crop_image, so an agent cannot tell which cutout-style tool to pick without outside knowledge.

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 the existing sticker-cutout operation' is a restatement rather than guidance; there is no when-to-use condition, no prerequisite (session, selected artwork), and no named alternative among the many sibling image tools. The only implied usage is the phrase 'selected artwork'.

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, idempotentHint=false, and openWorldHint=true, so 'This can overwrite the selected wording' largely restates destructiveHint. The genuinely additive content is the 'style fanout and explicit batches' behavior, but it is not explained, and nothing is said about what a failed/partial batch leaves behind.

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 opening sentence is well front-loaded, but the closing sentence is jargon-heavy and oblique ('style fanout and explicit batches'), and 'For all text... in every intended print area' is ambiguous rather than efficient.

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?

This is a destructive mutation with a large, alias-riddled nested options object and no output schema. The description never explains which parameters are preferred over their aliases, what 'style fanout' means in practice, or how partial failures across areas are handled, leaving real gaps for a call of this complexity.

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 the schema already documents most fields including the nested placement and text objects. The description adds only a targeting hint ('resolve targets from session state') and no guidance on the many aliases (elementId vs elementIds, allText vs areaIds, textColor vs textColour) that an agent must choose between.

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 ('replace existing text content or edit its style'), which cleanly separates it from add_text/create_design siblings without naming them. The scope is clear, though the distinction from add_text is only implied by the word 'existing'.

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?

'Resolve targets from session state' and the instruction to include every intended text object in every print area give some operational context, but there is no explicit statement of when to use this versus add_text or apply_design_batch, and no preconditions or exclusions.

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, openWorldHint=true, readOnlyHint=false, and idempotentHint=false. The description adds useful input-validity context and placement behavior, but it does not explain what destructive effect occurs or what may be overwritten when uploading and applying to a design.

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 four short sentences, front-loads the main action and accepted inputs, and contains no filler. Each sentence contributes either source semantics, required identifiers, placement guidance, or an important invalid-input constraint.

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 complex destructive upload tool with no output schema, the description covers key input sources and placement but leaves return behavior and the practical impact of the destructive flag unstated. The rich input schema and annotations carry much of the burden, but the description is still only minimally complete for safe 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 100%, so the baseline is 3, but the description adds meaningful semantics by naming the accepted image source alternatives and giving examples for filename, contentType, and fileType. It also explains that applyToDesign and areaId control placement.

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 clearly states a specific verb and resource: upload an image from one of several source forms. It does not explicitly distinguish this tool from close siblings such as add_image or replace_image, so it is clear but lacks sibling differentiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives practical usage context, including required identifying fields and placement options, and warns that caller-local paths or bare file IDs are not downloadable artwork. However, it does not say when to use this tool instead of alternatives like add_image or replace_image, leaving selection guidance implied.

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 destructiveHint=true, readOnlyHint=false and non-idempotent, yet the description frames this as a read ('Read the actual validation result'), disclosing no mutation, overwrite, or open-world fetch risk. The schema's options description admits supplied design patches can overwrite session content, but that critical warning never reaches the top-level description an agent reads first.

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, front-loaded with the action and with zero filler. It is not under-specified in length, though the brevity is part of why behavioral caveats are absent.

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 destructive, non-idempotent, open-world tool with a nested options object and no output schema, the description omits what a 'validation result' contains, whether failure leaves the session modified, and how the returned result should be read. The schema carries some of this, but the description alone leaves an agent under-informed for a mutating call.

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 all four parameters are documented in the schema, including the subject/sessionToken/requestId provenance and UUID reuse rules. The description adds no parameter guidance of its own, which is acceptable at this coverage level but unremarkable.

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+resource ('Validate the ... design') plus a distinguishing mechanism ('with the existing production compiler'), and covers both 'current or supplied' design modes. It is separable from siblings like preview_design and save_design, though the save relationship is only implied.

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 phrase 'before saving' implies a pre-save workflow step, which is useful sequencing guidance. But it never names alternatives (preview_design, save_design) or states when validation is unnecessary, so the agent must infer the decision rule.

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