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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint), so the bar is lower. The description still adds real behavioral context beyond them: what is returned (ids and, for query, the full path), the 12-item top-level count, and the interaction rule when query and parent_id are combined. It does not mention pagination or whether reads are cached/rate-limited, but for a public catalog listing that is a minor gap.

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 and the downstream use case, then the branching logic. No filler, no restatement of the title.

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, but the description compensates by describing what comes back (ids, and a path for query hits). The main residual ambiguity is the exact shape of the response for a listing call (flat array vs. nested children), which the description implies but does not state.

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

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

Schema description coverage is 100%, so baseline would be 3, but the description adds semantics the schema cannot express: the interaction between the two parameters ('with both, query searches only inside parent_id's subtree') and the downstream meaning of returned ids. The schema already covers the per-parameter examples ('عسل', parent 1 for food).

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 ('Browse Basalam's category tree and return ids') and immediately ties its output to a downstream use case, the category_id filter of bs_search. An agent can distinguish it from bs_search, bs_product, etc. 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 enumerates the four calling modes: no arguments (12 top-level categories), parent_id alone (one level down), query alone (search whole tree by name, returns path), and both (query scoped to parent_id's subtree). It also notes that ids at any level work as filters, which tells the agent when the result is usable.

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 behavioral context beyond them: it discloses that only two pages of 48 are read and that out-of-stock and low-rated items are dropped, which tells the agent about result coverage and filtering.

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, purpose front-loaded, followed by behavior and parameter strategy. No filler sentences; 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?

For a read-only, idempotent search tool with no output schema and annotations covering safety, the description supplies filtering behavior, coverage limits, and param strategy. It does not sketch the shape of returned offer fields, a minor gap given no output schema exists.

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

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

With 100% schema description coverage, a 3 is the baseline. The description goes further by explaining the tuning strategy (raise min_price when results are accessories, narrow via category_id), adding inter-parameter intent beyond the per-field schema text.

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

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

Specifies a concrete verb and resource (list the cheapest in-stock offers for a query), plus ordering (cheapest first) and currency (Toman). The 'cheapest/in-stock' framing clearly separates it from the general bs_search sibling.

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?

Offers actionable conditional guidance: raise min_price when results are still accessories and narrow with category_id from bs_categories, which routes the agent to a sibling tool. It lacks an explicit statement of when to prefer this over bs_search, so it falls short of a full 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 goes further by explaining the shipping-related fields (free_shipping_over threshold vs. free_shipping qualifying on this product's price alone), which is real behavioral context an agent needs to interpret the result. It does not discuss auth or rate limits, and the field list overlaps somewhat with the return surface, so it stops short of 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?

Front-loads the tool's output in the first sentence, then usage routing, then the shipping nuance. Three dense sentences with no filler, though the closing shipping sentence is packed tightly and slightly crowded against the rest.

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

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

For a single-item read with no output schema, the description covers the returned content, the follow-up routing, and the shipping-eligibility semantics well enough to call correctly. Minor gaps remain around pagination/truncation outside the full_text flag, but nothing essential is missing.

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

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

Schema description coverage is 100%, with both product_id (format, example) and full_text (truncation behavior) documented in the schema itself. The description adds nothing about either parameter, 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?

Opens with a specific verb+resource ('Get one product') and enumerates exactly what is returned: price in Toman, discount, stock, options, attributes, rating and shop. This is plainly distinguishable from the sibling search, vendor, and review tools.

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

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

Explicitly states when to call it ('after bs_search or bs_find_cheapest to check the details before recommending') and routes the agent elsewhere by intent: bs_reviews for opinions, bs_vendor for shop reliability. Alternatives and conditions are named, not inferred.

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

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

Annotations cover the safety profile (readOnly, idempotent, non-destructive), and the description adds context they cannot: the exact payload (product and shop average stars, review fields, shop replies), default truncation to 400 characters, and an explicit prompt-injection caution for user-generated review text. That last item is genuinely useful behavioral guidance for an agent handling untrusted content.

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 plus a compact parenthetical list. The purpose and ordering are front-loaded, and the safety caveat is correctly placed last. No sentence goes to waste.

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 burden and does so: it enumerates what comes back and warns about truncated text. Pagination and limits are handled by the schema, so nothing material is missing for correct invocation.

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

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

Schema description coverage is 100%, so all four parameters are already documented (limit, offset, full_text, product_id with example). The description mentions the 400-character truncation behaviour but adds no syntax or format meaning beyond the schema. 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 ('Read customer reviews of a product') plus distinguishing scope details: the star histogram, newest-first ordering, and the return contents. It is readily separable from siblings like bs_product or bs_search 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?

Usage is implied by the resource named, but there is no explicit when-to-use guidance, no conditions selecting this over siblings (bs_product, bs_search), and no prerequisites. Minimum-viable routing guidance only.

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, yet the description still adds non-obvious behavior: results arrive as paginated cards priced in Toman, and adjacent pages can repeat products (a real dedup hazard for an agent paging through results). It also supplies the canonical product URL pattern. It stops short of rate limits or total-result availability, so not a full 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 tight sentences, front-loaded with the core action and return shape before the sibling routing. Every clause carries information an agent needs; nothing is padding.

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

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

For an 11-parameter, no-output-schema, open-world search tool, the description covers action, return format, routing and the pagination duplication caveat, which is enough to call it correctly. Minor gaps remain (no mention of how to detect the last page or of rate limits), so it is strong but not exhaustive.

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 all 11 parameters carry inline descriptions with defaults, ranges and examples, so the schema does the heavy lifting. The description adds only the general note that filters and sort run server-side, and restates Toman pricing which is already in max_price/min_price. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('Search Basalam products') plus the concrete return shape ('a page of cards with prices in Toman'), and explicitly separates itself from three siblings by name. An agent can distinguish it from bs_find_cheapest, bs_product and bs_vendor_products 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 the primary use case ('browsing a product type') with the note that filters and sort are applied server-side, then names the alternative for each neighbouring intent — ranking by price (bs_find_cheapest), single product (bs_product), single shop catalog (bs_vendor_products). Routing conditions are explicit rather than inferred.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety and world-interaction profile is covered. The description adds the returned field set, which is useful, but says nothing about rate limits, failure behavior, or what an inactive/new shop response looks like.

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: the first front-loads what is returned, the second covers routing and the sibling alternatives. No filler or restatement of the name.

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

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

There is no output schema, but the description compensates by enumerating the profile fields returned. Combined with annotations covering the safety profile and full schema coverage on the single parameter, nothing essential is missing for correct invocation.

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

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

Schema description coverage is 100% and the single parameter's description already explains it is the shop_id from search results with an example. The description adds no further parameter guidance, so the baseline 3 applies.

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

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

States a specific verb and resource ('Get a Basalam shop's profile') and enumerates the exact contents (city, product count, shipping methods, activity, notice). It also explicitly separates this tool's scope from siblings bs_reviews (stars) and bs_vendor_products (catalog).

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 when-to-use condition: 'judge a seller before buying (new shop, inactive).' It also routes the agent to the right sibling for related data. It stops short of stating when-not to use it or any prerequisites, so it is clear context rather than a full when/when-not rubric.

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/destructive=false, so the bar is lower. The description nonetheless adds real behavioral facts beyond them: an unknown shop is an error rather than an empty list, and the product link template https://basalam.com/p/<id>. It does not cover pagination 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?

Three compact sentences, front-loaded with purpose, then usage context, then error semantics and link format. No filler; each sentence carries distinct 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 10-parameter read tool with no output schema, the description covers purpose, entry path, error behavior, and link output. It omits pagination behavior and return shape detail, but annotations carry the safety profile, so the 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 schema already documents all 10 parameters including Toman prices, the sort enum, and category_id sourcing. The description's 'prices in Toman, searchable and sortable' merely restates schema content, 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 with scope: 'List one shop's products with prices in Toman, searchable and sortable.' The scoping to a single shop plus the shop_id sourcing note distinguishes it from bs_search (cross-shop search) and bs_product (single 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?

'Use after bs_vendor or when the user names a shop' gives an explicit trigger condition and names the predecessor tool. It stops short of stating when NOT to use it (e.g. use bs_search for cross-shop queries), so it is clear context without full exclusion guidance.

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