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

Annotations already cover read-only, idempotent, non-destructive, open-world semantics, so the bar is lower. The description still adds genuine, non-obvious behavioral context: counts include out-of-stock products, and brands exist only for products tagged with the shop's brand attribute. Ordering and return fields are also disclosed. Pagination/limits are left to 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?

Three sentences, front-loaded with what the tool returns, then the routing use, then the data caveats. No filler; every sentence carries a distinct piece of information.

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

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

For a simple read-only list tool with full schema coverage and rich annotations, this is complete: purpose, scale, ordering, return fields, intended consumer, and the caveat about which brands exist are all present. No output schema exists, and the description already covers the shape of the response.

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` and `query` (including a Persian example). The description adds nothing about parameter syntax, so the baseline 3 applies. The example brand names loosely illustrate `query` matching but do not extend the schema's meaning.

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 brands"), plus scale (~150), example values, and the exact return fields (slug, product count) with ordering (biggest first). It also distinguishes itself by naming the consuming sibling bn_browse, so an agent can place 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?

Explicitly routes the agent: "Use to get the slug for bn_browse's `brand`." That is a concrete use case tied to a named sibling. It lacks explicit when-not guidance, but the brand-attribute caveat effectively tells the agent when results will be empty.

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 structurally. The description adds the precondition that at least one of category/brand/price bound must be supplied, but says nothing about result format, pagination limits, or empty-result behavior beyond what the input schema already documents (e.g. in_stock_only's stale-price 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?

Two sentences plus a compact example, front-loaded on the purpose with the constraint and usage context trailing. Nothing is padded, though the example largely restates what the first sentence already conveys.

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 an eight-parameter, annotation-rich, read-only browse tool with no output schema, the description covers purpose, entry-point workflow and the one non-obvious precondition. It omits anything about the shape of returned product data, but with rich schema documentation and the query-building rule stated, an 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?

With 100% schema description coverage the baseline is 3, but the description adds a genuine cross-parameter rule absent from the schema: at least one of category, brand, min_price or max_price must be given (no parameter is marked required). The inline example also shows how category, brand and sort compose, which the schema's per-field descriptions do not.

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

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

States a specific verb and resource with scope modifiers: 'List products of a category and/or brand, optionally in a price range, sorted by price or rating.' That is clear enough to act on, but it never differentiates itself from bn_search or bn_find_cheapest, so the agent must infer that this is slug/pivot browsing rather than free-text search or the dedicated cheapest lookup.

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

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

Gives a concrete workflow position ('Use after bn_categories / bn_brands to see what a section holds') plus an operational rule ('Give at least one of category, brand or a price bound') and a worked example. It stops short of saying when NOT to use it, e.g. that free-text queries belong to bn_search or that bn_find_cheapest already covers the single-cheapest case.

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

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

Annotations already declare this as a read-only, idempotent, non-destructive operation, so the safety profile is covered. The description adds real behavioral context beyond that: counts include out-of-stock products, and 'tv' hides hundreds of SEO subcategories that duplicate the same products, which prevents the agent from misreading inflated category counts.

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 paragraphs, each front-loaded and carrying a distinct point: return shape, argument behavior, and the SEO-subcategory caveat. The 'tv' example duck-types slightly into prose, but it earns its place by preventing a concrete failure mode.

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 still conveys the return shape (slug, product count, ordering) and the default scope. Combined with the sibling hand-off, an agent has everything needed to call this correctly on the first try.

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 does not: it explains what the empty-argument case returns (top-level sections) and frames `parent` and `query` as two mutually distinct expansion paths rather than just two optional strings.

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 shop categories') plus the fields returned and ordering ('with slug and product count, biggest first'). This is clearly distinguishable from siblings like bn_brands or bn_search without opening any schema.

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

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

Explicitly covers the no-argument default ('returns the top-level sections'), the two argument paths ('Use `parent` to open one, or `query` to search all of them'), and routes the agent onward to bn_browse by telling it to pass the slug as `category`.

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), but the description adds real behavioral context the annotations cannot: unpriced items are skipped, matching is order-insensitive on title words, results are capped at a 2,000-item scan, and complete=false signals truncated results. That last point is critical for interpreting partial output and is exactly the kind of disclosure that prevents misreads.

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 behavior is front-loaded in the first sentence, followed by usage, parameter guidance, and result semantics in tight succession. Every sentence carries information, though the density is high enough that it reads as a compact spec rather than prose.

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: it specifies the sort order, currency, truncation flag, and what is excluded from results. Combined with full parameter coverage, an agent has everything needed to call this correctly and interpret the response.

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 beyond it by explaining the practical intent behind min_price ('skip accessories and spare parts') and by clarifying query matching semantics (words in any order, title-only). It adds usage-level meaning rather than restating field definitions.

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 the cheapest products'), the matching rule ('whose title contains every word of the query'), and the output ordering ('one list sorted by price (Toman)'). This is clearly distinguishable from sibling bn_search, which returns matches rather than a price-ranked cheapest-first list.

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 an explicit when-to-use trigger, and 'Check bn_product before buying' routes the agent to a sibling for the follow-up step. It also advises raising min_price to skip accessories, which is operational guidance. No explicit when-not-to-use case is stated, 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 readOnly/idempotent/openWorld and non-destructive, so the safety profile is covered. The description adds genuinely new behavioral context beyond them: prices are denominated in Toman and variable products expose variation options only, with no per-variation price or stock published by the shop.

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 returned payload, then the usage condition, then the caveat. 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?

With no output schema, the description carries the return-value burden and does so by enumerating the fields, plus flags the variable-product limitation. Nothing needed to call this correctly is missing.

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

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

One required parameter with 100% schema description coverage; the schema already names the id and its sources plus an example. The description adds nothing about the parameter, 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 ("Get one product") and enumerates the returned data (price, stock, rating, brand, categories, spec attributes, highlights, description, images), which distinguishes it from the sibling search/browse tools. An agent knows this is the single-id detail lookup, not a list operation.

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 after a search or browse to check details of one id" gives explicit sequencing, and "Next: bn_reviews" routes onward. It lacks an explicit when-not (e.g., don't use for bulk or discovery), but the context is clear enough.

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, open world), so the bar is lower. The description adds genuinely useful behavioral context beyond the annotations: ordering is newest-first, dates are Gregorian, and many products carry a single generated 'summary of buyer opinions' that should be treated as marketing rather than real reviews.

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

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

Front-loaded with the core action and return shape, then the caveat about fake review summaries. Every sentence carries actionable information and nothing is redundant with 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?

No output schema exists, and the description compensates by naming the returned fields (rating, author, date, text). Combined with the data-quality warning and date-format note, an agent has everything needed to call and interpret this tool 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 page, limit, full_text and product_id are fully documented in the schema. The description adds only ordering (newest first) and the returned field set, which is mild added meaning. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb and resource ('Get buyer reviews of one product'), plus ordering (newest first) and the exact fields returned (rating 1-5, author, date, text). This clearly separates it from siblings like bn_search, bn_browse and bn_product, which retrieve products rather than reviews.

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

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

Gives a clear use case ('check quality or complaints') so the agent knows when this tool is appropriate. However, it does not name an alternative or state when not to use it, so it stops short of explicit 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 and openWorld, so safety is covered. The description adds a genuinely non-obvious behavioral rule beyond structured data: a multi-word query must match as a phrase in the title, unlike bn_find_cheapest. It stops short of describing result-set size, total counts, or empty-result 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?

Three tight sentences, front-loaded with purpose, then usage, then routing. Every clause carries information — the phrase-matching caveat and the sibling handoffs are the kind of detail that prevents mis-invocation rather than 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?

With no output schema, the description does name the returned attributes (ids, price, stock, rating), which is the key missing piece an agent needs. It does not cover pagination behavior in general or how to tell when results are exhausted, a minor gap for a 7-parameter search tool.

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

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

Schema description coverage is 100%, so the baseline is 3 and the schema already documents page/limit/sort/price bounds. The description earns above baseline by explaining query matching semantics (phrase-in-title, Persian or English) and currency units (Toman), which the schema only partially conveys.

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 Baneh products by name in Persian or English'), names the fields returned (price in Toman, stock, rating), and explicitly distinguishes itself from siblings bn_find_cheapest and bn_product. An agent can route to this tool without opening any schema.

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

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

Gives explicit when-to-use ('Use to find products and their ids') plus two named alternatives with the condition that selects each: bn_find_cheapest for lowest price with order-free word matching, bn_product for a single id. The phrase-match constraint is also flagged as a reason to prefer the sibling.

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