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 one useful behavioral detail — results include links — but says nothing about pagination limits (the 20-per-page, 50-page cap), ranking, or result volume, so it adds only modest value beyond the structured fields.

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, zero filler: the first defines scope and content, the second gives the usage trigger and the hand-off tool. The most decision-relevant information (what it searches) 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 two-parameter read-only search with no output schema, the description covers scope, trigger, and follow-up routing, and the 'with links' hint partially compensates for the missing return-value documentation. Pagination behavior is left to the schema, which is acceptable but leaves a small 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 description coverage is 100%: the query parameter already documents the Persian-input preference with examples, and page documents the 20-posts-per-page sizing. The description adds no parameter-level guidance 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?

States a specific verb (search) and resource (the Khanoumi magazine / مجله خانومی), and enumerates the content types returned (buying guides, care routines, ingredient explainers). This clearly separates it from the product-oriented siblings like kh_search and kh_product, though the differentiation is only fully spelled out in the second sentence.

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 ('when the user asks what suits them or how to use something') and names the follow-up tool ('then find products with kh_search'), which routes the agent well. It stops short of stating when not to use this tool, so it falls just 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 readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so safety/idempotency are covered. The description adds the corpus size and that slugs are returned, but says nothing about pagination behavior or result ordering beyond what annotations and schema imply.

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 opening with the verb; the parenthetical count and the downstream-tool note are both informative and earn their place. 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?

For a non-destructive paginated lookup with full schema coverage and comprehensive annotations, the description covers what is returned (brands + slugs) and the dataset scale. It could be slightly more complete by noting the paginated list shape, since there is no output schema.

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

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

Schema description coverage is 100%, so page/limit/query are fully documented in the schema (including Persian/English examples and empty = all, A-Z). The description's 'by name' adds no syntax or format detail beyond that, 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+resource ('Find brands') with useful qualifiers: the dataset size (~3,200), the return payload (slugs), and the downstream consumers (kh_browse / kh_filters). It does not explicitly contrast itself with lookups like kh_categories or kh_search, so sibling differentiation is implied rather than stated.

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

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

It gives a clear context of use by naming the tools whose `brands` filter this feeds (kh_browse, kh_filters), which tells an agent why to call it. It stops short of explicit when-not rules or naming an alternative lookup tool for the same need.

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: the requirement to supply at least one of three anchor parameters, the absence of rating/discount sort modes, and where filter ids must be sourced from. It does not discuss pagination limits or result volume, so a 4 rather than 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, all front-loaded: purpose first, then the use case and precondition, then the follow-up routing. No filler, no restatement of the title, and the 'Next:' clause is compact.

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

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

For a 12-parameter, zero-required faceted browse tool with no output schema, the description covers the essential invocation rule, id provenance, and workflow hand-offs. It omits any hint about result shape or how deep pagination goes, but with annotations carrying the safety profile and the schema carrying field semantics, the remaining gap is minor.

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

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

Schema description coverage is 100%, so the baseline is 3 and the schema already documents each field. The description nevertheless adds a cross-parameter rule the schema cannot express ('Pass at least one of category_id, brands or tag') plus provenance for each id type (kh_categories, kh_brands, kh_deals, kh_filters), which is genuinely additive.

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

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

The description opens with a specific verb and resource ('List products of a category, brand(s) or campaign tag') and enumerates the dimensions it supports (sorting, price range, filters). An agent can tell this is a faceted listing tool rather than a keyword search. It does not explicitly name the closest sibling (kh_search) as the contrasting option, 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 gives a concrete when-to-use example ('sunscreens for oily skin under 800,000 Toman'), a hard invocation precondition ('Pass at least one of category_id, brands or tag'), and a scope limitation ('No rating or discount sort'). It also points at the follow-up tools kh_product / kh_reviews. It never states when to prefer kh_search instead, which keeps it out of 5 territory.

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 still adds real behavior: a query searches every level, while an unqueried call only returns levels up to max_level.

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

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

Two tight sentences, zero filler. The return contents are front-loaded and the usage guidance plus parameter behavior follow in a logical order.

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 correctly compensates by naming what is returned (ids, URL paths, product counts). Combined with the 100%-documented params and the annotation safety profile, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds the conditional interaction between the two parameters that the schema documents only in isolation. The distinction between query mode and max_level mode is the key semantic an agent needs.

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 Khanoumi's category tree') plus the payload it returns (ids, URL paths, product counts). It also distinguishes itself from siblings by naming the tools that consume its category_id output.

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: use this to obtain a category_id for kh_browse, kh_filters, and kh_find_cheapest. It does not state when NOT to use it (e.g., fall back to kh_search for free-text lookup), 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 readOnly/openWorld/idempotent/non-destructive, so safety is covered. The description adds real behavioral context beyond that: results are ordered 'biggest discount first', sections may have a `tag` (full product list) or only a `link`, and voucher conditions live in voucher.text. It does not discuss auth or rate limits, but the ordering and field-structure disclosure are substantive.

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 dense but useful field notes in a compact second sentence. No filler sentences; every clause (pink_box_ends_in_seconds, tag vs link, voucher.text) carries information.

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

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

With no output schema, the description must explain return shape, and it does so by naming the key response fields (pink_box_ends_in_seconds, tag/link, voucher.text) and their meaning. It is close to complete, though it doesn't describe the overall response envelope or campaign-code placement explicitly.

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

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

There is a single optional `limit` parameter with 100% schema description coverage, so the schema fully documents it. The description adds nothing about the limit or pagination, which is the correct baseline 3 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?

The description names a specific verb and resource ('List today's home-page deals … plus the public discount code of the current pop-up campaign'), and states scope (today's home-page rows, biggest discount first). An agent can distinguish this from kh_search or kh_find_cheapest 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?

It gives an explicit usage cue ('Use for "what's on sale"') and cross-links to the sibling kh_browse for section tag expansion. It stops short of stating when to prefer kh_find_cheapest or kh_search over this tool, so there is no explicit exclusion.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so safety is covered. The description goes beyond them by disclosing truncation behavior (brands cut to 40, groups to 25 values, `omitted` counts the remainder) and the semantics of the returned price_range (list price pre-discount, min 0 meaning out-of-stock). It stops short of describing response shape or caching, which is why this is a 4 rather than 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?

Two dense paragraphs with the payload summary front-loaded and the usage/limits second. Every clause carries information, though the second paragraph packs truncation limits, price semantics and the group escape hatch into one long breath, which costs a little readability.

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 it does list the returned facets, counts, price range and stock counts plus truncation rules. What is left unstated is the behavior with zero arguments (all five params are optional) and whether the tool errors or returns unfiltered results, a gap for a no-required-param 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 real meaning: it maps output values onto specific parameters (slugs to brands, ids to colors, facet keys to facets) and explains that `group` lists a single attribute group in full. The `omitted`/truncation note also clarifies why group filtering exists.

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 ('List the filters') and enumerates the exact resource contents: sub-categories, brands, colors, attribute facets with ids and counts, plus price range and stock counts. It also disambiguates itself from kh_browse by positioning itself as the pre-browse step, so an agent can identify it without opening the schema.

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

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

'Use before kh_browse' gives explicit sequencing, and the follow-up sentence tells the agent exactly how to funnel the output forward: brand slugs as brands, color ids as colors, facet keys as facets. The `group` workaround for truncated groups is stated as a concrete condition, not 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 cover the read-only/idempotent safety profile, but the description adds real behavior: it drops loose title matches via match_all_words and explains that complete=false means matches continue past `scanned`, so the agent should raise scan. That scan/completeness mechanism is genuinely useful and not derivable from 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?

Dense and front-loaded: purpose first, then trigger, filtering, narrowing and next-step in four terse clauses. The telegraphic style ('complete=false: matches go on past scanned, raise scan') is efficient but borders on cryptic for an uninitiated agent.

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 `complete` return flag and the scan-raise remedy, and all five parameters are documented in the schema. It remains silent on the exact shape of returned offers and how limit interacts with truncation, which would round it out.

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

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

Schema coverage is 100%, so the schema documents each parameter. The description still adds value by tying match_all_words to its filtering effect and linking the `scan`/`complete` interplay, though it omits detail on limit and truncation semantics 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+resource ('find the cheapest in-stock products for a keyword') plus the sort criterion (payable price in Toman). It is clearly scoped but never names kh_search/kh_deals as the non-cheapest-dedicated alternatives, so sibling differentiation is left to inference.

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

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

'Use for the lowest price of X' gives a concrete trigger, and it notes narrowing via category_id and the natural follow-up ('Next: kh_product'). There is no explicit when-not-to-use or named alternative tool, which keeps it 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 readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds value beyond that by disclosing the shape and richness of the payload (per-variant pricing, stock, max quantity, currency in Toman), which tells the agent this is a heavyweight detail fetch rather than a summary. It stops short of noting response size or rate limits, so not 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?

Two sentences, no filler. The record contents are front-loaded and the second sentence is a compact routing cue (predecessor tools, then next tools). Every clause carries information.

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

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

With no output schema, the description takes on the burden of explaining return values and does so comprehensively, plus it supplies the workflow context. For a two-parameter read tool, nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so both parameters ('product' with its slug/numeric-id format and 'full_text' clipboard behavior) are already fully documented in the schema. The description adds no additional parameter semantics, making the baseline 3 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?

States a specific verb and resource ('Get one product's full record') and enumerates the returned record (price/discount in Toman, per-variant price/stock/max quantity, rating, brand, categories, attributes, description). The 'one product' framing cleanly distinguishes it from list-oriented siblings like kh_search and kh_browse.

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 places the tool in a workflow: 'Use after kh_search / kh_browse, or to check that a shade is in stock and its price', and names the natural continuations (kh_reviews, kh_similar, kh_store_info with a parenthetical on fees). Both the entry condition and the next step are 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 establish the safe read-only, idempotent profile, so the bar is lower. The description still adds real value beyond them: text is truncated to 400 characters unless full_text=true, truncated text ends with '…', and per-comment star ratings are deliberately absent (average lives in kh_product). These are non-obvious data-shape facts an agent needs, though it stops short of describing pagination behavior or the full review field set.

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

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

Two tight paragraphs, zero filler. The core purpose is front-loaded in the first sentence, and the operational caveats (truncation, missing ratings, when to use it) follow in a compact second block. 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 dutifully describes the return shape (comments, newest-first ordering, verified-buyer flag, photos) and flags the data limitation around star ratings. Combined with 100% schema coverage for parameters and read-only annotations, an agent has enough to call it correctly, though the per-review field list is not fully enumerated.

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 five parameters are already documented in the schema. The description reinforces ordering ('newest first') and the full_text truncation semantics but adds no new syntax or format guidance. Baseline 3 is appropriate when the schema carries the parameter 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: 'Read customer comments on a product, newest first, with a verified-buyer flag and photos.' This clearly identifies the tool as the reviews fetcher and is hard to confuse with kh_search or kh_browse. It does not explicitly position itself against an alternative reviews tool, but the resource is unique enough that differentiation is implicit.

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 as a quality check before recommending' gives a concrete usage scenario rather than leaving it implied. It also points to kh_product for average star ratings, steering the agent to the right source for that data. There are no explicit when-not conditions or named alternatives for the review-fetching itself, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds non-obvious behavioral value: the response includes best-matching categories and brands beyond the product list, which tells the agent to expect auxiliary result sets. It does not discuss pagination or result-count behavior, but the schema covers paging.

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

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

Two tight paragraphs: the first states purpose and return shape, the second is a compact routing line. Nothing is redundant and the primary use case 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?

With 7 parameters, no output schema and rich annotations, the description covers purpose, return fields and sibling routing adequately. It could say slightly more about how many categories/brands come back or how paging interacts with the auxiliary results, but nothing critical for invocation 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%, including units (Toman), enum meanings and defaults, so the schema carries the parameter burden. The description adds nothing about individual parameters beyond restating that price/discount/stock are returned, 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 (search products by keyword) and immediately enumerates what each match carries (price, discount, stock) plus the secondary payload (category ids, brand slugs). An agent can distinguish this from kh_product, kh_browse and kh_find_cheapest without opening any schema.

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

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

The description gives an explicit entry-point rule ('Use first for "price of X"') and names the follow-up alternatives (kh_find_cheapest, kh_filters + kh_browse, kh_product) in an implied order. It stops short of stating when each alternative is preferred over this one, so the routing is directional but not fully specified.

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 needs no restating. The description adds return context ('with prices and stock') and an item count, but does not disclose pagination, whether results are ranked, or that complementary lists are frequently empty (that fact is left to the schema). Modest added value against an already-covered annotation set.

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

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

Two tight sentences, front-loaded with what is returned and followed by the routing condition. No filler or repetition of the title; every clause carries information.

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

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

With no output schema, the description supplies the essential return shape (products with prices and stock, roughly 20 items) and the selection rationale. It covers enough to call correctly, though it omits pagination/ordering behavior and the near-empty nature of complementary results.

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%: kind, product slug format, and in_stock_only are all documented in the schema with examples. The description adds no parameter 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?

States a specific verb ('List') and resource ('alternatives to a product... or the products the shop pairs with it'), explicitly disambiguating the two modes the `kind` enum offers, plus a concrete count ('about 20'). It stops short of naming sibling tools like kh_product, so an agent gets the resource but no direct routing cue.

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

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

Gives explicit when-to-use triggers ('when a product is out of stock or too expensive, or to build a routine'), which is strong context. It does not state when-not to use it or point to a competing sibling such as kh_product or kh_find_cheapest, so it lacks the exclusions a 5 would need.

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 a safe read-only, idempotent profile, and the description adds genuinely useful behavior the schema cannot express: answers are truncated to 300 characters (ending in …) when topic=all with no query, with the three ways to obtain full text. It does not describe answer structure or result count beyond the clipping rule, so it falls short of the richest disclosures.

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

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

Two tight paragraphs, with the operational trap (300-character clipping) surfaced in the second sentence rather than buried. Some topic names are repeated verbatim from the enum (returns, payment, etc.), which is mild redundancy, but nothing is padded or off-topic.

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 no-required-parameter FAQ reader with no output schema, the definition covers the resource, the trigger cases, the parameter interaction, and the truncation caveat, plus a pointer to the server instructions for the cost formula. The only real gap is a brief note on what an answer record contains, which is minor given the read-only scope.

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 cross-parameter semantics the schema does not: the topic=all corpus is ~80 answers and is clipped unless full_text=true, and the clip only applies in that combination. It also frames query as 'questions or answers containing this', clarifying match scope beyond the schema's maxLength note.

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

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

States a specific verb and resource ('Get Khanoumi's order rules from the official FAQ') and enumerates the covered domains (packaging cost, shipping fees/times, returns, payment, refunds, authenticity, pink-box rules), which matches the topic enum closely. It is clear what is retrieved, but it never names or contrasts a sibling (e.g. kh_blog_search or kh_product), so an agent must infer the boundary from domain knowledge alone.

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

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

Gives concrete trigger phrasings ('how much is shipping', 'can I return it'), points to the delivery answers as the source of the fee values needed for the order-cost formula, and explains how to avoid clipped results. There is no explicit when-not-to-use statement or named alternative tool, so the routing guidance is strong but not exhaustive.

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