commercebridge

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

Annotations already indicate the tool is read-only, idempotent, and non-destructive. The description adds valuable context beyond annotations by disclosing the current deployment status and specific error states ('not_found', 'credentials_required') and the dependency on BESTBUY_API_KEY. This is transparent about operational caveats.

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 concise and front-loaded with the core purpose in the first sentence. The second sentence, while detailed, is necessary for operational transparency. No wasteful content, though the error explanation could be slightly more succinct.

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 simple one-parameter schema, presence of annotations, and output schema absence, the description covers the essential context: what the tool does, the parameter, and current error behavior. The vague 'full detail' is acceptable for a get-by-SKU tool, but a note on return format would make it 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?

The input schema fully describes the sole parameter 'sku' with an example, and the description adds no extra semantic meaning beyond 'by SKU.' Schema coverage is 100%, 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 clearly states the tool's action: 'Get one Best Buy product by SKU, full detail.' It specifies the resource (Best Buy product), the identifier (SKU), and the depth of information (full detail), distinguishing it from sibling tools that target other marketplaces or search functionality.

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

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

The description implies usage when you have a SKU and need full product details, but it does not explicitly contrast itself with the sibling search_bestbuy tool or provide exclusions. There is no guidance on when not to use this tool, though the purpose is self-evident.

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 meaningful behavioral context by disclosing a specific failure mode: 'Returns an honest `credentials_required` error until the upstream deployment has eBay app credentials provisioned.' This alerts the agent to potential auth-related failures and is beyond the structured 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 two sentences with no filler. The first sentence front-loads the purpose and key fields, the second adds a critical error behavior note. Every word 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 simple single-item lookup with no output schema, the description adequately covers what the caller receives (the list of fields), how to identify the item (id or legacy_id), and a notable failure condition. No critical 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% (all three parameters have descriptions). The description's mention of 'REST item id or legacy numeric id' reinforces the relationship between `id` and `legacy_id`, but this is already conveyed in the schema (legacy_id says 'used when `id` is omitted'). No additional semantic value beyond the schema is provided.

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

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

The description uses a specific verb and resource: 'Get one eBay item's full detail' and enumerates the included fields (description, brand/MPN/GTIN, color, item specifics, images, return terms, availability, item end date). The 'one' and 'by REST item id or legacy numeric id' clearly distinguish it from the sibling get_ebay_items, which implies bulk retrieval.

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 clearly states the input mode ('by REST item id or legacy numeric id') and the singular scope ('one eBay item'), making the use case evident when a specific item ID is held. However, it does not explicitly mention alternatives like search_ebay or get_ebay_items for broader queries, nor does it state when not to use 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, idempotentHint, and destructiveHint. The description adds the credential dependency, warning that a `credentials_required` error will be returned until credentials are provisioned, which is valuable behavioral 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?

Two sentences, both purposeful: one describes the core function, the other a relevant operational caveat. No redundant 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?

With only 2 parameters and rich annotations, the description addresses the main functionality and the credential error. It does not specify return structure, but no output schema exists, and the phrase 'full item detail' hints at the return. Adequate for the tool's simplicity.

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 covers both parameters with descriptions, including the required comma-separated item_ids with max 20 and the optional country enum. The description merely reiterates the schema details without adding new 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?

The description uses a specific verb 'Bulk-fetch' and identifies the resource 'full item detail for up to 20 eBay items in a single call', clearly distinguishing from the singular sibling tool get_ebay_item. The title reinforces the batch capability.

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

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

The description implies batch usage with 'Bulk-fetch' and 'up to 20', but does not explicitly contrast with get_ebay_item or specify when not to use. There are no alternative tool references 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?

Beyond the readOnlyHint and idempotentHint annotations, the description honestly discloses current error states (`not_found`, `credentials_required`), the dependency on ETSY_KEYSTRING/ETSY_SHARED_SECRET, and the Etsy API quirk regarding `views`. It also notes the upstream deployment status, which is valuable behavioral context for an agent.

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 two sentences that pack in the core purpose, the unique `views` behavior, the operational status, and the two relevant error modes. Every phrase earns its place; no filler or duplication.

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 conveys that the response is 'full detail' and specifically flags the `views` field as populated only here. It also explains expected error modes and credential prerequisites. While it doesn't enumerate all return fields, 'full detail' plus the unique field mention sufficiently covers this simple get-by-id tool given its siblings provide 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?

The input schema already provides descriptions for both `language` and `listing_id` (100% coverage). The description adds minimal parameter-specific semantics: it reiterates the importance of `listing_id` via 'by id' and mentions credential requirements, but does not enrich the meaning of the `language` parameter 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 opens with 'Get one Etsy listing by id, full detail' – a specific verb (get), resource (Etsy listing by id), and scope (full detail). It explicitly distinguishes itself from sibling search and shop-listing tools by calling out the unique `views` field behavior, making the purpose unmistakable.

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 clear context for when to use this endpoint: when a single listing's full detail is needed, especially if `views` is required, since search and shop-listings endpoints return `views: null`. It names the alternative categories (search and shop-listings) without being exhaustive, but the core usage trigager is 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 declare read-only, idempotent, non-destructive behavior. The description goes beyond this by disclosing specific error states ('not_found' and 'credentials_required') and their causes (route not redeployed, missing ETSY_KEYSTRING/ETSY_SHARED_SECRET). This is valuable operational context not available in 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 two sentences and front-loads the primary purpose before providing error caveats. The error detail is relevant for managing agent expectations, and no unnecessary words are present, though it could be slightly more compact.

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 get tool with no output schema, the description covers the returned fields, identifier options, and error states including upstream deployment and credential requirements. This sufficiently prepares the agent to invoke the tool and interpret failures, making it complete for its 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% with descriptions and examples for both parameters. The description adds minimal semantic value beyond saying 'by shop_id or shop_name', which is already conveyed by the schema's descriptions. No additional parameter format or usage details are provided, 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 clearly states the tool gets one Etsy shop by shop_id or shop_name and lists the specific data returned (name, listing counts, favorites, total sold, review count/average). This distinguishes it from sibling tools like get_etsy_listing and get_etsy_shop_listings, which focus on different resources.

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

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

The description implies usage for retrieving a single shop's aggregate data, with shop_id or shop_name as identifiers. It does not explicitly name alternative tools or state when not to use this tool, but the context is clear enough given the sibling tool names. The error-note also informs about environmental prerequisites, adding situational guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds valuable context about current operational limitations, specifically that it may return 'not_found' until redeployed and 'credentials_required' if Etsy keys are not provisioned. This goes beyond annotations and helps the agent anticipate failures.

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 concise and front-loaded with the primary purpose in the first sentence. The second sentence provides essential operational caveats without unnecessary filler. Every sentence earns its place, and the structure is clear and scannable.

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 list operation with no output schema, the description explains the scope (active listings, optional filter) and the current error states, which is important for invocation. It does not mention pagination behavior, but the schema covers limit/offset defaults. Given the tool's simplicity and annotations, this is sufficiently complete, though a brief note on return format would elevate it.

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 input schema has descriptions for 71% of parameters (5 out of 7), and the description adds only minor value by noting the keyword filter is optional. It does not elaborate on limit, offset, sort_on, or sort_order, but the schema already covers these adequately, so the 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 clearly states the tool's purpose: 'List one Etsy shop's active listings, optionally keyword-filtered within the shop.' It specifies the resource (one Etsy shop), the action (list listings), and scope (active, keyword-filtered). This distinguishes it from siblings like get_etsy_listing (single listing) and search_etsy (cross-shop search).

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 conveys clear usage context by identifying that it operates on a single shop and allows optional filtering, implicitly differentiating it from broader search tools. However, it does not explicitly state when not to use this tool or name alternative tools, so it lacks the explicit 'when/when-not' guidance 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 already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds meaningful extra context, including 'keyless' (no authentication required) and 'live now' (fresh data), plus a list of returned fields. This goes beyond the structured annotations without contradicting them.

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, dense sentence that front-loads the purpose, specifies output fields, and includes access mode and freshness. There is no fluff or redundancy.

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

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

The tool is a simple list operation with robust schema and annotations. The description names output fields and clarifies the public, keyless nature. It does not explicitly state pagination behavior, but the schema already provides page and limit details, so the description is sufficiently 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%, with all three parameters having descriptions (store, page, limit). The description itself does not add additional parameter-level meaning beyond what the schema already provides, so the baseline of 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 uses a specific verb ('List') and resource ('public Shopify store's collections'), and enumerates the returned fields (id, handle, title, product count, image). This clearly distinguishes it from sibling tools like get_shopify_product and search_shopify.

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 clear context: it is for listing public Shopify collections and emphasizes 'keyless, live now.' It does not explicitly state when to use it over alternatives or when not to use it, 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 already cover readOnly, idempotent, openWorld, and non-destructive behavior. The description adds 'keyless' (no auth needed), 'live now' (real-time fetch), and the specific source endpoint, which are valuable beyond the annotations. Missing details like error handling are minor for this simple 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?

The description is a single concise sentence that front-loads the primary action and key constraints, with zero filler or redundancy.

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

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

For a simple two-parameter read-only tool with strong annotations, the description covers the essential context (public store, keyless, live, source endpoint). It does not explain return format, but without an output schema and given the simplicity, this is an acceptable 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%, with both parameters (store and handle) already described with examples and types. The description mentions 'handle (slug)' which is redundant with the schema, so it does not add meaningful semantics beyond what the schema 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 clearly states the verb 'Get', the resource 'one product from a public Shopify store by its handle (slug)', and distinguishes it from siblings like search_shopify_products by focusing on a single product. It also adds a specific data source (/products.json), making the purpose 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 implies when to use this tool: when you have a store and handle for a public Shopify product and need keyless, live data. It does not explicitly name alternatives or when-not-to-use, but the context from title and sibling tools provides sufficient guidance.

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

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

Beyond annotations, the description discloses non-obvious behavior: dependence on Best Buy's official Products API, the specific return fields, and two operational error states ('not_found' and 'credentials_required') with context on when they occur. This adds significant transparency.

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 cover purpose, return data, and error behavior. Each sentence earns its place, though the last sentence about deployment status is slightly verbose. Overall well-structured and front-loaded with purpose.

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

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

Given no output schema, the description compensates by listing return fields. It also covers error scenarios and API source. It doesn't mention rate limits or pagination behavior, but these are partially addressed in the schema. Overall complete for a search 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 baseline is 3. The description adds no substantive parameter details beyond what the schema already provides (e.g., 'keyword and/or category' mirrors the 'q' and 'category' 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 clearly states the tool's function with a specific verb and resource: 'Search Best Buy's US product catalog by keyword and/or category.' It also distinguishes itself from siblings like get_bestbuy_product and other retailer-specific search tools, providing clear scope.

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 conveys when to use the tool (for searching by keyword and/or category) and implies 'get_bestbuy_product' is for direct product retrieval. However, it doesn't explicitly name alternatives or provide 'when not to use' scenarios, so it misses the top criterion.

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 and idempotent behavior. The description adds valuable context beyond annotations: it mentions the credential error behavior and the official API backend. No contradiction with annotations exists.

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

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

The description consists of three concise sentences: purpose and scope, output fields, and error behavior. Every sentence earns its place with no waste or redundancy.

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 lists output fields, covers site scope, and discloses the credential error. Since there is no output schema, listing the returned fields is valuable. It does not explicitly state that q or category is required, but the schema covers that. Overall, it is fairly complete for a 12-parameter search 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 75%, so baseline is 3. The description adds only a high-level mention of keyword/category and the 8 sites, without diving into individual parameter meanings. It does not significantly improve parameter understanding over 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 description clearly states it searches live eBay listings by keyword and/or category across 8 sites, built on eBay's official Browse API. It also lists the specific fields returned (id, title, price, condition, etc.), which differentiates it from sibling tools like search_ebay_sold and get_ebay_item by scope and output detail.

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 clear context (live listings, 8 sites, Browse API) but does not explicitly state when to use this tool versus alternatives like search_ebay_sold. No exclusions or comparisons are given, leaving the usage guidance implied but not 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, openWorldHint, idempotentHint, and non-destructive behavior, but the description adds crucial context: the 501 not_enabled response is expected until the limited-release API is enabled, and this is honest behavior rather than a bug. This goes well beyond the structured 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 three compact sentences with the purpose front-loaded in the first phrase. The second sentence explains the prerequisite, and the third sets failure expectations. There is no filler or repetition of schema/annotation details.

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 purpose, prerequisite, and failure behavior, which is strong given the annotations and simple schema. It does not describe the successful return format, but for a gated tool that may always return 501, this is less critical. Overall, it is nearly complete for the tool's 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?

The input schema already fully describes q as 'Keyword query,' with 100% schema description coverage. The description does not add additional parameter-level detail, but given the schema's completeness, none is necessary. The tool-level context about sold items is useful but not parameter-specific.

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

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

The description opens with 'Sold/completed-item price comps,' which is a specific verb+resource statement that clearly identifies this as a search for sold eBay listings. This distinguishes it from sibling tools like search_ebay and the various get_* tools.

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

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

The description provides explicit context about the prerequisite: it needs eBay's Marketplace Insights API, which requires a separate limited-release approval. It also clearly states that until enabled, the tool always returns a 501 gate, which tells the agent when to expect failure. However, it does not explicitly name an alternative tool for active listings.

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

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

Beyond the annotations (readOnlyHint, idempotentHint), the description adds substantial context: auth model ('app-only, no OAuth'), return fields (title, description, price, etc.), and honest error disclosure ('currently returns not_found... then credentials_required...'). This greatly informs the agent about expected behavior and prerequisites.

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, dense paragraph that front-loads the purpose and then provides return fields and error status. The error disclosure is detailed but relevant. It could be split into clearer sentences, but it remains efficient and 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 12-parameter search tool with no output schema, the description covers key context: return fields, auth requirements, and error behavior. It lacks explicit pagination semantics and doesn't explain optional filters, but the schema documents several of those. Overall, it provides enough for basic usage.

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 only 58%, yet the description does not compensate for the gaps. It only implies 'q' via 'by keyword' but leaves parameters like max_price, min_price, shop_location, sort_on, and sort_order unexplained. No additional meaning is provided beyond the sparse schema 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 clearly states 'Search Etsy's site-wide active listings by keyword', specifying both the resource (Etsy active listings) and the operation (keyword search). It distinguishes from sibling tools like get_etsy_listing or search_ebay by emphasizing 'site-wide' and 'built on Etsy's official Open API v3'.

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

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

The description implies usage for keyword-based site-wide search but does not explicitly state when to use this tool versus alternatives like get_etsy_listing or search_ebay. There are no exclusions or when-not guidance, so the context is clear but not 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 mark the tool as read-only, idempotent, and non-destructive. The description adds valuable context beyond annotations: it specifies that the store must be public, requires no key, operates on live data, and searches specific fields. This meaningfully clarifies 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?

The description is a single, tightly written sentence with no filler. It front-loads the core action and includes only high-signal additions ('keyless, live now') that are not redundantly stated in the annotations.

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 simplicity, strong annotations, and fully documented schema, the description covers the key operational context: public access, keyless usage, live data, and search scope. It does not describe return format, but no output schema exists and the absence is acceptable for a straightforward search 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%, providing descriptions for all three parameters. The description adds extra meaning by listing which fields the keyword applies to ('title, vendor, product type, and tags'), enriching the semantics of the 'q' parameter beyond the schema's basic example.

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 ('Filter') and resource ('public Shopify store's catalog') with clear scope ('by keyword across title, vendor, product type, and tags'). It is unambiguous, though it does not explicitly distinguish itself from the sibling tool 'search_shopify_products'.

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

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

The description implies usage for public Shopify stores with no API key ('keyless, live now'), but it does not state when to use this tool instead of alternatives like 'search_shopify_products', nor does it mention any exclusions or 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 cover read-only, idempotent, and open-world behavior. The description adds valuable context beyond that: it fetches directly from the store's own /products.json, requires no keys or auth, and specifies the returned fields. This enriches the safety profile without contradicting it.

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

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

The description is two sentences, front-loaded with the core action, and every sentence provides useful information: the source, the no-auth guarantee, the return fields, and the input example. No filler or redundancy.

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

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

For a read-only list tool with no output schema, the description effectively communicates what the user gets (specific product fields and URL). It omits pagination specifics but the schema includes page/limit, and the overall invocation model is clear. Slightly more detail on limit defaults or edge cases could make it complete, but current coverage is strong.

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 parameters. The description adds a concrete example for the store parameter and clarifies it should be a bare storefront domain (no protocol), which is a small but helpful refinement over the schema's generic 'Shopify store domain'.

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 verb 'List' and the resource 'any public Shopify store's product catalog', explicitly mentioning the ~/products.json endpoint. It distinguishes itself from siblings like get_shopify_product (single product) and search_shopify (search-oriented) by emphasizing full catalog listing with no auth.

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 context: use this to list the full catalog of any public Shopify store, and provides input format guidance ('bare storefront domain'). However, it does not explicitly mention sibling alternatives or conditions where another tool would be more appropriate, so it falls 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.