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

The annotations already declare read-only, open-world, idempotent, and non-destructive behavior, so the safety profile is fully covered elsewhere. The description adds the useful detail that the brand slug comes from site links, but it does not add much about pagination, rate limits, or return behavior beyond the schema.

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

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

The description is two tight sentences, front-loaded with the core action and followed by the key usage constraint. Every sentence adds routing or scope 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 list tool with rich parameter descriptions and full safety annotations, the definition covers purpose, slug source, and the main sibling alternative. It does not describe the shape of returned product results, but no output schema exists and the remaining gaps are minor.

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

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

Schema description coverage is 100%, and the schema already documents slug format, page size, and sort values. The description only reinforces where the slug comes from; it does not add new meaning for page or sort 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 states a specific verb and resource: list products of one brand page on Snapp! Shop. It also distinguishes this from ss_category by explaining that category-scoped brand browsing belongs to the other tool.

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 explicitly says to use this tool when the brand slug is known, notes where slugs come from, and routes category-specific brand lookups to ss_category. That is clear when-to-use guidance with a named alternative.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive, so safety needs no restating. The description usefully adds the hierarchical drill-down behavior and mentions brand pages appearing below categories, but says nothing about recursion depth limits, result-set size, or what happens with an invalid path.

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

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

Two sentences with zero filler; the identity of the output ('`path` values') comes first and the iterative usage pattern follows. Nothing needs trimming or reordering.

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-optional-parameter read tool with no output schema, the description covers what it returns, how to call it, and how to walk the hierarchy. The only real gap is whether traversal bottoms out at the subcategory/brand-page level or continues deeper.

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

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

Schema coverage is 100% and the `parent` property already documents the empty-string/null top-level case with an example. The description adds a little meaning by implying the parent value must be a path previously returned by this same tool, but it repeats the schema's own 'no argument' semantics rather than extending them. 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 ('List Snapp! Shop categories') and specifies the returned shape as `path` values, explicitly tying that output to the sibling ss_category. An agent can distinguish this from ss_search, ss_suggest, and ss_filters without reading 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?

Gives an explicit call pattern: invoke with no argument for top-level, then again with a returned path for subcategories and brand pages. This implicitly sequences the tool before ss_category, though it never states exclusions (e.g., don't use this to search by keyword), so routing is clear but not fully disambiguated from all siblings.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and non-destructive behavior. The description adds a non-obvious behavioral constraint: top-level category paths return no product list, so subcategories are required. It does not discuss pagination, rate limits, or return shape, but the annotations cover the safety profile.

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 main purpose is front-loaded, followed by prerequisites and the important top-level path caveat.

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 10-parameter read-only listing tool with full schema coverage and no output schema, the description supplies purpose, dependencies, and the critical path constraint. It omits return shape and pagination details, though the schema documents page size and item count.

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 detailed per-parameter descriptions for page size, price currency, sort options, spec format, colour format, and boolean filters. The description restates the filter categories and points to ss_filters for spec names, but adds little beyond the already-rich schema. Baseline 3 is appropriate.

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

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

The description states a specific verb and resource: 'List the products of one Snapp! Shop category or category-brand page,' with the filter scope explicitly named. It also distinguishes its role from ss_categories and ss_filters by referencing them as prerequisite/helper 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?

It gives clear usage context: use after ss_categories, and ss_filters shows spec names. It also provides a concrete exclusion: a top-level path such as 'mobile' has no product list, so the agent must pick a subcategory. It does not explicitly compare against siblings like ss_search for non-category product discovery, but the guidance is strong.

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

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

The annotations already cover read-only, idempotent, non-destructive, and open-world behavior; the description adds the collection-source dependency and supported collection types. It does not clarify paginated retrieval, and "every product" could imply an exhaustive single response despite the schema specifying 12 items per page.

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 single sentence is compact, front-loaded with the operation, and uses parenthetical examples efficiently. There is no filler or redundant explanation of the three parameters.

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?

Together with the complete schema and safety annotations, the description supplies enough context for a straightforward collection-listing call. Its completeness is limited by the lack of explicit pagination or exhaustiveness guidance and any sibling-selection guidance, especially with no output schema to clarify result granularity.

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

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

Schema coverage is 100%, and id, page, and sort already document their formats, defaults, and constraints. The description largely repeats the id's origin and collection types, with "see all" list as only a small addition, so the high-coverage baseline 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?

"List every product" identifies the operation and resource, while "one promotion collection" and the examples establish precise scope. Naming ss_promotions as the source also distinguishes it from the general search, category, and product siblings.

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 establishes a clear workflow: obtain a promotion collection from ss_promotions, then list its products. It does not explain when to prefer ss_search, ss_category, or ss_product, so the guidance is contextual rather than exhaustive.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the description's job is to add behavior — and it does, disclosing that `specs` is filtered to rows whose values differ and returned in product order. That is non-obvious output semantics an agent could not infer. It does not discuss failure modes such as an invalid or missing product id, which keeps it below 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 with zero filler. The returned fields come first, the workflow guidance and the non-obvious filtering rule follow — properly front-loaded.

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 one parameter, no nested objects and no output schema, the description carries the burden of describing the result — and it does list the compared fields and the differing-spec rule. It leaves the response's exact shape (how products are keyed, what happens with 2 vs 4 products) unspecified, a minor gap 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 coverage is 100%, so the schema already documents the id formats, the 2-4 bounds and the array type. The description only reiterates the 2-4 range and adds the ordering note ('in product order'), which is marginal added meaning. 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 (compare products side by side) plus the exact dimensions returned (price, rating, seller count, differing specs). An agent can distinguish this from ss_search or ss_product without opening any schema.

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

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

Explicitly positions the tool in a workflow: 'Use after ss_search to choose between candidates.' That names the prerequisite sibling clearly. It stops short of saying when not to use it (e.g., single-product lookups belong to ss_product), so it is strong context rather than complete routing.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered. The description adds the useful fact that the response enumerates the available filter dimensions (price range, colours, brands, specs), which matters because there is no output schema. It omits edge behavior such as unexpected results for an unknown category path or precedence when both inputs are given.

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

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

Two short sentences: capability and output content first, then the input requirement and the cross-tool naming hint. Nothing is padded and nothing important is buried.

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

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

For a simple two-parameter read-only lookup with no output schema, the description covers what the tool returns and how to supply inputs. The only meaningful gap is the undefined behavior when both or neither of path/query are passed.

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

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

Schema coverage is 100%, so both parameters are already documented, and the description repeats some of that (path from ss_categories, query as in ss_search). It does add one genuinely new constraint: the inputs are alternatives ("Give `path` or `query`"), which the schema does not encode since both are nullable with no oneOf.

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?

"Show the filters Snapp! Shop offers for a category or search" names a specific verb (show/list) and resource (filters), then enumerates what the filters cover (price range, colours, brands, spec filters). An agent can distinguish it from ss_category and ss_search, which return products rather than filter metadata, though the description never explicitly frames that contrast.

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?

"Give `path` or `query`" plus the pointer to reuse names from specs/colors/brands of ss_category and ss_search gives clear invocation and chaining guidance. It stops short of explicit exclusions or precedence rules (what to do if both or neither are supplied), so it is clear context rather than full when/when-not guidance.

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

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

The description adds crucial behavioral information not covered by annotations or schema. It specifies that offers are sorted 'cheapest first,' and informs the agent that the returned 'id' is intended to feed downstream tools like ss_reviews and ss_similar.

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 highly efficient, front-loading the primary value proposition and then systematically adding technical and operational constraints (sorting, currency, downstream usage) in logical sequence.

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?

Despite not having an output schema, the description provides sufficient context on the tool's data structure by listing retrieved attributes (specs, rating, price, stock, delivery) and crucial operational details like pricing currency and downstream ID 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?

The description significantly enhances the parameter schema by detailing the acceptable formats for the `product` input. It clarifies that the input can be a standard ID, a specific 'snp-<digits>' format, or a full snappshop.ir product URL.

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 immediately specifies the tool's function: to retrieve details, specs, ratings, pricing, stock, and delivery for a single product. It clearly positions itself as a detailed retrieval function distinct from search or category discovery siblings.

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?

While it doesn't explicitly list sibling exclusion criteria, it clearly defines the tool's scope by focusing on retrieving 'one product' rather than searching for them. The structure implies usage when a specific product identifier or URL is known.

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

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

The annotations already establish a safe, read-only, idempotent operation, while the description adds useful result behavior: flash sales include end times, product sections expose downstream `collection_id` values, and slugs can be found in site links. It does not cover freshness or empty-page behavior, but those omissions are modest for this simple discovery 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 front-loads the tool's purpose and then gives two compact integration details. Every phrase contributes either scope, output context, or invocation guidance without repetition.

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

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

For a read-only tool with one optional, fully documented parameter, the description and schema together provide enough information to select a page, understand the promotional content, and continue to `ss_collection`. Although there is no output schema, the description adequately summarizes the important returned elements and identifiers.

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 fully documents the optional `page` parameter, including its default, supported patterns, and examples. The statement that slugs appear in site links adds practical guidance for discovering the `<slug>` values needed to invoke non-default pages.

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—showing what Snapp! Shop is promoting—and concretely identifies flash sales, carousels, campaign pages, and top products. The `collection_id` handoff to `ss_collection` also helps distinguish its promotional-discovery role from the sibling collection tool.

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

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

It provides clear context for browsing promotions and directs the agent to `ss_collection` when it needs all products from a product section. It does not explicitly state when not to use the tool or contrast it with search and category siblings.

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

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

Annotations already declare a safe, idempotent, read-only, open-world read, so the burden is light. The description adds genuinely useful context beyond them: reviewer names are omitted (anonymized data), and the exact shape of each review record is disclosed even though no output schema exists. It does not mention review volume, sorting, or result totals.

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

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

Two short sentences, front-loaded with what the tool returns and followed by when to use it. Every clause carries information; nothing is repeated from the schema or 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?

With no output schema, the field enumeration is exactly what an agent needs to know what comes back, and the anonymization note and paging are covered. It leaves minor gaps around total review counts and any ordering of results, which matters somewhat for a paged list.

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%: the `id` parameter already documents the 6-character format and its provenance from ss_search/ss_product, and `page` documents the 10-per-page paging with min/max bounds. The description adds no meaning beyond this, so the baseline of 3 applies.

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

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

The description gives a specific verb and resource ('Read buyers' reviews of a product') and enumerates the returned fields (score, title, text, pros/cons, helpful votes, date), which makes the scope unambiguous. It stops short of naming sibling tools such as ss_product or ss_similar to explain the boundary, so it is clear but not fully sibling-differentiated within the description text itself.

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 to check quality complaints before recommending a product' supplies a concrete decision context for reaching for this tool rather than product metadata tools. There are no explicit exclusions or stated alternatives, so the guidance is clear but one-sided.

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

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

Annotations already cover the safety profile (readOnly, idempotent, openWorld, non-destructive), and the description adds behaviour the agent could not infer: no-match queries silently degrade to unrelated items, so titles must be verified. It also discloses currency (Toman) and delivery region (Tehran), though it says nothing about rate limits or result-size limits.

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

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

Four tight sentences, front-loaded with purpose before the chaining and fallback caveats. The parenthetical sibling references are efficient; nothing is filler, though the filter list in sentence one partially duplicates the schema.

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

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

With 11 parameters and no output schema, the description does useful duty by naming the returned `id`, `product_id` and first-page `brands` fields. It still leaves pagination behaviour, total result counts and the shape of the fallback result undescribed, which matters for a search tool the agent will chain from.

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 11 parameters are already well documented; the description mostly restates the filter categories at a high level. The one real addition is cross-call provenance for the brands filter (ids harvested from an earlier response's `brands` array), which reinforces what the schema says but does not extend 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 and resource ('Search Snapp! Shop products by name') plus the exact filter axes, which cleanly separates it from ss_category (browse) and ss_product (detail fetch). The sibling differentiation is explicit through the id/product_id handoff.

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 first to find a product' gives a clear entry-point rule and names the downstream tools each returned id feeds. It stops short of saying when to prefer ss_category, ss_filters or ss_suggest instead, so it is strong routing guidance but not a full when/when-not matrix.

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

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

Annotations already declare readOnly, idempotent, non-destructive, open-world behavior, so safety is covered. The description adds only the scoping idea ('one seller'), saying nothing about result volume, pagination behavior, or whether unavailable products are included.

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 earning their place: the first defines the operation and scope, the second routes the agent from ss_product. Purpose is front-loaded with zero filler.

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

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

For a simple read-only 3-parameter list tool with fully described parameters and explicit annotations, the description covers what an agent needs to select and call it. Only the shape of returned items is unstated, which is a minor gap given no output schema exists.

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%: page size/limits, sort enums and their default, and the seller_id source are all documented in the schema. The description implies seller_id comes from an ss_product offer but adds no syntax or format 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 and resource ('List the products one seller offers on Snapp! Shop') and explicitly differentiates from the sibling ss_product by framing this as the follow-up step after reading an offer there.

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

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

Gives a clear usage context ('after reading its offer in ss_product') that tells an agent when this tool fits rather than ss_product. It stops short of naming alternatives for broader product discovery (ss_search, ss_category) or stating exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered. The description adds a useful data-shape note ('Items have the same fields as ss_search') but says nothing about result volume, ordering, or whether an empty list is possible for a product with no substitutes.

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

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

Two short sentences, front-loaded with the action and the data-shape note placed second where it belongs. No redundant restatement of the title or parameters.

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 'same fields as ss_search' pointer does meaningful work in place of one. Still, for a lookup tool in an open-world catalog, it omits anything about result size, pagination, or empty-result behavior, leaving a real gap for an agent planning a call.

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

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

Schema coverage is 100%, including a documented enum for `kind`, so the schema carries parameter meaning on its own. The description adds no extra semantics about `id` or `category_id` beyond what the schema states; baseline 3 applies.

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

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

States a specific verb and resource ('Find alternatives to a product') and anchors it to a concrete surface ('similar products' section of Snapp! Shop). It implicitly distinguishes itself from ss_search by tying its results back to that tool's field set, though it never names the closest sibling (ss_compare) to contrast with.

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 to compare prices of close substitutes' gives an intended context, which is better than nothing. But there is no when-not guidance and no mention of ss_compare, the obvious sibling for comparison tasks, so an agent must infer the boundary between the two on its own.

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

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

Annotations already declare readOnly, idempotent, open-world and non-destructive, so the safety profile is covered. The description adds genuinely new behavior: results are ordered by search popularity and the payload contains `terms` with a `score`. It does not discuss limits on how many suggestions are returned, but the added context is real.

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

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

Two tight sentences with zero filler; the ordering semantics come first and the sibling routing second. 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?

With no output schema, the description usefully discloses the return shape (`terms` plus popularity `score`). For a one-parameter read-only tool this is close to complete; only result-count or truncation behavior is left unstated.

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

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

Schema coverage is 100% and the single parameter is already documented as 'Start of a search phrase', so the description only restates the prefix nature of the input via the search-box analogy. Baseline 3 is appropriate since the schema does the work.

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 (complete a phrase) and resource (search phrase/autocomplete), plus the ordering rule 'most searched first'. This is clearly distinct from ss_search, which returns actual results rather than phrase completions.

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 to find the popular wording before ss_search' names the sibling alternative and the sequencing condition that selects it. It stops short of stating when not to bother (e.g., when the user already has exact wording), so it is strong but not exhaustive.

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