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

Annotations already declare readOnly/idempotent/non-destructive, so the safety bar is low; the description adds genuinely useful behavior beyond them — cross-script matching (Persian or Latin names) and the fallback that omitting the name lists brands instead of erroring. No rate limits or truncation behavior are mentioned, keeping it 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?

Two sentences, zero filler: the lookup behavior and the downstream chaining are both front-loaded and each sentence carries a distinct instruction.

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 2-param read tool with full annotation coverage and no output schema, the description covers what it returns (brand ids), both invocation modes, and how the result is consumed downstream. 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 coverage is 100% and both parameters are already documented there, including the Persian/Latin example, so the baseline is 3. The description's added detail (empty query lists first brands) is really mode behavior rather than parameter meaning, and it doesn't explain how 'limit' interacts with the listing mode beyond the schema default.

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 + resource: 'Find brand ids by name', plus the two operating modes (name lookup vs. listing first brands). It also distinguishes itself from siblings by naming where the output goes (bm_browse / bm_search as brand_id), so an agent can place it in a workflow immediately.

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 states the condition under which each mode applies ('when no name is given') and what to do with the result ('Pass the id to bm_browse or bm_search as brand_id'). It stops short of a when-not rule or an alternative lookup path, but the intended usage context is unambiguous.

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 that results use 'the same filters and cards as bm_search' and that at least one scoping id is needed, but says nothing about pagination limits or result volume 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 sentences with no filler; the purpose and the scoping requirement are front-loaded before the workflow hint. Every clause carries information an agent needs.

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 browse tool with full schema descriptions and no output schema, the description covers purpose, required inputs and the calling sequence adequately. It omits only return-shape detail, which is partly implied by the 'same cards as bm_search' reference.

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 contributes something the schema does not: the cross-tool constraint that at least one of category_id or brand_id must be supplied, in a schema where nothing is required. The reference to bm_search filter parity also helps an agent infer the remaining filter semantics.

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

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

States a specific verb+resource ('List the products of a category and/or brand') and scopes it to a section rather than a query. It partially differentiates from siblings by pointing at bm_search for filter parity and bm_categories/bm_brands as inputs, though it never says outright how browse differs from bm_search in intent.

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 precondition ('Give at least one of category_id or brand_id') and a clear workflow cue ('Use after bm_categories or bm_brands to see a whole section'). It lacks an explicit when-not-to-use-this-vs-bm_search statement, 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 readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds real value beyond that by disclosing the return shape (id, name, level, parent_id) and the semantics of level ('deeper = narrower'), which is meaningful behavioral context despite there being no output schema.

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

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

Two front-loaded sentences: purpose and mode selection first, then return fields, then the downstream hand-off. Every clause earns its place with 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?

No output schema exists, so describing returned fields is required and it does so (id, name, level, parent_id). For a zero-required-parameter read-only tree lookup, 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 coverage is 100%, so the schema already documents limit, query, and parent_id, making 3 the baseline. The description adds interaction semantics the schema does not capture (no arguments yields top sections, parent_id yields children), which lifts it slightly above 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 ('Find category ids by name, or walk the tree') and covers both operating modes. It also names the sibling tools (bm_browse, bm_search) that consume the returned ids, so an agent can distinguish this lookup tool from them without opening a schema.

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

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

Gives explicit mode-selection guidance: no arguments = top sections, parent_id = children, and routing the output to bm_browse or bm_search. It doesn't state when NOT to use this tool or contrast it with a sibling category-like tool, so it stops short of full when/when-not/alternatives coverage.

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 read-only, idempotent, non-destructive behavior, so the bar is lower; the description adds genuinely new context that the list changes daily and sells out quickly, plus what each card contains (final_price, discount_pct, units left). It does not discuss pagination limits or empty-result behavior, keeping it 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?

Three tightly packed sentences with the purpose front-loaded and no filler. Minor redundancy between 'time left', 'left (units in stock)' and 'sells out quickly', but nothing wasteful overall.

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

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

For a zero-required-param read tool with no output schema, the description covers the return shape (card fields), the volatility caveat, and sibling routing. Missing only pagination/empty-state details, which is 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% and both parameters (page, limit) are fully documented in the schema with ranges and defaults. The description adds no parameter-level guidance (e.g., how to walk pages or handle the 24-per-page cap), 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 and resource ('List today's flash-sale products') with scope qualifiers ('deep time-limited discounts', 'with the time left'). It also distinguishes itself from the closest sibling by noting bm_product should be used for sizes.

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

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

Provides an explicit use case ('what is on sale right now') and routes the agent to bm_product for size lookups. It lacks an explicit when-not/negative condition, but the trigger context is clear enough to select this over browsing tools.

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 read-only, idempotent, non-destructive, so the safety profile is covered. The description adds domain-specific behavioral context the annotations cannot: prices are in Toman and final_price is the customer-facing amount while price is pre-discount. It does not cover failure behavior (e.g., invalid or missing product_id).

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, each of which earns its place: what is returned, when to call it, and how to interpret the price fields. The purpose is front-loaded before the usage hint.

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 enumerates the returned content (per-color price/discount, per-size stock, features, short description) and disambiguates the two price fields, which is exactly what an agent needs to consume the response. Nothing material is missing for a single-parameter 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 description coverage is 100% and the single product_id parameter is fully documented in the schema (including an example id). The description adds nothing beyond it, 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 and resource ('Get one product') and enumerates the returned facets (colors, price, discount, per-size stock, features, short description). An agent can distinguish it from bm_search/bm_deals, which surface candidates rather than full detail for a single item.

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 names the sequencing context ('Use after bm_search or bm_deals') and the decision it supports (checking size stock and per-color cost). It does not state any when-not conditions or what to do for other lookups (e.g., bm_reviews for reviews), so it falls slightly short of full routing guidance.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description still adds real value beyond them: it warns that a review's stars may be null when the review is text-only, and it flags that review text is user-generated and must be treated as data (a prompt-injection guard). It does not discuss pagination limits or rate limits, which keeps it below 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 tight sentences: the first states what is read and what comes back, the second states when to use it and a safety caveat. Nothing is redundant, and the most decision-relevant content (what the tool reads) 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?

There is no output schema, and the description compensates by describing the return shape (stars 1-5 or null, text, date, shop answer). Combined with full param coverage and annotations that already establish the safe-read profile, 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% (both page and product_id are documented, including the 10-per-page rule and the id example), so the schema carries the parameter burden. The description's parenthetical about stars is about return values rather than parameters, so it adds nothing 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?

The description opens with a specific verb+resource ("Read customer reviews of a product") and even enumerates the returned fields (stars, text, date, shop answer), which makes the tool's scope unmistakable against siblings like bm_product or bm_search. It stops short of naming an alternative tool, so it does not fully reach the 5 criteria, but the resource distinction is clear.

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

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

It gives concrete usage context — "Use to judge fit and quality ('runs big', 'thin fabric')" — which tells an agent what class of question this tool answers. There is no explicit when-not guidance or named alternative (e.g., bm_product for specs), so it stops at clear context without exclusions.

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

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

Annotations already establish the safe read-only, idempotent, open-world profile, and the description adds genuinely new behavior: result granularity is one card per product-color, so the same id legitimately repeats, and each card carries price, discount, color and in-stock sizes. It doesn't mention rate limits or result-count caps beyond what the schema already says.

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: what is searched, what comes back, and what to do next. The card-granularity caveat is placed immediately after the return description where it matters, with 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 read-only 10-parameter search with full schema coverage and no output schema, the description covers the return shape, granularity and follow-up path. Pagination limits and any result truncation behavior are left entirely to the schema, which is acceptable but leaves minor gaps.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds value by tying natural-language query intents to filters (price ceilings in the examples correspond to min_price/max_price and 'cheapest' to the sort enum). It stops short of mapping examples to explicit parameter names.

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 Banimode fashion products by keyword') and even describes the shape of the result ('priced cards with discount, color and sizes in stock'). It differentiates from bm_product as a follow-up drill-down, but leaves bm_browse, bm_deals and bm_categories undifferentiated, so an agent can't fully route between the search-family siblings from this text 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 usage scenarios ('cheapest white sneakers', 'men's jeans under 1M') and an explicit next-step rule: call bm_product with the id for full size/stock/color detail. It does not state when to prefer bm_browse or bm_deals instead, so the when-not guidance is missing.

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