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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so safety is covered. The description adds the content-type/link nature of results, but says nothing about result ordering, pagination behavior, or relevance 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; the resource and corpus are front-loaded, followed by the usage trigger and the handoff to kh_search. No redundant or filler text.

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, annotations covering the safety profile, and full parameter documentation, the description supplies everything else an agent needs: what the corpus is and when to prefer it over product search.

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%: query language preference (Persian) and the page/20-posts-per-page semantics are already documented in the schema. The description adds no parameter-level detail beyond that, so baseline 3 applies.

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

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

States a specific verb+resource ('Search the Khanoumi magazine') and enumerates the content corpus (buying guides, routines, ingredient explainers, how-tos). It is clearly distinguishable from kh_search by framing results as articles rather than products.

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

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

Gives an explicit when-to-use trigger ('user asks which product type suits them or how to use something') and names the follow-up alternative ('then find products with kh_search'), routing the agent along a concrete workflow.

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 profile is covered. The description adds genuinely new context beyond them: the corpus size (~3,200 brands), the nature of the returned value (slugs), and the examples of valid inputs.

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, zero filler, with the purpose and scale front-loaded and the usage/routing instruction second. 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-value explanation is unnecessary, and the description covers purpose, scale, and downstream use. It stops short of noting pagination behavior, but the schema already carries defaults and bounds.

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 page/limit/query are already fully documented in the schema (including Persian/English examples and 'empty = all, A-Z'). The description adds no parameter detail beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb+resource ('Find brands by name') and the key return artifact ('with their slugs'), plus dataset scale (~3,200 brands). It also routes the agent to the siblings that consume the output, so it is distinguishable from kh_search/kh_categories 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?

Explicitly says when to use it: to obtain the brand slug for kh_browse / kh_filters `brands`, with concrete examples ('simple', 'cerave'). No explicit when-not or exclusion clause, so it is clear context rather than full routing rules.

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), so the description earns credit for adding real behavioral limits: no rating or discount sort exists, and results should be verified via kh_product / kh_reviews. It stops short of describing pagination or result-cap behavior, which a browse tool would benefit from.

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 followed by example queries, then constraints and pointers to sibling tools. Dense but every sentence carries information; the quoted example phrasings are slightly verbose but useful for query matching.

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, and it instead covers the things an agent can't infer: the at-least-one-selector rule, filter provenance, sorting limits, and where to go for verification. Nothing essential is missing for a 12-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 coverage is 100%, so the baseline is 3, but the description adds a genuine constraint not expressed in the schema: at least one of category_id, brands or tag must be supplied even though none are marked required. It also clarifies where each filter id must be sourced (kh_filters, kh_deals, kh_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?

Opens with a specific verb+resource+scope: 'List the products of a category, brand(s) or campaign tag with sorting, price range and filters.' The concrete example queries ('cheapest CeraVe moisturizer', 'sunscreens for oily skin under 800,000 Toman') make the tool's domain unmistakable against siblings like kh_search or kh_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?

Explicitly states the invocation constraint ('Pass at least one of category_id, brands or tag'), names the upstream lookup tools (kh_categories, kh_brands, kh_deals, kh_filters), and rules out alternatives by noting there is no rating or discount sort and directing candidates to kh_product / kh_reviews.

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 bar is lower. The description adds real operational context beyond that: without a query only levels up to max_level are returned, while with a query every level is searched, which materially affects 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?

Three tight sentences with no filler; the primary purpose and the routing cue come first, followed by the query/no-query distinction and the alternative tool.

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 and annotations carry the safety profile, so the description need not explain return shapes. What remains — purpose, routing to sibling tools, and query-mode behavior — is fully 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 description coverage is 100%, so the baseline is 3. The description goes further by explaining how the two parameters interact (level truncation only applies in the no-query case; a query searches all levels), which is not stated in the schema itself.

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 (Khanoumi's category tree) and enumerates what it returns: ids, URL paths, product counts. This is clearly distinguishable from siblings like kh_search or kh_browse, which the description positions it against.

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 states the reason to call it (to obtain a category_id for kh_browse / kh_filters / kh_find_cheapest) and names kh_search as the alternative that also surfaces matching categories. It also clarifies the query vs no-query behavior, so an agent knows which mode fits its situation.

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/openWorld, so the safety profile is covered. The description adds meaningful behavior beyond that: sort order, that pink_box_ends_in_seconds is a countdown, that each section's tag feeds kh_browse, and that the voucher is redeemed at checkout with its terms in voucher.text.

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 usage, then output-field hints; every sentence carries information. It is dense and slightly scattershot in mixing output semantics with usage guidance, but there is 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?

An output schema exists so return shape need not be explained, yet the description still clarifies the non-obvious output fields (pink_box_ends_in_seconds, section tag, voucher.text). Combined with annotations and 100% param coverage, an agent has everything needed to call and interpret it.

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

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

Schema description coverage is 100% with a single documented 'limit' parameter (default 30, max 100). The description adds no further semantics about limit, so the baseline 3 applies when the schema carries the whole burden.

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 featured deals from the Khanoumi home page'), covers both the daily pink box and the pop-up campaign voucher, and is clearly distinct from siblings like kh_search or kh_browse. The ordering guarantee ('biggest discount first') further narrows what this tool is.

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 use trigger ('Use for "what's on sale" / "best discounts today"') and routes product-level drill-down to the sibling kh_browse(tag=...). It does not state when to prefer kh_search or kh_find_cheapest over this tool, so the exclusion side is 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 cover the safety profile (readOnly, idempotent, openWorld, non-destructive), and the description goes well beyond them by disclosing truncation behavior (brands cut to the 40 biggest, attribute groups to 25 values, with an `omitted` count) and non-obvious data semantics (prices in Toman, price_range based on list price before discount, min 0 meaning out-of-stock). These are exactly the quirks an agent would otherwise misread.

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, then progressively adds chaining guidance and gotchas in three tight paragraphs. The first sentence is dense with a long parenthetical enumerating facet types, which is slightly heavier than needed, but no sentence is 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?

An output schema exists, so return values need not be spelled out, yet the description still explains the two most confusing output aspects (truncation with `omitted`, and the list-price basis of price_range). Combined with the annotations, an agent has everything needed to call it 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% and each parameter already carries a description with provenance (tag from kh_deals, brands from kh_brands/kh_filters, category_id from kh_categories), so the schema does the heavy lifting. The description's 'pass brand slugs as brands' restates the same mapping, adding little parameter-level meaning beyond the 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 specific verb and resource ('List the filters of a category, brand, tag or search') and enumerates exactly what comes back: sub-categories, brands, colors, attribute facets, ids, product counts, price range and stock counts. It is clearly distinguishable from siblings like kh_search and kh_browse 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?

Explicitly frames the tool as a precursor: 'Use before kh_browse' and tells the agent how to feed the result forward ('pass brand slugs as brands, color ids as colors, facet keys as facets'). This is a concrete when-and-how-to-use directive rather than an implied one.

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 the safety profile is covered. The description adds genuine operational behavior not in the annotations: sponsored items are dropped, loose title matches are excluded by default, results are sorted by payable price, and complete=false signals that matches continue past `scanned` and scan should be raised.

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

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

Front-loads the core purpose in the first sentence and then layers usage, filtering, and pagination notes compactly. The terse fragments ('complete=false: matches go on past `scanned`, raise scan') are dense but slightly clipped, costing a little polish rather than content.

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 needn't be explained, and the description covers the non-obvious behavioral quirks (sponsored-filtering, match_all_words default, scan/complete pagination loop). Cross-references to kh_product and kh_categories round out what an agent needs to act.

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

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

Schema coverage is 100%, so baseline would be 3, but the description earns extra credit by clarifying scan semantics (matches continue past the scanned set on complete=false), the default match_all_words filtering behavior, and that final_price is the cheapest shade to verify with kh_product.

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 (find), resource (cheapest in-stock products), and scope (one flat list sorted by payable price in Toman). It implicitly separates itself from the broader kh_search by emphasizing 'cheapest' and dropping sponsored items, so an agent can route correctly 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?

'Use when the user wants the lowest price for X' gives a clear triggering intent, and it points to kh_categories/kh_search for narrowing via category_id. It does not state when NOT to use this tool or explicitly contrast alternatives like kh_search for general browsing, 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 readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds depth about the record's granularity (per-shade/size/seller variant pricing and max quantity), but says nothing about authentication needs, rate limits, or behavior on a missing/ambiguous slug. Adequate but not rich beyond annotations.

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

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

Front-loaded with the payload contents, then usage, then sibling routing — a sensible order. The field enumeration is long, and since an output schema exists it partly restates the return shape, but every listed field is genuinely useful for deciding whether to call this tool.

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 annotations covering safety, a 100%-documented single parameter, and an output schema handling return values, the description only needs to establish purpose and routing — which it does. The remaining gap is minor: no guidance on failure modes (invalid slug, product not found).

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 parameter is fully documented there (slug pattern plus numeric id example, including the sibling tools it comes from). The tool description adds no syntax or format detail beyond that, so baseline 3 applies.

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

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

Specific verb ('Get one product's full record') plus an enumerated content list: price/discount in Toman, per-variant price/stock/max quantity, rating, brand, category path, attributes, description. This is clearly distinguishable from kh_search (list-level) and kh_reviews (review-level) 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?

Explicit trigger ('Use after kh_search / kh_browse when the user picks a product, or to check that the shade they want is in stock and what it costs') plus direct routing for adjacent needs: kh_reviews for reviews, kh_similar for alternatives, kh_store_info for order-total fees. Nothing is left to inference.

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

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

Annotations already declare readOnly/openWorld/idempotent, so the safety profile is covered. The description adds genuine behavioral context beyond them: default ordering (newest first) and the absence of star ratings, which saves the agent a wasted call expecting rating 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 sentences, zero waste: the core behavior first, the routing/usage note second. Nothing is repeated from the schema or annotations.

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

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

With an output schema present, return-value detail is not needed, and the description covers the key surprises (no ratings, photo filtering, ordering). Pagination behavior and the upper page bound are left to the schema, which is acceptable here.

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 page, limit, product format, and with_photos. The description adds the 'newest first' ordering note, but that is already implied by the page parameter description, so it is baseline territory.

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 comments on a product') plus distinguishing attributes: newest-first ordering, verified-buyer flag, photos. It also carves out what it is not (ratings live in kh_product), though it doesn't differentiate itself from the remaining ten 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 an explicit situational trigger ('Use as a quality check before recommending a product') and routes the agent to kh_product for ratings and rating counts, which is a real alternative-selection cue. It stops short of stating when-not-to-use it, but the context is clear.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds real behavioral context beyond that: sponsored items are removed from results, and matches also yield category ids and brand slugs. It stops short of describing pagination cost or rate limits, but the added filtering/result behavior is meaningful.

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 the returned fields, followed by a compact routing block of sibling alternatives. Dense but every clause carries routing or result information; only the parenthetical's coupling of categories to kh_browse is mildly tucked away.

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 need not explain return values, yet it still signals what matches include. Combined with 100% parameter coverage and explicit sibling routing, the definition is essentially complete; only pagination/volume expectations are left implicit.

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

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

Schema description coverage is 100%, so page, sort, limit, query, min/max_price and in_stock_only are all documented in the schema (including units in Toman and enum meanings). The description adds no syntax or format detail beyond that, so the baseline 3 is correct.

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 ('Search Khanoumi products by keyword') and enumerates what each match returns: price, discount, stock, with sponsored items removed. It also names the sibling tools it is not (kh_find_cheapest, kh_filters, kh_product), so an agent can distinguish it 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?

It explicitly routes the agent: 'Use first for "price of X" / "do you have X"', then maps alternatives to their conditions ('For the cheapest in-stock match use kh_find_cheapest', 'to filter by skin type, color or brand use kh_filters + kh_browse', 'shades, sellers and per-shade prices: kh_product'). Both the primary case and the exclusions are spelled 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 safe, idempotent, non-destructive read, so the bar is lower; the description still adds real behavioral value by disclosing the ~20-item result size and the important caveat that complementary lists are empty for most products. It does not mention pagination or ordering, which keeps it from a 5.

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

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

Three short sentences, front-loaded with the core action and modes followed by usage triggers. No redundant or filler text; every sentence maps to a distinct decision the agent needs to make.

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-value explanation is not needed, and the description still summarizes the payload (prices and stock). Usage conditions, both modes, and the empty-complementary edge case are all covered for a 3-parameter, 1-required 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%, including a documented enum for kind and the slug/id pattern for product, so the schema already carries parameter meaning. The description restates the kind semantics, adding no syntax or format detail beyond it; 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?

Specific verb and resource ('List alternatives to a product... or the products the shop pairs with it') with scope (~20 items) and payload (prices and stock) stated up front. The two modes are clearly distinguished, which separates it from generic siblings like kh_search and kh_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?

Explicit when-to-use triggers are given: out-of-stock, too expensive, or building a routine/bundle. It stops short of naming an alternative sibling (e.g. kh_find_cheapest) for the price-shopping case, so routing is strong but not fully closed.

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 that answers come from the official FAQ and that delivery answers carry the courier/fee breakdown and FreeShipping badge logic, which is useful content context, but it does not mention e.g. result length limits or staleness beyond what the schema already notes.

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 resource and reserves the second paragraph for the when-to-use cases and the cost formula, which earns its place. Slightly weakened by the hard line-break mid-sentence and dense formula, but overall tight and purposeful.

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 the description covers scope, trigger questions and the cost-computation usage. It is essentially complete for a two-parameter FAQ lookup; only minor behavioral detail (result size/staleness) is absent.

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 both the free-text query and the topic enum with its default. The description adds only marginal meaning (that delivery answers distinguish Tehran/Alborz courier from provincial post and can be zero with a FreeShipping badge), which is baseline-adequate but not compensating for any gap.

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 resource (Khanoumi's order rules: shipping, returns, payment, refunds, guarantee, pink-box) drawn from the official FAQ. An agent can immediately distinguish this from product/search siblings like kh_product or kh_search, which return item data rather than policy answers.

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 enumerates triggering questions ("how much is shipping", "can I return it", "how do I pay") and a concrete use case (computing true order cost from delivery answers). It stops short of naming when NOT to use it or routing to a specific sibling, 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.