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

Annotations already cover safety (readOnly, idempotent, non-destructive, openWorld), so the bar is lower; the description still adds real behavior: the weighted-rating rule, the tie-breaker, and that queries require every word in the title and drop accessories. It stops short of noting result size or pagination limits of the scan.

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

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

Three tight sentences, front-loaded with the purpose, then the ranking rule, then the usage cue. Dense but every sentence carries information; only slight terseness ('Use for "best X under Y"') costs it a point.

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

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

For a 7-parameter, no-output-schema, open-world tool, the description covers what the tool does to the data (filter, drop accessories, weight ratings) and what to do next. It omits any hint of the returned shape, which is the only notable gap.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds semantics the schema does not: query matching requires every word in the title and drops accessories, and min_price defaults to a floor that filters accessories when a query is given. That meaningfully clarifies two of the seven parameters.

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

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

States a specific verb (rank) plus resource (best-rated in-stock products) and the exact ordering key (rating weighted by count, ties to cheaper). This clearly separates it from siblings such as dk_search, dk_best_sellers, and dk_find_cheapest.

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') and chains the follow-up tools (dk_product, dk_reviews). It does not, however, state when to prefer this over similar siblings like dk_best_sellers or dk_find_cheapest, so exclusions are missing.

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 one genuine behavioral trait beyond the annotations: the response also carries the main category ids usable as category_id. It says nothing about ordering, result size limits, or failure behavior.

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

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

A single compact sentence with the core purpose front-loaded before the secondary return-value detail. The trailing clause about returning category ids is slightly compressed and grammatically awkward, but nothing is wasted.

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 two-parameter, read-only list tool with no output schema, the description covers what it returns at a high level and how to source the optional category_id. Missing only result ordering and the effect of limit defaults, which 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 coverage is 100%, so the baseline is 3, but the description adds real meaning: it clarifies that category_id accepts only main categories and that the tool itself returns those ids, making the input self-servicing. limit's semantics are left entirely to 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 best sellers) and adds scope (overall or within one main category), which separates it from dk_category_products and dk_search. It does not explicitly name a sibling it is not, so it stops short of a 5.

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

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

The description implies usage via the category_id sourcing note (dk_categories or this tool's own `categories` output), which is useful chaining guidance. However, it never says when to prefer this over dk_category_products, dk_deals, or dk_search, and gives no 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 the Toman currency and a hint about a returned brand id, but says nothing about pagination limits beyond the schema, result size, or failure modes. Modest added value over the annotations.

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

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

Two short sentences with the core capability front-loaded and the disambiguation second. The parenthetical '(Toman)' and the 'brand id for brand_ids' fragment are slightly cryptic but cost 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?

There is no output schema, so the description carries some burden for return shape; it only gestures at 'the brand id' without describing the product list structure or the 20-per-page behavior (which lives in the schema). Given full param coverage and full annotations, it is adequate but leaves the response format underspecified.

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 every parameter (page, sort enum, min/max price, brand_code pattern, in_stock_only) is already documented in the schema. The description only restates currency units and filter categories. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb+resource ('List a brand's products') and names the filter dimensions (sort, price). It also differentiates from the sibling dk_category_products. The trailing clause 'plus the brand id for brand_ids' is ambiguous about what is actually returned, which keeps it short of a 5.

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

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

Explicitly routes the agent to the alternative: 'For one brand inside one category use dk_category_products(brand_code=...).' That gives a clear when-to-use-this-instead condition. It doesn't cover other siblings (dk_search, dk_best_sellers) or when a brand-level browse is the wrong entry point.

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 safety (readOnly, idempotent, non-destructive), and the description adds genuinely useful behavior beyond them: Persian queries match more terms than English codes, and parent_id/query never surface main categories. The accessory-mixing caveat for categories with subcategories is real operational 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?

Purpose is front-loaded in a short first sentence and the rest is dense with semicolon-separated rules rather than filler. Slightly compressed but every clause carries information; minor awkwardness in the wrapped formatting.

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, yet the description still explains what is returned (category codes for dk_category_products, main-category ids for dk_best_sellers) and the matching rules. The one remaining gap is that it names the 'main categories' limitation without offering a path to retrieve them.

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% (baseline 3), but the description adds meaning the schema lacks: a Persian-vs-English matching asymmetry with a concrete example, and the fact that parent_id lists children whereas query/parent_id together still omit main categories.

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 category codes ... main-category ids') and immediately connects the output to the two siblings that consume it (dk_category_products, dk_best_sellers), so an agent can distinguish this lookup tool from the product-listing 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 concrete per-parameter routing: query matches name/code, parent_id lists children, and 'neither lists the main categories' flags a limitation. It also implicitly routes the agent to browse the product leaf for accessories, but no explicit sibling alternative is named as a fallback for the main-category gap it calls out.

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

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

Annotations already declare this a read-only, idempotent, non-destructive open-world read, so the safety profile is covered. The description adds the currency unit (Toman) and ID-provenance requirements, but says nothing about rate limits, auth, or result shape, and 'strict order' is vague filler rather than a disclosed 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?

Two compact sentences with examples doing real work and the core purpose front-loaded. Minor waste in the unexplained phrase 'strict order', which costs a point.

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

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

For a 13-parameter tool with one required field and no output schema, the description covers purpose, ID sources, and search exclusion, and the schema itself is richly documented. It still leaves the return shape (result fields, total counts) unaddressed, which matters more here because 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% and every parameter already carries an example, so the baseline is 3. The description mostly duplicates that (brand_code='xiaomi', category slug, Toman pricing) and only adds cross-tool provenance for feature/attribute ids.

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 (List), resource (one category's products), and scope (sort + filters, single category, no text query). It explicitly carves itself out from the text-search sibling with 'No text query here' and the worked examples ('cheapest laptops', 'best-selling Xiaomi phones') make the intent unmistakable.

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

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

Gives concrete when-to-use examples and dependency routing ('Feature ids come from dk_filters(category_code=...)'), plus an implicit exclusion of text-query tools. It stops short of naming dk_search or dk_brand_products as the alternative for those cases, so the routing is suggested rather than explicit.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds substantive behavior beyond them: how missing/unknown ids surface (missing_ids), how identical spec rows collapse (same_specs), positional alignment of values to products with null meaning absent, and which side wins ties ('best within one category'). That is useful non-obvious context for an annotated read 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?

Three short, front-loaded lines with no filler; the core action comes first and the field-name semantics follow. Slightly telegraphic phrasing ('Best within one category') costs a little clarity but nothing is wasted.

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 must carry the return contract, and it largely does: comparison shape, differing-row filtering, same_specs, missing_ids. It omits error behavior for invalid counts or mismatched product kinds, but a 1-parameter read-only tool is otherwise sufficiently covered.

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 fully documented there, so baseline is 3. The description goes beyond the schema by explaining how the result relates back to the input ordering (`values` follows `products`, null = no such spec), which is semantics an agent needs to read the response correctly.

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

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

States a specific verb and resource ('Compare 2-4 products side by side') plus the scope and the exact outputs it produces (price/rating, differing spec rows). No sibling tool does product-vs-product comparison, so the agent can distinguish it from dk_product, dk_search, or dk_shortlist at a glance.

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 never states when to choose this over alternatives such as dk_product (single lookup) or dk_shortlist, nor any preconditions (all ids must be the same kind is only in the schema). Usage is inferable from the verb, but no explicit routing guidance is given.

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

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

Annotations already declare this a safe, idempotent, read-only call. Beyond that, the description discloses genuinely new behavior: results are constrained to in-stock items, sorted by biggest discount by default, and each product returns discount_pct, price_before_discount and deal_ends in Tehran time. That timezone note matters for a time-sensitive field and is not derivable from structured data.

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 paragraphs, front-loaded with what the tool returns and how it is scoped. Both sentences carry non-redundant information given there is no output schema. Minor slack in restating the store mapping that the schema also covers.

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 explains the returned fields and their timezone, plus the in-stock filter and default sort. Pagination is left to the schema and there is no mention of rate limits, but for a read-only listing tool the agent has enough 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 description coverage is 100%, so every parameter is already documented in the schema, which sets the baseline at 3. The description reinforces the store semantics and default ordering but adds no format or constraint detail beyond what the schema states. The one extra value-add, the Tehran timezone, concerns output rather than a parameter.

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 ('List today's Incredible Offers'), clarifying it is a curated deals feed rather than a general search. The in-stock-only and default-sort modifiers pin down the scope further. It does not name sibling tools (e.g. dk_search, dk_find_cheapest) to differentiate, so it stops short of a 5.

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

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

It implies when to use it (browsing live flash deals) and clarifies that store='supermarket' switches to Fresh grocery deals, which is decision-relevant routing. However, it never states exclusions or explicitly contrasts with alternatives such as dk_search or dk_find_cheapest, leaving the agent to infer which deals tool to pick.

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 the safety profile (readOnly, idempotent, non-destructive, openWorld), so the description only needs to add operational detail — and it does. It discloses the response shapes ({value title: id}, {title: id}, {code: id}, {code: title}) and the non-obvious truncation behavior for large attribute sets that forces a second call. Since there is no output schema, this disclosure is doing real work.

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 statement is front-loaded in the first sentence, and the remaining lines are dense but each carries a distinct fact (return shapes, recursion rule, downstream consumption). The telegraphic brace/semicolon shorthand is efficient but costs some readability, keeping it from a 5.

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

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

With no output schema, the description carries the return-value burden and does so by describing each filter's shape. It covers both operating modes, the two-call workaround for large attribute sets, and how the ids feed into sibling tools. Minor gaps remain (e.g. seller_type semantics, price-range format beyond Toman), so 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, but the description adds mode-dependent meaning the schema does not state cleanly: brands use {code: id} in category mode, categories use {code: title} in query mode. That clarifies which parameters are applicable in which operating mode, going beyond the per-field schema text.

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 of a category or a search' — and enumerates the filter kinds returned (attributes, colors, sellers, price range, brands). It also names the consumer tools (dk_category_products, dk_search), which separates it from siblings like dk_categories or dk_suggest. It stops short of explicitly contrasting itself with those 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?

Gives concrete when-to-use direction: pass the returned ids to dk_category_products or dk_search, and it names the exact parameter names to use. It also handles the edge case explicitly — an attribute with over 15 values returns only value_count, so call again with attribute_id. No explicit when-not-to-use or exclusions, so not 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/openWorld/idempotent/non-destructive, so safety is covered. The description adds real behavioral detail beyond that: it scans the top relevant results, keeps titles containing every query word (falling back to any word with a `note`), and drops accessories. That matching-relaxation behavior is exactly the kind of thing an agent cannot infer from annotations or schema.

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

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

Three compact sentences, front-loaded with purpose then matching logic then routing; nothing is filler. The mid-sentence line break before the backticked `note` makes the structure slightly choppier than ideal, keeping it just under a 5.

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

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

For a 5-parameter, no-output-schema lookup tool, the description covers purpose, filtering behavior, ordering, unit (Toman), and the next step. Return shape is only hinted at via the mention of a `note`, which is a minor gap but not a blocker 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 schema already documents limit, pages, query, min_price, and max_price including the accessory-dropping default. The description's 'drops accessories' reiterates the schema's min_price note rather than adding new parameter meaning, so the baseline 3 applies.

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

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

The description states a specific verb and resource with scope: 'Find the cheapest in-stock products that really match a query, sorted by price.' It also signals the intended phrasing ('Use for "cheapest X"'), which separates it from generic siblings like dk_search. It stops short of distinguishing itself from the closest sibling, dk_best_for_budget, so it is clear but not fully sibling-differentiated.

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 concrete when-to-use trigger ('cheapest X') and a follow-up step ('then dk_product on the winner, as another seller may sell it for less'). There is no explicit when-not or named alternative for budget-style queries, 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 cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the description only needs to add beyond that. It does disclose precedence behavior when both query and category_code are supplied, and that category_code also returns sub-categories, which is a genuine return-shape clue absent from the schema.

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

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

Two short sentences, front-loaded with purpose and the precedence rule, followed by a compact routing pointer. No wasted words, though the stray line breaks make it slightly less tight than an ideal single block.

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?

Seven optional parameters are all documented at 100% coverage, annotations carry the safety profile, and no output schema exists so return detail is not required. The description covers the one ambiguous interaction (query vs category_code) and hints at sub-categories, leaving little an agent would need 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 seven parameters richly (units, limits, enums, example values). The description's only added meaning is the precedence of category_code over query, which is useful but minimal against a fully documented 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 ("Search or browse") and resource ("Digikala Fresh (supermarket)"), so an agent knows it targets the grocery vertical. It names dk_deals as the alternative for discounts, but never explicitly contrasts with dk_search, which is the obvious sibling an agent might confuse it 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?

Gives explicit routing guidance: discounts go to dk_deals(store='supermarket'), and it states a precedence rule ("category_code beats query"). It lacks a when-not-to-use-this-vs-dk_search note, so the guidance is clear but not 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 declare readOnly, idempotent, open-world, non-destructive behavior. The description adds genuinely useful field semantics beyond that: what gold18_day_change_pct compares against, that period change/low/high span a ~3-month chart, and that a null coin price means 'not for sale.' This is real context the annotations do not carry.

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 purpose sentence followed by a compact field-glossary paragraph; every sentence earns its place. The second block is slightly terse ('period change, low and high') but not wasteful.

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 parameters and no output schema, the description must convey what comes back, and it partially does by defining several return fields. It does not enumerate the full response shape (e.g., the coin list structure), leaving a small gap for a tool whose return values carry the whole contract.

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?

With zero parameters, the baseline is 4. The description instead spends its text on return-field semantics, which is the right allocation for a no-argument tool.

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

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

The first sentence states a specific verb and resource: 'Get the live 18k gold price per gram and gold coin prices, in Toman.' No sibling tool in the list covers market/commodity pricing, so it is trivially distinguished from the product-search 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 gives clear context (live gold/coin prices) but no explicit when-to-use/when-not guidance. Because it takes no parameters and no sibling overlaps this resource, the usage is unambiguous without routing instructions.

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 safety is covered; the description adds genuinely non-obvious behavioral facts on top: an approval requirement, empty-result behavior on unknown ids, and the warning that plans are not sized to the product price so they must not be framed as a per-month product offer.

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

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

Three tight sentences with the purpose front-loaded, then the domain caveat, then the prerequisite and error behavior. Nothing is padded, though the mid-sentence backtick identifiers make it slightly denser than needed.

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

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

For a one-parameter read-only lookup with no output schema, the description supplies the missing return-shape vocabulary, the approval prerequisite, and the invalid-id behavior. The only gap is that it never contrasts with the sibling dk_plus_plans, leaving the agent to guess which plan tool fits which product type.

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 product_id parameter is already well documented in the schema (format, example, range), so the schema carries the load. The description adds only the currency unit (Toman) and output-field vocabulary (credit_amount, months, monthly_repayment), which are return-value semantics rather than parameter semantics.

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

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

States a specific verb (Get) and resource (Digipay credit-line offers for a product) and even names the price unit (Toman). It defines what an installment plan is, but never explicitly distinguishes itself from the nearby sibling dk_plus_plans, which an agent could plausibly confuse it 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?

Gives a real prerequisite ("Needs Digipay approval"), tells the agent what happens with a bad input ("An unknown id gives no plans"), and routes to a validator ("check it with dk_product"). It stops short of an explicit when-to-use-vs-alternative statement (e.g. vs dk_plus_plans), so it is clear context but not full exclusion 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/openWorld/non-destructive, so the safety bar is covered. The description adds genuinely useful behavioral context beyond them: the two mutually exclusive input modes and the domain fact that pricing is location-independent while delivery is not.

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

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

Two sentences, zero filler, with the primary purpose front-loaded and the input modes immediately after. 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?

For a 4-optional-param, no-output-schema lookup tool this is close to complete: it names the inputs, the two modes, and the returned identifiers. The one gap is that with zero required parameters and all defaults null, the failure behavior when neither mode is supplied is not stated.

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 per-parameter docs already carry the load and the baseline is 3. The description goes one step further by specifying the cross-parameter pairing constraint (address+city as a unit, lat+long as a unit), which the schema does not express.

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 bidirectional verb+resource: address→coordinates or coordinates→address, returning Digikala city_id/state_id. That is unambiguous and clearly distinct from every sibling, all of which are catalog/product/price 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?

'Pass address + city, or lat + long' tells the agent exactly which invocation mode to pick, and the note that location only affects delivery (not price) tells it when the result matters. It stops short of stating what happens if both or neither mode is 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?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds genuine domain context the annotations cannot: the plan tiers (jet vs fresh) and that results carry Toman pricing and benefits. It does not describe ordering or count, which is a minor omission for a small static list.

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

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

A single front-loaded sentence with the core action first and the differentiating details in a compact parenthetical. Every clause (tier names, geography, currency, benefits) carries information an agent would otherwise lack; nothing is padding.

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 zero-parameter, non-destructive list tool with no output schema, the description already tells the agent what comes back (plan tiers, Toman prices, benefits). Nothing needed to invoke or interpret the call 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?

The tool takes zero parameters, so the baseline of 4 applies. The description neither invents nor misrepresents parameters, and correctly implies the call returns the full plan set with no filtering input.

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 (List) and resource (Digikala Plus plans), then immediately qualifies what those plans contain (jet same-day Tehran/Karaj shipping, fresh supermarket, price in Toman, benefits). No sibling tool in the list covers subscription plans, so the agent can route here unambiguously.

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 — an agent infers this is for questions about Plus subscription tiers, but there is no explicit 'use when' clause, no prerequisites, and no named alternative (e.g. when to prefer dk_fresh_search or dk_deals instead). Adequate but leaves selection 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 cover the safety profile (readOnly, idempotent, non-destructive), and the description adds real context beyond them: the ~30-day window, daily granularity, Toman currency, per-variant grouping, and the Jalali calendar basis. It also discloses the empty-result edge case for unknown ids, though it does not describe other return fields or data-freshness guarantees.

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 capability in the first sentence, then layers the interpretation hint and the error-handling note. Three short blocks, no filler, 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?

With no output schema, the description must carry return-value meaning, and it does name lowest, highest, and lowest_2_days with their semantics. For a single-parameter read-only tool this is nearly complete; only minor details (exact window variance, additional fields) are left implicit.

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

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

Schema coverage is 100% for the single product_id parameter, so the baseline would be 3, but the description adds behavioral meaning: an unknown id yields no variants and should be validated via dk_product. That extra guidance is genuinely useful parameter-level context.

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

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

States a specific verb (Get), resource (daily buy-box prices), and scope (~30 days, per color/variant, in Toman) plus the two summary fields returned. It also routes the agent to dk_product for id validation, so it is distinguishable from sibling 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 frames the use case ('For "is this a good price?"') and explains why lowest_2_days is the right field versus lowest for that judgment. It also names dk_product as the fallback for an unknown id. It does not, however, compare itself to pricing siblings like dk_find_cheapest or dk_deals.

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), yet the description adds substantial behavioral detail: the offer model (one color/size per seller), that stock_left appears 'only when low', ships_by semantics ('jet' = same-day Tehran/Karaj), and the lowest_price_30d volatility caveat. This is well beyond what the structured fields 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?

The core purpose is front-loaded in sentence one, followed by a compressed field glossary. Dense but essentially waste-free; the caveats about lowest_price_30d and groceries each carry information an agent would otherwise misread.

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

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

With no output schema, the description carries the burden of describing returns and does so: the top-level fields and the full per-offer field set with their meanings and conditional presence. Nothing an agent needs to interpret results 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 product_id, max_offers and include_specs; the baseline is 3. The description reinforces the cheapest-first ordering and the offer concept 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?

Opens with a specific verb+resource ('Get one product's...') and enumerates exactly what comes back: price, stock, rating, specs, and every seller's offer. It is clearly distinguishable from siblings like dk_search (listing) and dk_price_history (history series).

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?

Routes the agent to alternatives with reasons: dk_price_history's lowest_2_days is 'steadier' than a possibly spurious lowest_price_30d dip, and warns that grocery prices may differ from dk_search's. It lacks an explicit 'use this when you have a product_id' trigger or a when-not-to-use statement, 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 the safe-read profile (readOnly, idempotent, non-destructive), and the description adds real behavior beyond that: 20 items per page and texts truncated to 300 characters unless full_text=true. It does not mention rate limits or total counts, but this is solid added 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 compact sentences with the core read/count facts front-loaded and the use case trailing. No filler, though the truncation detail is packed into a parenthetical that is slightly dense.

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

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

For a read-only, single-object listing tool with a fully documented schema and annotations covering safety, this is nearly complete. The absence of an output schema is not an issue since the description conveys the return shape (questions, answers, truncation).

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

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

Schema description coverage is 100%, so baseline is 3. The description restates full_text's effect and page size, which the schema already documents, so it adds little beyond the structured fields.

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

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

States a specific verb and resource: 'Read customers' questions' with the answer cardinality made concrete ('up to 2 answers each'). It is clearly a Q&A reader, distinguishable in spirit from dk_reviews, though it never names that nearest sibling explicitly.

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

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

'Use for practical doubts (compatibility, size, registration)' gives concrete when-to-use context. It does not state when NOT to use it or point to alternatives like dk_reviews, so it stops 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 declare readOnly/idempotent/non-destructive, but the description adds real behavioral detail: truncation limits (300 chars, pros/cons 5 of 80), the full_text override, and that an unknown id returns no reviews rather than an error. That is meaningful context beyond the annotations.

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

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

Front-loaded with the return payload, then constraints, then the id caveat. Three tight sentences with no filler, though the numeric limits make it slightly dense.

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

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

With no output schema, the description carries the return-value burden and does so well (fields, truncation, full_text behavior). Only minor gaps remain, such as pagination semantics, which the schema already covers.

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 value the schema lacks: the concrete cut numbers and the semantic note that stars can be null (no rating). It does not add syntax for page/sort/limit 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 ('Read customer reviews') and enumerates the returned fields (stars, text, pros/cons, verified buyer flag). It also distinguishes itself from the sibling dk_product by explicitly routing the overall rating 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?

Clear context: it directs the agent to dk_product for the overall rating and to verify ids, and explains when to set full_text=true. It stops short of explicitly naming when not to use it, but the routing guidance is solid.

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 safe read-only, idempotent, open-world behavior, so the bar is lower. The description goes well beyond by disclosing 20 results per page, the 'match' field semantics ('all', 'some' with missing_words, 'none'), and the important sort=cheapest caveat.

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 search action and keeps the rest dense with match, filter, sort, and next-step information. It is appropriately sized with no filler, though some fragments are compressed enough to require 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?

For a complex 12-parameter search tool with no output schema, the description covers key behavioral details: pagination, result match quality, and the next tool to call. It does not describe all return fields or pagination limits beyond page size, but schema and annotations cover the remaining structured concerns.

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 12 parameters are already documented, making 3 the baseline. The description adds only marginal parameter context, mainly that filter ids come from dk_filters(query=...) and restating price/seller/rating fields.

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

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

States a specific verb and resource: 'Search products by name', with scope details (price, discount, seller, rating, 20 per page). It also distinguishes itself from siblings by naming dk_find_cheapest for cheapest real matches and dk_product for seller offers.

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 clear usage context: filter ids come from dk_filters(query=...), sort=cheapest has a caveat directing to dk_find_cheapest, and 'Next: dk_product' tells the follow-up call. It lacks explicit when-not-to-use guidance against other search-like siblings such as dk_fresh_search or dk_category_products.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint, so the safety profile is covered. The description adds genuinely useful metric semantics ('Percentages are the share of good orders, 100 = never late') that annotations cannot express, but says nothing about pagination behavior or how many products come back.

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

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

Three tight sentences with zero filler. The purpose and the usage trigger are both front-loaded, and the clarifying note on percentage semantics is placed last where it does not obstruct scanning.

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 does name what is returned (rating, on-time shipping, cancellations, returns, products) and how to interpret the numbers, which is adequate for a read-only lookup. It leaves the 20-products-per-page result shape to the schema, but nothing critical for invoking the tool is missing.

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

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

Schema description coverage is 100%, and every parameter (page, sort, seller_code, in_stock_only) is documented with type, default, enum or pattern in the schema itself. The description only glosses the reputation fields, adding no parameter-level detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource: fetching a seller's reputation metrics plus their products. It is distinguishable from siblings like dk_best_sellers (listing) and dk_brand_products (brand-scoped), though it never explicitly names those distinctions.

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 before recommending an unknown seller' gives a clear trigger condition for when to reach for this tool. It stops short of stating when not to use it or pointing at an alternative for known/trusted sellers.

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 and explains non-obvious value semantics: cheapest_offer can sit below price (featured offer), low_30d requires two consecutive days at the low, vs_30d_low_pct is 0 at the low, and lowest_one_day_30d is Digikala's figure that may be a one-day dip. With no output schema, this disambiguation is genuinely load-bearing.

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 capability and its field set are front-loaded in the first sentence, followed by usage, then field semantics. Every remaining sentence defines a term or points at an alternative; nothing is padding.

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

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

With no output schema and only one input parameter, the description carries the return-value burden and does exactly that by defining the five fields and their units. An agent knows what it will get back and when to prefer a sibling.

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's description already documents the 1-10 id constraint. The description's 'up to 10 products' merely restates maxItems, adding no new syntax or format meaning, so the baseline 3 applies.

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

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

States a specific verb and resource ('re-price up to 10 products in one call') and enumerates the returned fields (price, cheapest offer, stock, rating, 30-day low) with currency. It explicitly names the siblings it is not (dk_compare for specs, dk_price_history for the daily curve), so an agent can differentiate 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?

'Use to refresh a watched list or check stock' gives the triggering scenario, and the closing sentence routes to two concrete alternatives with their selection criteria ('For specs use dk_compare; for the daily curve dk_price_history'). When-to-use and when-not-to-use are both covered.

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 this as a safe, idempotent, read-only, open-world lookup, so the safety profile is covered. The description adds useful behavioral context — the notion of similarity and that one sort mode yields cheaper alternatives — but says nothing about return shape, result size, 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, front-loaded with the purpose before the parameter hint and next-step pointer. The trailing fragment "then dk_compare." is terse almost to the point of ambiguity, but no sentence is wasted.

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 listing tool whose 4 parameters are fully documented in the schema, the description covers purpose, similarity scope, a key sort semantic, and the natural follow-up call. The main remaining gap is that, with no output schema, it never characterizes what a result entry contains.

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 genuine meaning the schema lacks: the schema only says 'Order of the results' for sort, while the description explains that sort='cheapest' resolves to cheaper alternatives relative to the source product. This only covers one of eight enum values, so it is above baseline but not exhaustive.

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+resource ("List products similar to one") and immediately defines what 'similar' means — same kind, other models and brands — which disambiguates it from generic listing siblings like dk_search or dk_category_products. It stops short of explicitly naming a sibling it should not be used in place of.

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 concrete usage direction: use sort='cheapest' to surface cheaper alternatives, and it names the follow-up tool (dk_compare) as a chained next step. There is no 'when not to use this' guidance or comparison against the other discovery tools, so it is clear context rather than full 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 and destructiveHint=false, so the safety profile is covered. The description adds value beyond that by disclosing the return shape (keywords, categories, brands) in a tool with no output schema, though it says nothing about result limits or ranking.

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 compact lines: the capability first, the follow-on routing second. No filler, and everything is 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?

For a one-parameter, read-only lookup with no output schema, the description covers the input expectation, the returned entity types and the next step, which is everything an agent needs to call it and chain 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% and the single parameter already has an example, so the baseline is 3. The description adds semantic meaning by indicating the query is expected to be partial/vague or misspelled, which frames how to populate 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 ('Autocomplete a vague or misspelled query') plus the nature of the output (keywords, categories, brands). It also names the sibling tools it feeds into, so an agent can place it precisely in the workflow.

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 condition for use is explicit ('vague or misspelled query'), and the two downstream alternatives (dk_search, dk_category_products) are named with the input each expects. It stops short of stating when NOT to call this (e.g. skip it if you already have a clean keyword), so it is clear context rather than full routing logic.

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