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

Goes well beyond the readOnly/idempotent annotations: it discloses the shrinkage ranking algorithm (rating pulled toward candidate average until ~20 ratings), the cheaper-wins tie-break, the all-query-words-in-title match rule, and that accessories are dropped. This is exactly the non-obvious behavior an agent needs to trust and interpret the output.

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 dense sentences, front-loaded with purpose, then algorithm, then usage/follow-ups. No filler, though the middle sentence packs several rules together and reads slightly heavy.

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?

An output schema exists so return format need not be described; annotations cover safety. Purpose, ranking behavior, query semantics, and downstream tool routing are all present, leaving nothing an agent needs to invoke this correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it explains that min_price defaults to a floor that drops accessories when a query is present, and clarifies the query-title matching semantics that govern how 'query' behaves.

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

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

Specific verb ('rank') plus resource ('best-rated in-stock products') plus scope ('within a budget'), and the ranking criterion is stated. An agent can distinguish this from dk_best_sellers and dk_find_cheapest 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?

Gives an explicit trigger phrase ('best X under Y Toman') and routes follow-ups (dk_product for seller prices, dk_reviews for buyer sentiment). It lacks an explicit when-not / alternative-tool condition (e.g., vs. dk_best_sellers or dk_find_cheapest), 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 declare readOnly, idempotent, openWorld and non-destructive, which covers the safety profile. The description adds that main categories with ids come back in the response, a useful behavioral detail, but says nothing about result ordering, pagination, or truncation behavior at the limit cap.

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

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

Two short sentences with the primary action and scope stated first and the follow-up workflow second; nothing is redundant and no filler is present.

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 an output schema present, return values need not be explained, and the description does the extra job of flagging the category-id handoff. It is nearly complete, though it never clarifies that results are ranked by sales volume or what happens to limit behavior, which are minor gaps for a 2-param read tool.

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

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

Schema description coverage is 100%, so both limit and category_id are already fully documented in the schema, including the leaf-id rejection rule and the example id. The description only restates the overall-vs-one-category notion, adding no syntax or format detail beyond structured data.

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 Digikala's current best-selling products) plus the scope axis (overall or one main category), which sets it apart from leaf-level tools like dk_category_products. No sibling is named explicitly, so an agent still has to infer the boundary versus dk_deals or dk_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 second sentence describes a concrete two-step workflow: read the returned main categories and their ids, then call again with category_id. It does not state when to prefer this over dk_category_products, dk_deals, or dk_search, so exclusions are missing but usable context is present.

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 only adds that prices are in Toman; it says nothing about pagination limits or result caps beyond what the schema already states. Adequate but thin 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 short sentences with zero filler; the core capability is front-loaded and the routing caveat follows immediately. Every clause earns its place.

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

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

An output schema exists, so return values need no explanation, and annotations cover safety. Scope, filters, currency and the sibling alternative are all present, leaving nothing an agent needs to call this correctly.

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

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

Schema description coverage is 100%, so all six parameters are already documented in the schema (page size, sort enum, price bounds, brand_code format, stock filter). The description reinforces the Toman currency for the price filters but adds no syntax or semantics the schema lacks. Baseline 3 applies 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?

States a specific verb and resource ('List a brand's products on Digikala') plus the facets it supports (sort and price filters). It explicitly separates itself from the closest sibling by name, so an agent can distinguish it from dk_category_products 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 second sentence gives an explicit routing rule: for one brand inside one category, use dk_category_products with brand_code instead. That names the alternative and the condition that selects it, which is exactly the when-to-use 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 cover read-only/idempotent safety. The description adds a critical nuance: the Persian vs English search coverage difference and the accessory-mixing behavior in parent categories, which go beyond annotations. It doesn't discuss limits or output structure (though output schema exists), so not perfect.

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 output types then describes modes cleanly. It's not overly long, but the parenthetical about Persian and the final caution sentence could be tighter. Still, every sentence provides useful 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 an output schema present and annotations covering safety, the description fills the remaining gaps: the relationship to sibling tools, the parameters' effects, and the accessory caveat. 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 is 3. The description adds real semantic value: it explains what each parameter does in terms of the result set (query matches name/code, parent_id lists children, neither returns top-level), and gives a concrete example of Persian vs English behavior. This goes beyond the schema's simple 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 names the specific artifact this tool produces (category codes for dk_category_products and main-category ids for dk_best_sellers), which explicitly connects it to sibling tools and distinguishes it from dk_search, dk_suggest, etc. The purpose is concrete and actionable.

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 explains the three modes (query, parent_id, neither) and gives a behavioral caveat about mixed accessories. It doesn't explicitly compare against siblings like dk_search or dk_suggest, so it's slightly short of the top score, but the mode explanations are strong 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 annotations already declare the read-only, idempotent, open-world, non-destructive safety profile. The description adds useful behavioral context beyond them: currency is Toman, text queries are ignored, and attribute filters require IDs from dk_filters. It does not add deeper details such as pagination behavior or rate limits, but with annotations covering safety that is acceptable.

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 short and front-loaded: it starts with the core action, then gives examples, then the dk_filters prerequisite, then the text-query caveat. Every sentence adds distinct routing or prerequisite information with no 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?

Given the 13-parameter schema, full parameter descriptions, an output schema, and rich annotations, the description supplies everything an agent needs for correct selection and invocation. Return values are handled by the output schema, and parameter details are handled by the input schema, so no critical context 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 13 parameters fully. The description mentions filter categories and gives a couple of examples such as category_code='notebook-netbook-ultrabook' and brand_code='xiaomi', but it does not add syntax or constraints beyond what the schema provides. 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 products of one category, with sort and filters. It also distinguishes the tool from text search by noting that the API ignores text queries here, and gives concrete browsing examples, so an agent can identify the tool's role without opening the schema.

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

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

It gives explicit use cases ('cheapest laptops', 'best-selling Xiaomi phones'), an exclusion ('API ignores text queries here'), and a prerequisite/alternative route for attribute filtering ('get the attribute and value ids from dk_filters(category_code=...) first'). This is close to complete routing guidance.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds real behavioral context beyond that: null means a missing spec, identical rows are folded into `same_specs`, and unknown ids are dropped and reported in `missing_ids`.

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

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

Front-loaded with the core action in the first clause, then dense but useful detail about the return semantics. Two short paragraphs, no filler, though the second paragraph is tightly packed.

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?

An output schema exists so return values need not be explained, yet the description still clarifies the key semantic conventions (ordering, nulls, folding, missing ids). The only gap is absence of explicit alternative-tool routing.

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% for the single parameter, so baseline is 3. The description adds meaning by stating that `values` follow the order of `products`, which tells the agent that input ordering is preserved and significant.

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 with scope: 'Compare 2-4 products side by side: price and rating, then the spec rows where they differ.' An agent can tell this is a multi-product comparison rather than a single-product lookup, though no sibling (e.g. dk_similar, dk_product) is named to sharpen the boundary.

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

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

'Works best for products of the same category' implies when the tool is appropriate, and the 2-4 bound is stated. However, there is no explicit when-to-use/when-not guidance and no routing to alternatives such as dk_product for a single item.

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. The description adds meaningful context beyond annotations: ranking rule (biggest discount first), in-stock filtering, returned fields (discount_pct, price_before_discount, deal_ends), timezone (Tehran), and store-specific behavior. It doesn't disclose pagination size or sort overrides, but the annotations lower the bar and the description meaningfully supplements 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?

Three sentences, front-loaded with the key action and scope, then field-level detail, then a use-case cue. No filler; each sentence contributes relevant 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?

Given annotations and a 100%-covered schema plus an output schema, the description is nearly complete. It covers ranking, filtering, returned fields, timezone, and store variants. Minor gaps remain around pagination and sort override interactions, but the essentials for correct invocation are 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 all six parameters are already documented in the schema. The description reinforces the store semantics and note about Tehran time, but adds little beyond the schema. Baseline 3 is appropriate given the schema's completeness.

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 today's Incredible Offers (flash deals)'), and adds discriminating scope: biggest discount first, in-stock only. An agent can distinguish this from dk_search (general search) and dk_find_cheapest (price-focused) without opening the schema.

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

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

Gives a clear usage trigger ('Use for "best discounts right now"') and a store variant condition. It does not explicitly name which sibling to use for non-deal searches, but the implicit contrast with dk_search is reasonable. Lacks explicit when-not-to-use 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 readOnly, idempotent, non-destructive, open-world, so the safety profile is covered. The description adds real behavioral detail beyond that: truncated attributes expose only value_count and require a second call with attribute_id, and the return shape differs by mode (brands for category, categories for query).

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 purpose before the return-shape detail, and every sentence carries operational information (value truncation, downstream id passing). It is dense and paragraph-heavy, but no sentence is redundant with 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 an output schema present the description need not document return values, yet it does so usefully enough to explain the truncation/re-call loop and the mode-dependent outputs. Coverage of inputs, outputs, and follow-up actions is sufficient for correct invocation.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds conditional semantics the schema does not: brand_code is category-only, the query mode returns spanned categories rather than brands, and attribute_id is the documented remedy for the value_count truncation.

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 filters Digikala offers for a category or a search') and enumerates the filter families returned (features, colors, sellers, price range). It also names the downstream siblings (dk_category_products, dk_search), so an agent can place it precisely among the 22 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?

Clearly routes the agent: 'Pass the ids to dk_category_products or dk_search' with the exact argument shapes, and gives the re-call procedure when an attribute exceeds 15 values. It lacks an explicit statement of when to prefer category_code vs query or what to do if neither is supplied, but the practical usage path is unambiguous.

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

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

Annotations already declare read-only, idempotent and non-destructive, so the bar is low, yet the description adds substantial non-obvious behavior: the scan is deliberately bounded to relevance pages because the full catalogue is 'full of cheap accessories', matching requires all query words in the title with a documented fallback (any word, flagged with a `note`), 'suitable for ...' accessories are dropped, and sorting uses the buy-box price in Toman.

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

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

The core capability and the follow-up recommendation are front-loaded and every clause carries information, but the single dense paragraph of matching mechanics is slightly run-on and would read faster as a short list of the filtering rules.

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?

An output schema exists, so return values need no explanation, and the description covers the non-obvious parts an agent needs: bounded scanning, word-matching rules with fallback, accessory filtering, price semantics in Toman, and the recommended next call. Nothing material is missing for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds design intent the schema lacks: it explains why only the most relevant search pages are scanned (tying to `pages`) and why a min-price floor exists (dropping cheap accessories), reinforcing the min_price default documented in 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 with scope qualifiers ('cheapest in-stock products that really match a query, one flat list sorted by price'), which is clearly distinguishable from dk_search, dk_deals and dk_best_sellers. An agent can select this tool from the name plus the first sentence 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?

Gives an explicit trigger phrase ('Use for "cheapest X"') and a follow-up action with its rationale ('Then call dk_product on the winner: another seller may offer it for less'), which routes a multi-step workflow. It stops short of naming when not to use it (e.g. vs dk_deals or dk_search), so it is clear context without 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, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds behavioral value beyond that: 'Browsing a category also returns its sub-categories' and the category_code-over-query precedence rule. It stops short of describing no-argument behavior or result/pagination traits.

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 kept to three short, information-dense statements with no filler. The domain parenthetical and the two follow-up sentences each carry distinct guidance. Slightly more than strictly needed, but nothing that wastes the reader's time.

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 7-parameter search tool the description covers purpose, the key parameter interaction, and an alternative route. Return values need not be explained because an output schema exists, and annotations carry the safety profile. The remaining gap is sibling routing (dk_search/dk_categories), which is not addressed.

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 documents each parameter and the baseline is 3. The description adds interaction semantics the schema lacks: 'category_code takes precedence over query' and that category browsing returns sub-categories. This is real added meaning above the field-level docs.

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 pair (search/browse) and a precisely scoped resource: 'Digikala Fresh (the supermarket: dairy, groceries, drinks, hygiene).' The parenthetical domain listing distinguishes it functionally from general product search, but it never names dk_search or dk_category_products explicitly, so full sibling differentiation is left to inference.

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 use context (grocery/supermarket products) and an explicit alternative for a sub-case: 'For grocery discounts use dk_deals(store='supermarket').' The category-vs-query precedence rule further guides invocation. However, the primary alternative dk_search is not mentioned, so exclusions for general queries are incomplete.

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

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

Annotations already declare readOnly, idempotent, non-destructive and openWorld, so the safety profile is covered. The description adds real behavioral context beyond that: the period semantics of gold18_day_change_pct vs gold18_period_change_pct/low/high, and critically that a null coin price means 'not for sale right now'. That null-value meaning is not something annotations would convey.

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

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

Three sentences, front-loaded with the core purpose and scope, then field semantics. Every sentence carries information. The second sentence is dense with field names, but nothing is filler or redundant.

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

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

An output schema exists, so return structure needn't be spelled out. The description nonetheless supplies interpretation rules (change_pct period undocumented for coins, null = unavailable) that an agent needs to read the output correctly. Missing only explicit usage/routing guidance and any freshness/cadence note beyond 'live'.

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

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

Zero parameters, so by the rubric this is a baseline 4. The description does define the meaning of returned fields (day vs period change, null price semantics), which is beyond the no-parameter schema and helps interpretation, though these are response fields rather than inputs.

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: 'Get Digikala's live 18k gold price per gram and gold coin prices, in Toman.' No sibling tool in the list deals with gold/coins, so it is trivially distinguishable from dk_search, dk_product, dk_price_history etc. An agent knows exactly what this returns.

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: the agent infers 'call this for gold/coin prices' from the purpose statement. There is no explicit when-to-use or when-not-to-use guidance, nor a pointer to dk_price_history as the historical alternative for other assets. The implicit '~3-month chart' reference hints at the covered window but does not route the agent anywhere.

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 call; the description adds substantial non-obvious behavior: plans are fixed credit lines not sized to price, unknown ids yield no plans, Digipay approval is required, and the credit/price interaction at checkout is unconfirmed.

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, then layers caveats and routing in short sentences that each carry weight. It is slightly dense with caveats, but nothing is filler or redundant.

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

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

With an output schema present, return-value exposition is unnecessary, and the description still covers the interpretive caveats an agent needs (fixed credit line, approval gating, empty result on bad id, unconfirmed checkout combination). Nothing material is missing for correct invocation.

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

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

Schema coverage is 100% and the single product_id parameter is fully documented in the schema (format, example, 'dkp-<id>' origin). The description adds behavioral meaning ('an unknown id gives no plans') but nothing about parameter format beyond what the schema supplies, so the baseline 3 applies.

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

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

States a specific verb and resource — 'Get the Digipay credit-line offers available when buying a product' — with the unit (Toman). It clearly distinguishes itself from sibling pricing tools like dk_price_history and dk_product by naming the credit-line semantics.

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

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

Explicitly routes the agent to dk_product for the product price and to validate a product id, which is actionable guidance. It does not, however, state when to prefer this over the similarly-named dk_plus_plans sibling, leaving one plausible alternative unaddressed.

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/openWorld/idempotent/non-destructive, so safety is covered. The description adds genuinely useful behavioral context beyond them: that prices are location-independent and location only affects checkout delivery options, which tells the agent when calling this is worthwhile. It does not cover error behavior or matching fallbacks.

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

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

Three short sentences, front-loaded with the core purpose, then the invocation rule, then the relevance caveat. No filler or restatement of the name.

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?

An output schema exists, so return values need not be explained, and all four parameters are fully documented in the schema. Combined with the usage rule and relevance caveat, nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds the mutual-exclusivity/pairing rule for the two modes (address+city vs lat+long), which the flat schema does not express, so it earns above baseline.

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

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

States a precise verb+resource pair ('turn an address into coordinates, or coordinates into an address') and names the concrete domain artifacts returned (city_id, state_id). It is clearly distinguishable from every sibling, which are all search/product/review tools.

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

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

Explicitly tells the agent which parameter combinations are valid ('Pass address + city, or lat + long') and when this tool is relevant ('location only matters for delivery options shown at checkout'). It does not name alternative tools or state exclusions, 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.

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

Annotations already declare this as a safe, idempotent, open-world read. The description adds genuinely new behavioral context: the meaning of 'jet' (same-day Tehran/Karaj) and 'fresh' (supermarket), and the caveat that exact shipping fees only appear at checkout.

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

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

Front-loaded with the core action, then the usage cue and caveats in two tight sentences. No filler, though the parenthetical detail about jet/fresh adds length that could be trimmed if space were at a premium.

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 zero parameters and an output schema present, the description does not need to explain return values; it covers purpose, benefits, and the checkout-fee caveat. Sufficient for an agent to call it correctly, with only minor room for extra routing detail.

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

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

The tool takes zero parameters, so per the rubric the baseline is 4. There is nothing further for the description to disambiguate on the parameter side.

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 Digikala Plus membership plans') plus the returned content (price in Toman and benefits). No sibling tool covers Plus memberships, so it is clearly distinguishable from the search/category/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?

'Use when shipping cost matters' gives a concrete triggering condition and explains why (free deliveries per month). It stops short of naming alternatives or when-not-to-use cases, so it is strong context without full routing guidance.

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

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

Annotations already establish it as a read-only, idempotent, non-destructive, open-world operation. Beyond that, the description discloses the time window, currency, per-variant granularity, the distinction between lowest and lowest_2_days, Jalali date format, omission of days when a variant was not for sale, and unknown-id 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 definition is front-loaded with the core capability, then layers in the key nuances. Every sentence contributes either scope, usage context, or an edge case, with no filler.

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

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

Given a rich output schema and full annotation coverage, the description still supplies the essential behavioral details an agent needs: date format, currency, variant granularity, what lowest vs. lowest_2_days means, and how missing sale days are handled.

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

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

The schema fully documents product_id, so the baseline is 3. The description adds meaningful parameter behavior by stating that an unknown id yields no variants and suggesting validation via dk_product, which is useful context 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 description states a specific verb and resource: it retrieves roughly 30 days of daily buy-box prices per color/variant, with lowest and highest values. It distinguishes the tool from siblings by focusing on historical price evaluation and explicitly routes id validation to dk_product.

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

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

It gives a clear use case — answering "is this a good price right now?" — and explains how to handle an unknown id by checking with dk_product. It does not explicitly name alternatives or when not to use it, so it falls just short of full routing guidance.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower, yet the description adds substantial behavior: exact offer field meanings (price in Toman, stock_left only shown when low, seller rating 0-5, ships_by values decoded, free_shipping), the caveat that lowest_price_30d can be a one-day dip, and that exact shipping cost is only known at checkout.

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

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

The purpose and returned-field inventory are front-loaded, and virtually every sentence carries non-obvious information (enum meanings, price-source caveats). Some sentences are densely run-on (the ships_by clause), which slightly hurts readability but wastes little space.

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 an output schema present, the description need not explain return values, yet it goes further by decoding offer fields and flagging cross-tool price discrepancies. Combined with the annotations, an agent has everything needed to call this correctly and interpret the result.

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 product_id, max_offers and include_specs are already documented in the schema; baseline 3 applies. The description adds no further parameter guidance (e.g. it never mentions the 50-offer cap or the specs toggle), so it does not exceed 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 ('Get one product's price, stock, rating, specs and every seller's offer') with scope qualifiers ('cheapest first'). It even differentiates itself from siblings by naming dk_search, dk_compare and dk_price_history, so an agent can tell the detailed single-product view apart from the search/compare 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?

Clear context is implied throughout: this is the per-product detail tool, and the caveat that grocery items' prices differ from what dk_search/dk_compare/dk_price_history show tells the agent which source wins for supermarket items. There is no explicit 'use this instead of X when Y' routing statement, 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.

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 bar is lower, yet the description adds real behavioral detail: answer-count cap, the answered_by taxonomy, 20 items per page, and 300-character truncation of long texts. These caveats materially affect how an agent interprets 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?

Two tight sentences, zero waste, with the core function and result shape front-loaded before the pagination/truncation caveats and the usage hint. Every clause earns its place.

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

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

With an output schema present, return values need not be described, and the description still covers pagination, truncation and answer limits. Only minor gaps remain (empty-result behavior, no cross-reference to dk_reviews), which is enough for a 4 but not 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%, so the baseline is 3. The description's page-size note actually corrects the schema's mislabeled '20 products per page' to 20 questions per page, but it adds nothing about the sort enum or the product_id format beyond what the schema already documents.

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

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

States a specific verb (read) and resource (customers' questions about a product) and even bounds the payload ('up to 2 answers each'). It doesn't explicitly name the sibling it differs from (dk_reviews), but an agent can still tell it apart by the resource noun.

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: 'Use for practical doubts (compatibility, size, registration).' That is concrete when-to-use guidance. It stops short of stating when-not-to-use or pointing at dk_reviews/dk_product as alternatives, so it isn't 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 the safety profile (readOnly, idempotent, non-destructive), and the description adds genuinely new behavior: page size of 20, long texts truncated at 300 characters, null meaning "no stars given", and empty results for unknown ids. These are exactly the traits that would otherwise surprise a caller.

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

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

Three short sentences, front-loaded with what is returned, then pagination/truncation limits, then the error-handling hint. No filler and no repetition of 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?

For a read-only paginated list tool with a full output schema and complete annotation coverage, the description supplies everything an agent still needs: what comes back, how much per page, truncation, and what an empty result implies.

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, and the description adds value by clarifying the page size ("20 per page"), which usefully corrects the schema's mislabeled "20 products per page" text on the page parameter. It says nothing extra about the sort enum values beyond the schema's own ordering description.

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 ("Read customer reviews of a product") and enumerates the returned fields (stars, text, pros/cons, verified buyer flag). It also distinguishes itself from the sibling dk_product by noting that the overall rating lives there rather than here.

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

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

Gives a concrete routing rule for the failure case: an unknown id returns no reviews, so validate it with dk_product first, and it redirects the agent to dk_product for the aggregate rating. It stops short of stating when to prefer this over other sibling tools (e.g., dk_questions for Q&A), but the context it does give is actionable.

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 substantial behavior: 20 results per page, the match/'all'|'some'|'none' relevance semantics, API ordering quirks with brand_ids+price range, and the caveat that cheaper items can land on later pages.

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 capability and page size, then caveats and routing. Every sentence carries operational information, though the later sentences are dense and clause-heavy, requiring careful parsing.

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?

Output schema exists so return values need not be explained, and the description covers the remaining gaps an agent needs: pagination size, relevance semantics, filter-id sourcing, sort pitfalls, and the correct sibling for edge cases. Nothing essential is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning beyond the schema: where color/brand/attribute ids come from (dk_filters, dk_product's brand_id), the attribute OR/AND semantics, and the price-ordering caveat tied to sort/brand_ids. It does not fully document every one of the 12 params in prose, so not a 5.

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

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

States a specific verb+resource ('Search Digikala products by name') plus the returned facets (price in Toman, discount, seller, rating). It explicitly routes to siblings — dk_filters for filters, dk_suggest/dk_categories for category codes, dk_category_products for a brand in a category — so an agent can distinguish it without opening another schema.

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

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

Gives explicit when-to-use and when-to-use-something-else rules: sort=cheapest surfaces cheap accessories so use dk_find_cheapest for the cheapest real match; brand_ids+price range reorders per category and dk_category_products keeps a strict order. Names prerequisites (filter ids from dk_filters) and follow-ups (dk_product for all offers).

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 as a safe, read-only, idempotent, non-destructive operation, so the safety profile is fully covered. The description adds valuable clarification about the reputation metric semantics ('Percentages are the share of good orders (100 = never late / never cancelled / never returned)'), which is not in annotations and helps interpret results. It does not discuss output schema details, but the presence of an output schema lessens that burden.

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

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

The description is concise and front-loaded: first sentence states what the tool does, second gives usage guidance, third clarifies metric semantics. It could be slightly more efficient, but every sentence 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?

Given annotations cover safety and an output schema exists, the description provides sufficient context for correct invocation: it clarifies the meaning of the reputation metrics, which is neither in annotations nor schema. It doesn't explain pagination or sorting behavior, but the schema covers those parameters. Complete enough for an agent 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 four parameters (page, sort, seller_code, in_stock_only) are fully documented in the schema. The description adds no parameter-specific syntax or constraints beyond what the schema already provides, so 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 ('Get a marketplace seller's reputation ... and products') and enumerates the reputation facets (rating 0-5, on-time shipping, cancellations, returns). This is clearly distinguishable from sibling tools like dk_product, dk_best_sellers, or dk_reviews, which target products or reviews rather than seller profiles.

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 context for use ('Use before recommending an offer from a seller you don't know'), which tells the agent when to reach for this tool. It does not, however, name alternative siblings or state when NOT to use it (e.g., when the seller is already known), leaving some guidance implicit.

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, so the safety profile is covered. The description goes further by clarifying output-field semantics that are easy to misread: cheapest_offer can undercut price, low_30d requires a two-day hold, and lowest_one_day_30d is Digikala's own one-day-dip figure. This is genuine added context beyond structured fields, though it stops short of describing rate limits or failure modes.

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 primary action and scope are front-loaded in the first sentence, with usage and field semantics following. The explanation of the three low-price fields is dense but earns its place by preventing misreading; a little tightening could still be done.

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 an output schema present, the description needn't re-document return values, and with annotations covering safety it covers selection, usage context, sibling routing, and the semantic traps in the returned metrics. Nothing an agent needs to call this correctly is missing.

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

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

There is a single parameter with 100% schema description coverage and schema-level min/max constraints, so baseline is 3. The description's 'up to 10 products in one call' merely restates maxItems=10 and adds no new syntactic 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?

The description opens with a precise verb+resource+scope: 'Re-price up to 10 products in one call', then enumerates exactly what it returns (price, cheapest offer, stock, rating, 30-day low). It is immediately distinguishable from siblings like dk_compare and dk_price_history, which it names explicitly.

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

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

It states both when to use it 'to refresh a list the user is watching or deciding between, or to check a saved product is still in stock' and when not to, routing specs side-by-side to dk_compare and the daily curve to dk_price_history. Nothing about tool selection 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, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is fully covered by structured data. The description adds only the scoping sense of "similar" and the cheapest-sort trick, but says nothing about result volume or pagination behavior beyond what the schema states.

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

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

Two short sentences with zero filler; the core purpose leads and the two routing hints follow. 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?

An output schema exists, so return values need no explanation, and annotations carry the safety profile. What remains unaddressed is how this tool relates to the overlapping sibling dk_find_cheapest and how paging behaves in practice, leaving a small ambiguity for the agent.

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 goes beyond the schema by attaching intent to a specific enum value: sort='cheapest' yields cheaper alternatives. That is genuine semantic value the bare "Order of the results" schema text does not convey.

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 products similar to one product") and immediately disambiguates the fuzzy word "similar" as "same kind, other models and brands." It also names the sibling to use instead for comparison (dk_compare), so an agent can place it against alternatives without reading schemas.

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 actionable routing: use sort='cheapest' for cheaper alternatives, and use dk_compare to compare two or more products. It lacks explicit when-not guidance (e.g., versus dk_search, dk_find_cheapest, or dk_category_products for browsing a category), so the alternative space is only partially mapped.

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, destructiveHint=false and openWorldHint=true, so the safety profile is fully covered without the description. The description adds only that the tool normalizes partial/misspelled input into keywords, categories and brands, which is mildly useful but not rich behavioral context.

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

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

Two short sentences, front-loaded with the core action and followed by the usage condition and next steps. There is minor blank-line padding but no wasted clauses.

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

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

For a single-parameter read tool with an output schema, the description supplies everything needed to decide to call it and what to do with the result. Return-value details are correctly left to the output schema.

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

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

Schema description coverage is 100% and the single 'query' parameter is documented in the schema with examples and length bounds. The description adds the notion of a 'vague or partial' query, but no syntax or format detail beyond what the schema already provides, so the baseline 3 applies.

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

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

States a specific verb ('Autocomplete') and the transformation applied to the resource (a vague/partial query into search words, categories and brands). It also names the sibling tools it feeds into (dk_search, dk_category_products), so an agent can distinguish its role from those search tools 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?

Gives a clear triggering condition ('when the user's words are unclear or misspelled') and routes the agent to the correct follow-up call with the suggested output type. No explicit when-not-to-use case is given, so it falls short of full 5-level guidance, but the context is unambiguous.

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