mcp-fashion

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so irreversibility is covered. The description adds real value by naming the side-effect target (~/.polopan/region.json), but omits what happens if the ID is unknown or if the address is currently the default.

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

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

One sentence, front-loaded with the verb and resource, with no filler. Every element earns its place.

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

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

For a single-param destructive tool with full annotation coverage, a complete schema, and no output schema, the description supplies what the structured fields do not: the persistence location. Only missing edge-case behavior keeps it from a 5.

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 single address_id parameter is documented in the schema, so baseline 3 applies. The description adds no format, source, or lookup detail beyond 'by ID'.

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

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

States a specific verb (Delete), a specific resource (a saved delivery address), the selector (by ID), and the storage target. It is clearly distinguishable from address.save, address.set_default, and address.list_saved without opening any schema.

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

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

Use case is implied by the intent — remove a saved address — but there is no explicit when-to-use guidance, no exclusion conditions, and no pointer to alternatives such as address.set_default for merely changing the default rather than deleting.

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 this a safe read (readOnlyHint=true, destructiveHint=false), so the bar is lower. The description nonetheless adds real context: the data source is local config at ~/.polopan/region.json, and — importantly with no output schema present — it discloses the 'has_address' result flag that callers must branch on. It does not cover failure modes (missing/corrupt config file, no active region), which is a minor gap.

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

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

Front-loads the core purpose in one sentence, then uses a labeled block for the critical usage rule; every sentence carries actionable content. The uppercase 'CRITICAL ANTI-SHORTCIRCUIT RULE' framing is slightly dramatic but defensible given the downstream branching requirement.

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

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

With no output schema, the description carries the burden of explaining returns and does disclose the key 'has_address' flag plus the prefill-vs-prompt behavior. It stops short of describing the remaining address fields or the error path when no region/config is available, so it is strong but not exhaustive.

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 single optional 'country' parameter (with code examples and default-to-active-region behavior) is already fully documented in the schema. The description's mention of the 'currently active region' restates rather than extends that semantics, 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?

Names a specific verb+resource (get the default delivery/shipping address) and scopes it to the active region's local configuration. It is immediately distinguishable from siblings like address.list_saved or address.delete, which operate on address collections rather than the single active-region default.

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 directive ('ALWAYS call this BEFORE generating 1-click checkout links') plus branch-specific follow-ups depending on the result, and routes to a named alternative ('address.save') when no address exists. It even states the anti-pattern to avoid (emitting a naked checkout link) and what to ask the user for instead.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered by structured data. The description adds useful context by disclosing the backing store (~/.polopan/region.json), but says nothing about ordering, pagination, auth requirements, or behavior when the file is missing/empty — so it adds only modest value beyond 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?

One sentence, front-loaded with the verb and resource, followed by scope and the optional filter. No filler or redundancy; every clause carries information.

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

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

For a one-parameter read-only list tool with full schema coverage, the description is nearly sufficient. Since there is no output schema, it could have stated what a returned address entry looks like (fields, ordering), which is the one 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 description coverage is 100%, so the single 'country' parameter (ISO-2 or natural name, optional) is already fully documented in the schema. The description merely restates the filter without adding syntax, matching rules, or fallback behavior, so baseline 3 applies.

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

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

States a specific verb+resource (list saved customer delivery addresses) and even names the storage location (~/.polopan/region.json), so the agent knows exactly what collection is being read. It is clearly distinct from write siblings like address.save/address.delete, but it does not explicitly differentiate itself from address.get_current, leaving a small routing ambiguity.

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 'optionally filtered by country' implies the intended usage (enumerate all saved addresses, narrow by country), but it is framed as a parameter note rather than guidance. There is no statement of when to prefer this over address.get_current or what happens when no filter is supplied, so usage 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?

Annotations establish it is a non-destructive write; the description adds real value by disclosing the persistence target (~/.polopan/region.json), the region-mapping behavior, and schema parity with the Flutter app. It stops short of explaining update-vs-create conflict semantics or what happens to pre-existing addresses.

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 purpose in one sentence, followed by a short schema-parity note. The second sentence is somewhat redundant with the schema's field list, but overall it is tight and well-structured.

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 14-parameter mutation tool with no output schema, the essential behavior (where it writes, region binding) is covered and safety is carried by annotations. It does not address return values, the outcome of an update to an existing id, or failure modes, leaving modest 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 schema already carries all 14 parameter meanings (enums, defaults, id semantics, storage_mode). The description only re-lists field names that the schema already documents, adding no syntax or format detail beyond it, so baseline 3 applies.

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

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

States a specific verb+resource (save/update a customer delivery shipping address) and clarifies its dual create-or-update role. It does not, however, name or contrast with address siblings like set_default or delete, leaving the agent to infer which address tool to reach for.

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 when-to-use vs when-not guidance and no reference to alternatives such as address.set_default (relevant since is_default is a parameter) or address.delete. Usage is only implied from the tool name and the 'id' parameter.

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 and destructiveHint=false, so the mutation/safety profile is covered. The description usefully adds that the change is persisted to ~/.polopan/region.json and scoped per-country, but it does not say whether an existing default for that country is overwritten or what happens if the address belongs to a different country.

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 the verb first and zero wasted words. The persistence path is appended without diluting the core action.

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

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

For a one-parameter mutation with no output schema and safety annotations already present, the description covers what changes and where it is stored. It stops short of describing replacement semantics for an existing default or error conditions, but nothing critical for 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 description coverage is 100% for the single address_id parameter, so the baseline is 3. The description only reinforces that the address must be 'existing' and implies its country drives the scope; it adds no format 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 (set as default), the resource (an existing saved address), and the scope (default shipping address for its country). This clearly separates it from address.save (create), address.delete, and region.set_current (region-wide default).

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 word 'existing' implies a precondition that the address must already be saved, which implicitly routes creation to address.save, but no sibling is named and there is no explicit when-to-use/when-not guidance. Usage is inferable 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 readOnlyHint=true and destructiveHint=false, so the safety profile is partly covered. The description usefully adds that it is a 'read-only link generator with no persistent state modifications or charges,' auto-resolves the variant index when only a size string is given, and encodes coupon/quantity into the URL. It stops short of describing edge cases (e.g. invalid size_index, missing variant, coupon rejection), which keeps it below a 5.

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

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

The sectioned structure (purpose, when-to-use, when-not, behavior, params) is front-loaded and scannable, with the key output template stated first. The parameter section duplicates schema content, adding some length that does not earn its place, but the overall brevity is acceptable for a tool with this much conditional logic.

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 compensates by specifying the generated URL format and the encoded inputs, so an agent knows what to expect back. Combined with 100% schema coverage on the input side, the definition is nearly complete; only finer handling details (auto-resolution failure, coupon application) are left implicit.

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 eight parameters, and the description's 'PARAMETERS & CONSTRAINTS' section largely restates them. It adds a small amount of value by framing 'size' as user-confirmed and noting size_index is zero-based, but the nested address object is only described generically and the country parameter present in the schema is omitted from the description. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('Generate the direct 1-click checkout purchase URL') and even gives the exact URL template. It explicitly distinguishes itself from browsing links by contrasting the /{handle} vs /{handle}/{size_index} forms, so an agent can separate it from sibling products.items.get_by_handle without opening any schema.

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

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

Provides explicit WHEN TO USE ('ONLY after the user has explicitly selected and confirmed their size') and WHEN NOT TO USE ('Do NOT provide direct checkout URLs during initial browsing, shortlisting, or if size is ambiguous') with a concrete alternative (the base link). This is precisely the routing guidance an agent needs.

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 read-only/non-destructive, but the description adds real behavioral context beyond them: automatic exclusion of any look with an out-of-stock item, localization to active country/240+ regions, enrichment with purchase links and policy data, and the negative-return-days convention. This is well above the annotation baseline.

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

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

Front-loaded with purpose and routing, then organized into labeled sections that scan well. It is on the long side, and the MANDATORY AGENT INSTRUCTIONS (table rendering, checkout-link timing) lean prescriptive rather than descriptive, but each section is relevant to correct invocation.

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

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

No output schema exists, so the description carries the return burden and does so reasonably: it covers in-stock filtering, localization, purchase-link format, and policy data. It could say more about response structure (e.g. how looks and their constituent items are grouped), which is the remaining gap for a complex 8-parameter tool.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds value: it lists the valid occasion themes, interprets the gender enum ('women' or 'men'), and gives richer country examples ('US', 'United States', 'UK', 'Dubai', 'CA', 'IN') than the schema. It does not, however, explain interaction between page/page_size or mode defaults in new ways.

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 ('Discover complete curated fashion looks styled for specific occasions') and enumerates concrete occasions. It explicitly contrasts itself with products.search.text (individual products) and looks.curation.recommend (seed-product-based), so an agent can distinguish it from siblings without opening any schema.

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

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

Dedicated WHEN TO USE and WHEN NOT TO USE sections name the two alternatives and the exact conditions that select them ('outfit inspiration for events' vs 'single product category' vs 'coordinating around a specific item'). Routing is explicit and leaves nothing 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 only declare readOnlyHint/destructiveHint, but the description adds substantial non-annotation behavior: out-of-stock filtering that guarantees 100% purchasable looks, automatic localization across 240+ regions, and enrichment of items with purchase permalinks and policy strings. These are real operational traits an agent needs and cannot get from the schema or 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?

The opening paragraph is excellently front-loaded, but the PARAMETERS & CONSTRAINTS block restates the schema descriptions nearly verbatim (100% coverage), which is pure redundancy, and the MANDATORY AGENT INSTRUCTIONS section is long. Structure is good via headers, but several sentences do not earn their place.

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

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

With no output schema, the description carries the burden of describing returns and does so: it names the in-stock guarantee, permalink/policy enrichment, and localization. Combined with the styling/checkout link instructions, an agent has everything needed to call and present results correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuinely new semantics: it explains that 'handle' and 'occasion' are alternate entry paths rather than combinable filters, and supplies concrete occasion examples that constrain the free-form string. The remaining param text largely mirrors the schema, capping this at 4.

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?

First sentence states a specific verb and resource ('Get complete recommended outfits') and the two entry modes (handle vs. occasion). The disambiguation section explicitly names 'products.search.alternatives' and 'looks.curation.by_occasion' and contrasts the use cases, so an agent can select this tool without opening any sibling 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?

Contains explicit WHEN TO USE (styling a selected product, occasion discovery) and WHEN NOT TO USE clauses, each routing the agent to a named alternative tool. This is about as complete as usage guidance gets.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description only restates that ('read-only and idempotent with no persistent state modifications'), which earns no extra credit. It does add genuinely non-obvious behavior: automatic numeric/IN/UK/EU size normalization and the negative-return-days formatting rule ('-7' -> 'Exchange only 7 days'), plus the returned JSON keys. Useful, but largely a restatement of the safety profile plus output-field listing for a read-only tool with no destructive or auth risk to disclose.

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?

Well front-loaded with clear headers and the routing decision placed early, but there is notable redundancy: the read-only/idempotent claim, the size-mapping rule, and the negative-return-days rule are each stated twice, and the MANDATORY AGENT INSTRUCTIONS partially restate the BEHAVIOR and WHEN TO USE blocks.

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, and the description compensates by naming the returned fields ('is_in_stock', 'available_sizes', 'out_of_stock_sizes', 'product_details', 'shipping_policy_text', 'return_policy_text'). For a read-only inspection tool with annotations covering safety, everything an agent needs to call it correctly 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%, so the schema already documents all four parameters with the same examples. The description's 'PARAMETERS & CONSTRAINTS' section repeats handle, desired_size, and size_index but omits the 'country' parameter entirely, so it adds little and is actually less complete than the schema. Baseline 3 applies.

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

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

States a specific verb (Verify) plus a precise resource (live stock, pricing, specs, sizes for a single product handle) and enumerates the concrete outputs it computes (size-availability matrix, discount percentage, checkout permalink). It explicitly distinguishes itself from 'products.items.get_by_handle' and 'checkout.links.get_direct_url', so an agent can route without opening any schema.

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

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

Has dedicated WHEN TO USE and WHEN NOT TO USE sections naming concrete triggers (verifying a desired size before confirming a product, generating the specs table, checking return eligibility) and explicit exclusions with the correct alternatives ('products.search.text', 'products.search.image_url'). The disambiguation block also states the condition that selects the sibling over this tool.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds non-obvious behavior beyond that: a 404 on unknown handles and enrichment of the document with verified purchase URLs, which is meaningful context for interpreting results.

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?

Well front-loaded with labeled sections that make scanning easy, but the DISAMBIGUATION bullets and the WHEN NOT TO USE bullets restate the same routing guidance twice, costing some efficiency.

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 enumerates the return shape (metadata, variants, in-stock sizes, price, purchase link) and error behavior. The only gap is that the optional 'country' parameter's effect on results is never explained.

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 restates the 'handle' examples that already exist in the schema and never mentions the optional 'country' parameter at all, so it adds essentially nothing beyond the structured fields.

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 ('Fetch the raw product document and metadata for a single item by unique product handle') and explicitly names the two siblings it is not (check_stock, search.text). An agent can distinguish it from every other catalog tool 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?

Provides explicit WHEN TO USE and WHEN NOT TO USE sections plus a disambiguation block routing to alternatives by condition (known handle vs. keyword search vs. live stock). Nothing is left to inference.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered and the restated 'Read-only and idempotent' adds little. The description does add genuine behavioral context beyond annotations: dynamic in/cm conversion, fit-confidence with relaxed vs snug advice when body measurements are supplied, and a per-size 1-click checkout permalink. It stops short of describing output format or edge-case handling (e.g., product lacking a size chart).

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 and the sectioned layout (purpose, disambiguation, when/when-not, behavior, parameters) is easy to scan. It is somewhat long and has mild redundancy, notably restating the read-only/idempotent facts already in annotations and repeating example sizing questions across the purpose and WHEN TO USE sections.

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 correctly carries the return-value burden and does so concretely, enumerating the chart, measurement matrix, unit switcher, how-to-measure guidelines, and fit recommendation plus permalink. Combined with full parameter coverage, an agent has everything needed to invoke and interpret this tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description goes modestly beyond the schema by clarifying the semantic split between 'unit' (chart unit) and 'user_unit' (unit of the user's own measurements), which the schema leaves ambiguous since both default to 'in', and by explaining that user_chest/waist/hip jointly drive best-fit computation. It adds clarifying value but no new syntax 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?

The opening sentence states a specific verb (Retrieve) and enumerates the exact resource returned (size guide chart, body measurement matrix, unit switcher, fit recommendations) scoped to a product handle. It explicitly distinguishes itself from sibling 'products.items.check_stock' by mapping sizing/fit questions to this tool and inventory questions to the other, so an agent can route without opening either schema.

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

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

The definition provides explicit WHEN TO USE bullets (sizing, fit, measurements, rendering a chart), an explicit WHEN NOT TO USE exclusion (products without size variants such as accessories/bags), and names the alternative sibling plus the condition that selects it. Nothing is left to inference.

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

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

Beyond the readOnly/destructive annotations, it discloses non-obvious behavior: it auto-fetches the source product's primary image embedding, excludes the source handle from results, and returns PoloPan purchase permalinks. This is meaningful context an agent could not derive from annotations or schema.

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

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

The summary line is front-loaded and the sections are well organized, but the PARAMETERS & CONSTRAINTS block duplicates schema content verbatim, adding length without new 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?

With no output schema, the description compensates by explaining the return format (clean permalinks), the exclusion of the source item, and the localization behavior. For a 10-parameter read tool, this is complete enough to call correctly.

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

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

Schema description coverage is 100%, so all ten parameters are already documented in the schema. The description's PARAMETERS & CONSTRAINTS section largely restates the schema (enums, defaults, ranges) rather than adding new meaning, so the baseline of 3 applies.

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

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

The description states a specific verb and resource ('find visual substitute products... for a given fashion item handle using visual image similarity') and immediately disambiguates against four named siblings. An agent can select it confidently without opening any schema.

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

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

Dedicated WHEN TO USE and WHEN NOT TO USE sections name the exact scenario (cheaper/higher-end substitutes for a known handle) and route the agent to alternatives ('products.search.text', 'looks.curation.recommend', 'looks.curation.by_occasion') with the condition that selects each. Nothing is left to inference.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuine context beyond that: the image is copied to secure temporary storage that expires after expiry_hours (default 24h), MIME types are auto-resolved, and results are enriched with verified purchase links and stock metadata. It doesn't cover failure modes (e.g. unsupported format, oversized upload), so not a 5.

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

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

Front-loaded and organized under clear headers, with the disambiguation placed early. However, the 'PARAMETERS & CONSTRAINTS' block largely duplicates the schema descriptions (country, expiry_hours, content_type, mode repeated near-verbatim), adding length without new 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 16-parameter, zero-required tool with no output schema, the description is complete: it names the return shape (matching products with in-stock sizes, pricing, verified purchase URLs), explains localization to the active country/240+ regions, and documents every parameter group. An agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so baseline would be 3, but the description adds real meaning the schema does not enforce: it states that one of image_path or image_base64 is required (the schema marks zero required params, so this constraint lives only here). It also clarifies country accepts currency/city aliases and the upload-expiry semantics of expiry_hours. The remaining params largely restate 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+resource ('search PoloPan catalog products using visual image similarity' from an uploaded file/base64) and explicitly disambiguates from the two closest siblings: products.search.image_url (URL vs local/base64) and vision.outfit.detect_pieces (single garment vs full outfit). An agent can pick the correct tool without opening any schema.

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

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

Has explicit WHEN TO USE and WHEN NOT TO USE sections that name the alternative tool for each excluded case (image_url for public URLs, products.search.text for text-only). The condition selecting this tool (local file or base64 data) is stated unambiguously.

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

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

Beyond the readOnlyHint/destructiveHint annotations, the description discloses the actual pipeline (downloads image, generates embeddings, retrieves ranked matches) and the enrichment behavior (verified purchase links, stock metadata, localization to 240+ regions). It omits rate limits or failure modes on unreachable URLs, keeping it short of a 5.

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

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

Front-loaded with the core purpose and well-sectioned for scanning, but there is redundancy: the purpose, disambiguation, and parameter list repeat much of the same routing information across PURPOSE, WHEN NOT TO USE, and PARAMETERS sections. Slightly longer than necessary.

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

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

With no output schema, the description correctly compensates by describing the return payload (visually similar products with sizes, pricing, and verified purchase URLs including the URL pattern). For a 13-param read-only search tool, the coverage is 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 all 13 parameters fully; baseline is 3. The description largely restates the schema (country examples, mode semantics, sort enums) without adding format or interaction details beyond it.

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

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

States a specific verb (search), resource (catalog products), and method (visual image similarity from a URL), then explicitly distinguishes itself from three siblings by name: products.search.text, products.search.image_upload, and vision.outfit.detect_pieces. An agent can route correctly without opening any other 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?

Provides dedicated WHEN TO USE and WHEN NOT TO USE sections with concrete conditions and named alternatives for each exclusion (local/base64 images -> image_upload, text queries -> search.text, multi-garment segmentation -> detect_pieces). Nothing is left to inference.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description partly repeats that ('Read-only and idempotent'). Beyond that it adds real non-obvious behavior: automatic sanitization and enrichment of records, computed in-stock size lists, human-readable shipping/return policy strings, verified permalink construction, and the negative-return-days convention. It stops short of describing pagination limits or failure behavior, so a 4 rather than 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?

The purpose is front-loaded and the header structure is easy to scan, but the text is long and has real redundancy: the 'Distinct from products.search.image_url / alternatives / looks.curation.by_occasion' bullets in PURPOSE & DISAMBIGUATION are repeated almost verbatim in WHEN NOT TO USE. The MANDATORY AGENT INSTRUCTIONS section is presentation policy rather than tool-selection 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?

With 12 parameters, no output schema, and no nested objects, the description compensates fully: it enumerates the return payload (in-stock sizes, specs table fields, shipping/return policies, discounted pricing, permalink format) and specifies the base-link vs. checkout-link rule. Nothing an agent needs to call or present results from this tool is missing.

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

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

Schema description coverage is 100%, so the schema already documents all 12 parameters with enums, defaults, and examples. The PARAMETERS & CONSTRAINTS section largely restates the schema (mode, page, page_size, sort_by, sort_order, gender, size, price_min/max, vendor) with only marginal added nuance. Baseline 3 is appropriate when 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 first sentence names a specific verb (search), resource (PoloPan catalog products), and scope (text keyword query with optional multi-attribute filters). The disambiguation section explicitly names three siblings (products.search.image_url/image_upload, products.search.alternatives, looks.curation.by_occasion) and states how this tool differs from each.

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 are dedicated WHEN TO USE and WHEN NOT TO USE sections with concrete trigger examples ('black leather jacket', 'men linen shirts') and explicit routing rules to named alternatives for image input, substitute-finding, and outfit curation. An agent has no inference left to do.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful context by disclosing the data source (persistent local configuration at ~/.polopan/region.json), implying no network call and locally persisted state.

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 enumerating the returned fields with zero filler; every clause carries information.

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

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

With no output schema and no parameters, the description appropriately enumerates the returned values (country, currency code, symbol, phone code, catalog scope mode) and the source of truth. It stops short of describing behavior when no region is configured, which is the only 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?

The tool takes zero parameters, so the schema has nothing to document and the baseline is 4. All semantic weight falls on the described return content, which the schema does not cover.

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 (Get) plus the exact resource and the fields returned (destination country, currency code, symbol, phone code, catalog scope mode). It is clearly distinguishable from region.set_current and region.list_supported by verb 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?

Usage is only implied by the verb 'Get' and the sibling pair region.set_current / region.list_supported; there is no explicit statement of when to call this versus those alternatives or whether the state can be absent.

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

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

Annotations already declare readOnlyHint=true / destructiveHint=false, so the safety profile is covered. Beyond that, the description adds real context: the size of the dataset (240+), the fields attached to each entry (currency codes, symbols, flags, phone codes, price groups) and the fact they come from 'live platform settings' (i.e., data may change). It is silent on pagination behavior despite the limit parameter.

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 the verb first and no filler; the trailing field list is doing work by previewing the payload. Nothing could be removed without losing 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 simple, read-only, two-optional-parameter tool, the description covers purpose and the shape of the returned records, which matters because there is no output schema. Only pagination/limit interaction and any search-matching caveats remain unaddressed, and those are minor for this complexity level.

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

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

Schema description coverage is 100%, including the query field's accepted search axes and an example, so the schema already carries the parameter burden. The description echoes the search concept but adds no syntax, matching rules, or default/limit behavior beyond what the schema states. 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 pairs a specific verb ('Search') with a specific resource ('240+ supported destination countries') and enumerates the data carried on each result, so the agent knows this is a catalog/read tool rather than a lookup of the user's own region. It does not explicitly contrast itself with region.get_current / region.set_current, but the scope is unambiguous.

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

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

Usage is only implied: calling it a search over 'supported destination countries' hints at discovery/validation use cases, but there is no statement of when to prefer this over region.get_current or the address.* tools, and no prerequisites or exclusions are given. Minimum viable guidance, nothing more.

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 readOnlyHint=false and destructiveHint=false; the description adds the genuinely useful behavioral fact that the value is written to a persistent local JSON file (~/.polopan/region.json) and survives across turns and sessions. It does not say what happens on an unrecognized region or whether validation failures are possible, which keeps it below a 5.

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

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

Two sentences, both front-loaded: the first covers accepted inputs, the second covers the persistence side effect. No filler and no repetition of the title.

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

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

There is no output schema, and the description covers the action, the input flexibility, and the side effect, which is nearly everything an agent needs to call a 2-parameter setter. It omits error/validation behavior for invalid regions and whether the call requires prior authentication.

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 real semantic value by enumerating the accepted input variants (natural name, city, ISO-2, currency) and giving concrete examples that clarify the loosely typed 'country' string. It does not explain the interaction between the 'country' and 'mode' parameters.

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 (Set) and resource (active shopping country/region) and implicitly distinguishes itself from region.get_current and region.list_supported by describing the write action and what it accepts. An agent can tell exactly what this tool mutates 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?

The description gives a rich and explicit set of accepted input forms (country name, city, ISO-2 code, currency) and explains the persistence rationale. It stops short of naming sibling alternatives (e.g., region.list_supported to discover valid values, region.get_current to read the current value), so routing is implied rather than stated.

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

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

While annotations already declare readOnlyHint and destructiveHint, the description goes further by stating the tool is 'read-only and idempotent' and specifies the input methods (image_path, image_base64, image_url) with the constraint that exactly one must be provided. It also discloses the output structure (label, confidence, box) and the threshold's range, adding valuable context beyond 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?

The description is well-organized with clear sections (PURPOSE, WHEN, BEHAVIOR, PARAMETERS) and avoids redundancy. It is longer than minimal but each sentence serves a purpose, such as disambiguation and usage rules. Slight redundancy exists in the parameter explanations (schema already contains similar), but it remains focused.

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 the tool's moderate complexity (4 params, no output schema), the description is exceptionally complete. It covers purpose, disambiguation, usage rules, behavioral details, input constraints, and return format. An agent has everything needed to correctly invoke the tool without additional research.

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

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

The schema already covers all parameters (100% coverage), but the description adds practical context for each, such as example paths, the meaning of threshold, and the exact-one-source constraint. It also clarifies the output format, which is not in the schema, providing extra value for parameter usage.

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 the tool's purpose: deconstructing outfit images into individual fashion pieces with bounding boxes and confidence scores. It lists the piece types (e.g., Upper-body garment, Dress, Footwear) and explicitly distinguishes it from sibling tools like products.search.image_url, making its unique role 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 description provides explicit WHEN TO USE and WHEN NOT TO USE sections, detailing scenarios for multi-piece outfit images versus single garments, and contrasts it with text-based search. This directly guides the agent on when to select this tool over alternatives like products.search.image_url or looks.curation.recommend.

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