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 description's real contribution is the fuzzy name-resolution behavior: names map to the top search match and ids should be passed for exactness. That is a genuine behavioral caveat an agent would otherwise miss, though it says nothing about what happens when no single shop stocks everything.

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 the core behavior and the caveat placed second. The parenthetical reference to items[].name is compact, though it points at a response field with no output schema to anchor it.

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 sketch the return shape ('best single shop' plus 'split-cart total'), which is the minimum needed. It omits the fallback behavior when no single shop covers the list and leaves the min_score threshold unexplained for a tool with five parameters.

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 80%, so the baseline applies. The description meaningfully clarifies the `items` parameter (names resolve loosely; verify against the returned items[].name), but the undocumented `min_score` parameter — a scoring threshold with no schema description — is not addressed at all.

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 computation over a specific resource: cheapest single shop covering a whole list plus the split-cart total. That is clearly distinct from single-product siblings like tb_cheapest and tb_compare, though it never names those siblings explicitly.

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 phrase 'whole shopping list' implies the multi-item use case, distinguishing it in spirit from single-item price tools, but there is no explicit when-to-use/when-not or named alternative such as tb_cheapest or tb_shop. The agent must infer the routing decision.

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 description's job is to add constraints — and it does: results are ranked, priced in Toman, restricted to in-stock products, and explicitly carry no quality score. That last point is a genuinely useful disclosure about what the tool will NOT return. It does not describe the shape of the ranked output, which matters since there is 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?

Three short sentences, front-loaded with the core purpose before the example and the tb_compare hand-off. Every clause carries information; the phrase 'No quality score: check specs with tb_compare' is slightly compressed but still readable.

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 and no output schema, the agent is left inferring what a 'ranked pick' record contains (price, shop count, model info) and how ranking changes with rank_by. The in-stock and no-score caveats are helpful, but for a tool of this complexity the description stops short of fully arming the caller.

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 71%, so the schema carries most parameter meaning, and the description adds only the Toman currency for budget — which the schema already states ('Max price, Toman.'). The ranking behavior of rank_by, the limit cap of 30, the query/category interplay, and the min_shops shop-count filter are not illuminated beyond their schema text. Baseline 3 for a well-covered schema 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?

It names a specific verb+resource ('Ranked product picks that fit a budget') and anchors it with a concrete intent example ('best phone under 30 million'), so the agent knows this is a budget-constrained discovery tool. It also pre-empts confusion with a rating tool by stating 'No quality score'. It does not, however, distinguish itself from close siblings like tb_cheapest or tb_search.

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 through the example intent and the hand-off 'check specs with tb_compare', which tells the agent where to go for quality comparisons. But there is no explicit when-to-use/when-not versus tb_cheapest, tb_search, or tb_suggest, which are the most likely competing choices for the same request.

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, destructiveHint=false and openWorldHint, so the safety profile is fully covered. The description adds only the scoping fact (results are per-category) and the id-passthrough purpose; it says nothing about the limit/pagination behavior implied by the default of 60 and max of 100.

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 short sentence that front-loads the resource and its scope, with the integration hint second. Nothing is redundant, though the terseness edges toward under-specification rather than crispness.

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 lookup with rich annotations, no output schema, and mostly documented parameters, the description covers what the tool returns (brands plus ids) and why. The only material gap is the undocumented limit parameter and the resulting pagination behavior.

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 67%: category and search are documented in the schema, while limit has no description anywhere. The tool description adds no parameter-level detail beyond implying that category drives the result set, so it neither compensates for the undocumented limit nor adds meaning over 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?

The description names a specific resource (brands), scopes it to a category, and states the return payload (brand ids). That distinguishes it from siblings like tb_filters or tb_search — this is a lookup that feeds one of them — though it never explicitly contrasts itself with tb_filters, which also returns taxonomy data.

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 parenthetical '(for tb_search brand=)' gives a concrete chaining hint: call this to obtain the id value that tb_search expects for brand. There is no explicit when-not guidance and no mention of tb_filters as the place to discover category ids, so the agent must infer the workflow entry point from the schema rather than the description.

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, open-world behavior, so the safety profile is covered. The description adds return-content context (ancestors plus sub-categories plus top products), which is valuable given there is no output schema, but it says nothing about pagination over the 10-default limit or what happens at tree edges.

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, front-loaded with what the caller gets, followed by the routing rule. No filler and nothing redundant.

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 carry the burden of describing results and does so briefly (parents, sub-categories, top products). Given six parameters that include filtering and pagination, an agent still has to infer how results are paged and ordered, keeping this short of full coverage.

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?

At 67% schema coverage, the description adds essentially no meaning for page, limit, sort, brand, or max_price — all are left to the schema. The only parameter-adjacent info is the parenthetical showing that tb_search also accepts a category argument, which is a cross-tool hint rather than semantics for this tool's inputs.

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?

"A category page: its parents, sub-categories and top products" states the resource and enumerates what comes back, and "Use to walk the category tree" gives the agent an unambiguous job for the tool. It is clearly separable from tb_search, though it stops short of a verb-first statement of the 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?

Explicitly routes text queries elsewhere: "For text search in a category use tb_search(category=)" names the sibling and the condition that selects it. No guidance is given on when to prefer other category-adjacent siblings (tb_filters, tb_brands), but the main disambiguation is handled.

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, open-world, and non-destructive, so the safety profile is covered. The description adds real value beyond that: it discloses the multi-step search-then-check-every-shop behavior and warns that the matched product name may not be exact, which is important for trusting results. It stops short of stating cost/latency implications of checking multiple candidates.

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

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

Two short sentences, front-loaded with the purpose, with no filler. The return-shape sentence is slightly compressed ('per top match and the overall `cheapest`'), but nothing is wasted.

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 6-parameter, no-output-schema tool, the description covers purpose, internal search behavior, return shape, and the fuzzy-match caveat. The main remaining gap is that it doesn't quantify that each candidate match costs an extra request, though the schema's candidates description mentions 'one request each'.

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 every parameter is already documented, and the baseline is 3. The description reinforces the query semantics ('named in words') and implies the candidates concept via 'top match', but adds nothing about city, condition, min_score, or installment_only beyond what the schema states.

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 uses a specific verb+resource ('Cheapest trustworthy offer for a product named in words') and explains the internal two-step behavior (search, then inspect every shop's offer). It is clear what the tool returns ('best usable offer per top match and the overall cheapest'), though it doesn't explicitly contrast itself with near-neighbors like tb_offers, tb_best_value, or tb_compare.

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 only implied: you supply a product 'named in words' and get the cheapest trustworthy offer. There is no explicit when-to-use vs. when-not, and no sibling is named as an alternative for cases like browsing all offers (tb_offers) or comparing specific products (tb_compare). The 'check the matched name' note is a useful caveat but not routing guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered without the description. The description's only added value is workflow context (these ids feed `city` arguments) plus three sample mappings; it says nothing about how results are ordered, paged, or capped.

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 compact sentence with the purpose front-loaded and no filler. The parenthetical example IDs are genuinely useful for grounding the identifier format, though they are an arbitrary three-city sample that could mislead about coverage.

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 and half the parameters undocumented, the description should explain that the tool returns a list of cities with their ids and how `search`/`limit` shape that list. Instead it only asserts the id mapping, leaving the agent to infer the return shape and filtering behavior.

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 only 50%: `search` is documented in the schema, but `limit` (default 10, max 50) has no description anywhere. The description mentions neither parameter and does not compensate for the gap by explaining filtering by Persian name or result limiting.

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 the concrete resource (city ids) and the reason it exists (to be fed into `city` arguments of other tools), which distinguishes it from siblings like tb_stores or tb_products. It lacks an explicit verb describing the operation (list vs. search), so an agent knows what it yields but not exactly what it does.

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 phrase 'for `city` arguments' implies when to call it: whenever a `city` parameter is needed elsewhere. There is no explicit when-not guidance, no mention of alternatives (e.g. omitting the argument to get defaults), and no statement that omitting `search` returns the most visited cities.

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, open-world, so the description is not required to explain safety. It adds genuinely new behavioral context: the result is filtered to only differing specs, includes a price window, and the `differences` map carries null for unlisted values. That last detail is important, because null would otherwise be ambiguous between 'not listed' and 'unknown'.

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: the first front-loads the operation and the output summary, the second handles the one non-obvious return-value convention. Nothing is repeated from the schema or title, and no sentence is filler.

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

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

For a single-parameter, read-only tool with no output schema, the definition covers input cardinality, input format (via schema), and the shape of the response, including null semantics. The remaining gap is failure behavior: it doesn't say what happens when an id is invalid, a product has no offers, or fewer than 2 valid products resolve.

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?

Reported coverage is 0% (the schema's own description text is minimal), and the schema already encodes minItems 2 / maxItems 5; the description reinforces the 2-5 range in prose. More importantly, it explains that values in `differences` follow the `products` argument order, so the order in which the caller supplies ids is semantically meaningful. That is meaning beyond the schema, though it doesn't say whether duplicate ids are rejected or normalized.

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 operation ('side-by-side comparison of 2-5 products') and enumerates what it returns: differing specs, price window, cheapest pick. That is far more specific than the title 'Compare products'. It does not, however, distinguish itself from close siblings such as tb_cheapest, tb_best_value, or tb_products_batch, which an agent could plausibly pick for the same 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?

Usage is implied by the 2-5 product cardinality and the comparison framing, so an agent can infer 'use when the user wants several products contrasted'. There is no explicit when-to-use statement, no exclusion of tb_cheapest/tb_best_value (whose purposes overlap with 'which is cheapest'), and no note on what happens for a single product or unknown ids.

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 disclosing the actual scoring model (100 minus price percentile among past weekly minimums, minus up to 20 when above today's cheapest usable offer) and noting a `reasons` field, which is real behavioral insight not captured in 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?

Roughly 40 words, front-loaded with the question and the output form, with zero filler. The formula sentence is somewhat dense in notation ('minus the price's percentile...') and slightly harder to parse than a plain-language restatement would be, but nothing is redundant.

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 2-parameter, annotation-covered, no-output-schema tool, the definition covers what the tool returns and how it is computed. The only minor gap is not stating what `reasons` contains or what the score means in practical terms (e.g., thresholds for 'good'), though the return-format burden is light here.

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

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

Schema description coverage is 100%, including the 'default today's cheapest usable offer' behavior and the Toman unit, so the schema carries most parameter meaning. The description reinforces the comparison basis (past weekly minimums vs today's competing offers) but adds no syntax or format detail 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?

Opens with the user-facing question the tool answers and states a concrete output: a 0-100 score derived from the product's price history plus today's competing offers. That framing (a judgment/score) is clearly distinct from sibling tools like tb_price_history, tb_cheapest, tb_compare, and tb_best_value, so an agent can route 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?

Usage is implied rather than stated: it is for judging whether a specific offered price is fair. There is no explicit when-to-use/when-not-to-use guidance and no sibling is named as an alternative (e.g., 'for raw series, use tb_price_history'), which leaves the agent to infer the boundary.

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 safety and determinism are covered. The description adds useful output-shape context (it returns attribute slugs/values usable as filter inputs) but says nothing about empty results, latency, or whether filters are query-dependent versus category-dependent.

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

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

Two short sentences, front-loaded with the return payload followed by the usage rule; nothing is padding. The first sentence is a fragment without a verb, which is slightly clipped but still readable.

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 two optional params, no output schema, and rich annotations, the definition covers the essentials: what the call yields and how to use the result in a follow-up search. The remaining gap is the undocumented `category` parameter and the interaction between the two optional inputs.

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 only 50%: `query` has a description and example in Farsi, while `category` is an undescribed integer. The phrase "category / brand ids" hints that `category` consumes an id rather than a name, which is real added meaning, but it never states where that id comes from (tb_category) or how query and category interact when both are supplied.

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 the specific resource and enumerates the payload: sub-categories, brands, price span, sort options, and attributes returned for a query/category. It implicitly distinguishes itself from tb_search by being the metadata-discovery step, though it never explicitly says it does not return products.

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

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

"Use before tb_search for category / brand ids or the attribute slugs and values" gives a clear sequencing rule and names the downstream sibling, which is stronger than most definitions. It stops short of covering edge cases such as calling with neither query nor category, or when to prefer tb_category/tb_brands for ids instead.

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 non-destructive behavior, so safety is covered. The description adds the useful fact that the lookup key can be either a name or a domain and that results are ids meant for follow-up tools, but says nothing about pagination, result caps, or empty-result behavior for a directory search.

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 tight sentence with the action, data source, lookup keys, and return value front-loaded; there is no filler or redundancy.

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 partially compensates by saying it returns ids for tb_shop and tb_shop_products, which is genuinely useful. But for a 5-parameter paginated search it omits pagination behavior and total-count semantics, so key operational details an agent needs are 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 60%: query, city, and kind are documented in the schema, while page and limit have no descriptions. The description's 'by name or domain' restates the query parameter but adds no new semantic detail, and it does not compensate for the undocumented pagination parameters. 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 ('Find shops in Torob's directory') and the lookup key ('by name or domain'), plus names the downstream consumers (tb_shop, tb_shop_products). It does not disambiguate from close siblings like tb_stores or tb_sellers, so it falls short of a 5, but the purpose is unambiguous.

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 phrase 'returns ids for tb_shop and tb_shop_products' implicitly tells the agent this is a discovery/lookup step that should precede those calls. However, there is no explicit statement of when to use this instead of tb_stores, tb_sellers, or tb_search, and no exclusions or prerequisites.

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 without the description's help. The description adds no behavioral context beyond annotations: no mention of pagination depth limits, the heavy payload cost, or what a 'row' contains. The 900 KB-per-row cost note lives only in the parameter schema, not here.

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?

It is a single tight sentence with zero filler and the resource name is front-loaded. However, its brevity comes at the cost of information: the one sentence could have carried a usage cue or payload warning at little length cost.

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 three optional paging parameters, no output schema and no required inputs, the description is complete enough to identify the target but not enough to call it confidently, since the nested rows-of-products return shape goes unexplained. An agent would need to guess how results are structured and what a single page yields.

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 sits at 67%: size and limit carry upstream descriptions, but page is undocumented. The description adds nothing about any parameter — not the page/size/limit interplay, not what a 'row' versus a 'product' means operationally — so it fails to compensate for the uncovered parameter.

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 resource (Torob's special-offers feed, "پیشنهاد ویژه") and states its contents: themed rows with discounted or promoted products. The retrieval verb is only implied by 'feed', and no sibling (tb_suggest, tb_deal_check, tb_cheapest) is named to distinguish it, 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?

There is no guidance on when to call this instead of the many overlapping siblings such as tb_suggest, tb_deal_check or tb_cheapest, and no prerequisites or exclusions are stated. The agent must infer usage purely from the resource name.

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, open-world behavior, so safety is covered. The description adds the useful signal that results span online shops, physical stores, installment/warranty sellers, and a price window – behavioral context beyond the annotations. It does not describe result shape or whether the answer is a count, list, or summary.

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?

It is a single short fragment with no wasted words, but the terseness comes at the cost of precision: no verb, and 'price window' is left unexplained. Short is not the same as well-structured here.

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 one required parameter, no output schema, and full annotation coverage, the definition is nearly complete for invocation. However, it never explains what 'how widely' means operationally (counts? shop list? range?) or what a 'price window' is, leaving the return semantics ambiguous.

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 the single 'product' parameter is fully documented (UUID or torob.com URL), so the schema carries the burden. The description adds nothing about how the product input affects the presence result, 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?

The description identifies the resource as how widely a product is sold across shop types, but it is a noun phrase without a verb, and terms like 'price window' and 'presence' are not defined. An agent can guess it returns availability/distribution info but cannot state precisely what the tool returns versus tb_offers or tb_stores.

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?

No when-to-use guidance and no exclusions are given, despite many plausible siblings (tb_offers, tb_stores, tb_find_shops, tb_sellers, tb_cheapest) that could be confused with it. The agent must infer that 'presence' means distribution breadth rather than price comparison.

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?

The annotations already cover safety (readOnly, idempotent, non-destructive, open-world), so the description's added value is in disclosing data shape: weekly series over roughly a year, prices in Toman, and a verdict field derived from a percentile statistic. It explains the verdict's enum semantics and derivation, which is genuinely useful beyond the annotations. Minor tension: it says 'about a year, weekly' while the schema default of 26 points yields about 6 months.

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 with the core purpose front-loaded and the verdict/percentile explanation following. Every clause carries information; only the year-vs-default-points mismatch slightly muddies an otherwise clean statement.

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 carry the return-value burden, and it only partially does: it names summary.verdict and the percentile concept plus min/average prices, but not the shape of the chart series itself. For a read-only two-parameter tool this is adequate but leaves the primary output structure underspecified.

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, points) are already fully documented in the schema, making 3 the baseline. The description adds only indirect meaning, tying the weekly cadence to the series length, but does not clarify how 'points' interacts with the stated one-year window.

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 resource (a product's price chart), its granularity (weekly, about a year), the metrics returned (minimum and average price in Toman) and an added output (a buy-now verdict). That is enough to tell it apart conceptually from siblings like tb_price_history or tb_trends, though it never names an alternative explicitly.

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 'buy-now verdict' phrasing implies the decision-support use case, so an agent can infer when this tool is relevant. However, there is no explicit when-to-use or when-not-to-use statement and no routing against the closely overlapping siblings tb_price_history and tb_deal_check.

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, open-world behavior, so the safety profile is covered. The description still adds real context beyond them: newest-first ordering, inclusion of the lowest and highest point, weekly granularity, and the sign convention that a negative change_pct is a drop. What it doesn't add is any sense of cost, latency, or what happens when no move clears the threshold.

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

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

Two short sentences with the core behavior front-loaded and no filler. The second sentence is dense and slightly cryptic ('the chart's minimum price' presumes familiarity with the price-chart tool), but nothing is redundant.

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 carry return-value information, and it partially does: ordering, the presence of low/high points, and the change_pct sign convention. It omits the per-event shape beyond change_pct (timestamps, price values) and never clarifies how min_change_pct defaulting interacts with the 'notable' definition, leaving a moderate gap for a 3-parameter analytical 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 67%, with product and min_change_pct documented inline but limit undocumented. The description gives meaning to the threshold indirectly ('notable', 'ignore smaller moves' via the schema default of 3) and clarifies the sign of change_pct. It does not explain that limit caps the number of returned events, so one parameter remains semantically thin in both places.

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 concrete resource and behavior: notable price moves for a product, ordered newest first, bounded by lowest and highest points. The second sentence defines 'notable' as weekly moves of the chart's minimum price, which sharpens the otherwise ambiguous word. It stops short of naming a sibling (e.g. tb_price_chart) as the alternative, so the boundary with the raw-series tool is only implied.

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 is implied rather than stated: an agent can infer this is for summarizing significant movements versus fetching a full series, especially from the 'chart's minimum price' reference. There is no explicit when-to-use/when-not-to-use clause and no named alternative such as tb_price_chart or tb_deal_check, leaving the choice 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?

The annotations already declare read-only, idempotent, open-world, and non-destructive behavior. The description adds useful domain-specific semantics beyond the annotations: price_min/price_max include unreliable offers, while cheapest_offer is the cheapest usable offer on the page.

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 description is front-loaded with the core purpose and then adds one focused clarification about price reliability. Both sentences are useful and there is no redundant or filler text.

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

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

For a simple two-parameter read-only tool with full schema coverage and annotations, the description gives a clear inventory of returned fields and explains an important price caveat. It is nearly complete, though it could briefly clarify how this differs from related tools like tb_offers or tb_variants.

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 schema already explains that 'product' accepts a UUID or torob.com URL and that 'full_specs' adds the full spec table. The description does not add further meaning about the input parameters, 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?

The description states a specific resource and scope: a full record for one product, listing name, price range in Toman, category, brand, key specs, and cheapest offer. It distinguishes itself implicitly from search/batch siblings by focusing on a single product, but it does not explicitly name alternatives such as tb_offers or tb_variants.

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 'Full record of one product,' suggesting this is for retrieving details about a known single product rather than searching or listing many. However, there is no explicit when-to-use guidance, no exclusions, and no named alternatives among the many sibling 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 cover safety (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint), so the description's job is to add operational detail — and it does: 'one request per product' discloses the fan-out cost, and 'failures go to errors' discloses partial-failure semantics rather than all-or-nothing behavior. It stops short of noting rate-limit or throttling implications of that per-product fan-out.

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

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

Two short sentences, front-loaded with the payoff (what records you get and how many), followed by the operational caveat. No filler; the line break before the failure-handling note is slightly odd but the content 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 correctly spends its budget enumerating return fields (name, price window, shop counts, category, brand) and documents error routing, which is the main behavioral unknown for a batch call. Remaining gaps — identifier format, partial-success ordering, whether missing products count as errors — are moderate rather than disqualifying.

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 reported at 0%, so the description needs to carry the parameter meaning, and it largely does not — it never says whether the array accepts UUIDs, URLs, or both, nor what happens to malformed entries. Its only parameter-relevant content ('up to 10 products') merely restates the schema's maxItems constraint.

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 the resource (short product records) and the scope (up to 10 products at once), and enumerates the returned fields, so an agent can tell what it gets back. The verb is implicit rather than stated, and it never names the single-item sibling tb_product, so the batch-vs-single distinction must be inferred from 'at once'.

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 only implied: the 'up to 10 products at once' framing suggests this is the multi-product path versus a single-product lookup, but there is no explicit when-to-use or when-not-to-use statement and no alternative tool is named despite tb_product, tb_search and tb_offers being available siblings.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false. The one thing the description adds beyond them is "no request is sent", which usefully tells the agent this never touches the network despite openWorldHint=true, but it says nothing about the shape of the result or how malformed input is handled.

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 with zero filler; the operation and its key caveat arrive together.

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 one-parameter utility with no output schema, the description covers the essentials. It still leaves an agent guessing what the returned "clean" value looks like (full URL vs path vs id) and what happens on invalid input.

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 applies. The description's mention of "path" slightly extends the schema, which only documents a UUID or full URL, and the plural "path or link" hints at additional accepted forms — a modest but real addition.

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 gives a specific verb and resource ("Clean torob.com URL for a product id, path or link") and distinguishes itself from data-fetching siblings via "no request is sent". It falls short of a 5 because "clean" is left to inference — normalize, strip tracking parameters, or canonicalize?

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 parenthetical implies this is a pure formatting utility rather than a lookup, which nudges the agent toward it before calling tb_product. However, no sibling is named and no explicit when-to-use or when-not-to-use condition is stated.

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), so credit goes to what is added: the shape of each result card, the existence and meaning of `low_confidence`/`unmatched_terms` on weak matches, and that `price_span` reflects the unfiltered result rather than the filtered one. That last point is genuine non-obvious behavior an agent would otherwise misinterpret; auth/rate-limit behavior is still unstated.

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, no filler: result shape first, then the failure/rephrase path, then the one subtle output field that could mislead. Front-loaded and every sentence 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 correctly takes on the return-value burden, describing card contents and diagnostic flags. For a 15-parameter search tool it is reasonably complete, though it never mentions pagination limits, that query is optional alongside category, or when a sibling like tb_suggest should replace a rephrase attempt.

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 80%, so the baseline is 3 and the schema already documents most parameters including the city caveat and filter slug source. The description adds only one clarifying semantic — `price_span` measures pre-filter results, which matters for min_price/max_price interpretation — but says nothing about query-vs-category combinations beyond what the schema already 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+resource ('Search Torob for products') and immediately characterizes the result card (cheapest shop price in Toman, shop count), so the agent knows what comes back. It does not differentiate from siblings like tb_cheapest, tb_compare, or tb_suggest, which all retrieve product pricing data.

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 — this is the general entry-point search — and the note about weak matches plus `spellcheck`/`suggested_queries` gives implicit guidance to rephrase rather than retry blindly. However, there is no explicit when-to-use/when-not statement, and the routing hint to tb_sellers for city filtering lives only in the schema, not the description.

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 carry the safety profile (readOnly, idempotent, non-destructive, open-world), so the bar is lower, and the description still adds real value by decoding the response semantics: score/votes scale, what 'unreliable' means (bait or stale price), what buyer_notes contains, and that stats cover usable offers only. It omits pagination/truncation behavior and the meaning of 'cheapest first' when unreliable offers are included.

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 purpose and sort order are front-loaded in the first sentence, followed by a compact field glossary that earns its place. The backticked field list is dense and reads like documentation shorthand, but no sentence is redundant.

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 the necessary work of explaining the returned offer fields, which is the main completeness risk here. Remaining gaps (limit/output defaults, behavior when filters exclude everything, relationship to the toolbar siblings) are minor for a read-only listing tool whose annotations already cover safety.

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 75%, so the schema already documents city, product, min_score, warranty_only, installment_only, and include_unreliable; limit and output carry no description in either place. The description adds indirect meaning by explaining the score scale and the unreliable flag that min_score and include_unreliable operate on, but it never addresses city scoping, the limit cap of 50, or the json/csv choice.

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 resource and scope: every online shop offer for a given product, ordered cheapest first, plus what each offer carries (trust, warranty, installment, delivery). It stops short of naming any sibling (tb_offers, tb_cheapest, tb_compare, tb_stores) by contrast, so an agent must infer the boundary itself.

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 to pick where to buy' implies the selection scenario but names no alternative and no when-not condition among the many overlapping siblings (tb_cheapest, tb_best_value, tb_compare, tb_offers). The routing decision is left to inference.

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

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

Annotations already establish that this is a safe, idempotent, read-only lookup, so the description doesn't need to restate safety. It does add a genuine disclosure not present in structured fields: 'Contact details are left out,' telling the agent to expect a redacted view of the profile. It doesn't mention rate limits or whether the record can be missing, which keeps it below the top score.

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

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

Two short sentences with no filler. The content of the profile comes first and the usage instruction second, which is the right front-loading for a lookup tool.

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

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

With a single required parameter, no output schema, and full annotation coverage, the description is complete enough to call correctly. Since no output schema exists, the field enumeration stands in for a return-value description, though it doesn't indicate structure or absence behavior.

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 the shop_id property already documents its range and origin, so the schema carries the parameter burden. The description reinforces the tb_sellers linkage but adds no syntax or format details beyond that.

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?

Names the resource precisely and enumerates the profile contents (score and votes, e-Namad seal, time on Torob, city, website, delivery and payment terms), which tells an agent exactly what it gets back. It is a noun phrase rather than a verb, but the retrieval intent is unambiguous and clearly distinct from the list-oriented siblings like tb_sellers and tb_stores.

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 clause 'Use to vet a seller from tb_sellers' supplies both the use case (seller vetting) and the workflow dependency (obtain shop_id from tb_sellers first). It stops short of excluding alternatives such as tb_stores or tb_find_shops, so the routing guidance is clear but not exhaustive.

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, open-world and non-destructive, so the safety profile needs no restating. The description adds genuinely non-obvious semantics: prices shown are the cheapest across all shops, not this shop's asking price, which prevents a serious misinterpretation of results. It stops short of disclosing pagination limits or result ordering 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?

Two compact sentences, front-loaded with what the tool returns, with the pricing caveat in second position where it is most likely to be read. No filler, though the tb_sellers clause is compressed enough to be slightly ambiguous.

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 five-parameter, read-only listing tool with no output schema, the definition covers purpose and the key price-semantics caveat but omits pagination behavior, sort semantics, and any indication of result shape. An agent can call it correctly but may mis-set paging or sorting without guessing.

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 only 40%: query and shop_id are documented, but page, sort, and limit carry no descriptive text. The description does not compensate — nothing is said about the meaning of page, the four sort modes, or the limit cap, despite 'price range of the page' hinting at pagination without explaining it.

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 resource ('Products one shop sells on Torob') plus an attributed payload ('with the price range of the page'), so the verb and object are unambiguous. It also gestures at the boundary with tb_sellers, though the differentiation is phrased obliquely rather than as a direct 'use X instead'.

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?

Implicit usage is clear: call it with a shop_id to browse that shop's catalogue. The only routing hint is the remark that tb_sellers carries this shop's own offer, which nudges the agent away from using this tool for seller-level pricing, but there is no guidance on pagination strategy, sort choice, or when another sibling (tb_search, tb_stores, tb_shop) is a better fit.

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, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds real value beyond that by disclosing the shape of the result (cheapest price plus shop count per alternative), but says nothing about how many results come back, what the default limit implies, or what happens for a product with no similar items.

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 with no filler; the resource and returned fields come first. It is efficient and readable, though the parenthetical gloss could have been spent on usage routing instead.

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 lookup with annotations and no output schema, the description covers purpose and result fields adequately. It is incomplete on the one thing an agent must decide unaided: when to reach for this over tb_variants, tb_compare, or tb_cheapest, and how the limit affects 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 coverage is only 50%: the 'product' parameter is documented in-schema as a UUID or torob.com URL, but 'limit' carries no description beyond type and 1-50 bounds. The description mentions neither parameter, so it does not compensate for the undocumented limit or clarify whether the shop count/price apply per alternative.

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 the resource precisely: products that Torob classifies as similar, explicitly glossed as 'alternatives in the same class', and the returned fields (cheapest price, shop count). It is clear what the tool retrieves, though it never contrasts itself with nearby siblings such as tb_product, tb_variants, or tb_compare.

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?

There is no explicit when-to-use guidance and no named alternative. An agent must infer from the word 'similar' that this is the right call versus tb_variants (different variants of one product) or tb_compare (side-by-side comparison), with no help from the description.

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

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

Annotations already declare this a read-only, idempotent, non-destructive open-world query, so the safety profile is covered. The description adds value the annotations cannot: it discloses what each result carries, including freshness cues like opening hours and "open now" plus the age of the shelf price, which tells the agent the data is time-sensitive. It does not mention result volume or how the limit behaves, leaving a small 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?

Two compact sentences: the first front-loads what the tool returns, the second handles intent and redirection to the sibling. 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?

With four parameters, no output schema, and a physically-located-data scope, the description carries the right load by enumerating return fields and framing the use case. Missing pieces are minor: nothing about result ordering or how the limit interacts with the open-now framing.

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 75%, with city, product, and with_location documented inline, so the baseline is 3. The description adds no parameter-level detail — no syntax for the product identifier or city, no note on what with_location costs in response size. The undocumented limit parameter is bounded by schema min/max/default, so little is lost.

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 the resource and its scope precisely — physical shops stocking a given product — and enumerates the returned attributes (address, opening hours, open-now status, shelf price and price age). It explicitly contrasts with tb_sellers for online offers, so an agent can separate the two. It stops short of distinguishing itself from other shop-related siblings such as tb_find_shops, tb_shop, or tb_shop_products.

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

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

"Use for 'can I buy it today near me'" gives a concrete, recognisable intent that maps cleanly to the tool, and the trailing "Online offers: tb_sellers" routes the agent away when the intent is online-only. There are no explicit exclusions against the other shop/location siblings, so the guidance is clear but not exhaustive.

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). The description adds real behavioral context beyond that: a hard cap of 8 results and that it normalizes Finglish/colloquial input into canonical phrases, plus the availability note about blocked calls.

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

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

Two short sentences, zero filler, with the core capability front-loaded and the workflow hint second. Nothing is redundant or buried.

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-parameter read-only autocomplete tool with full schema coverage and rich annotations, the description supplies enough to call it correctly, including the result cap. Only the exact return shape (bare strings vs. structured suggestions) is left implicit, which is minor here.

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

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

Schema coverage is 100% with an example provided, so the baseline is 3. The parenthetical about fixing Finglish and colloquial wording adds meaning about what the 'text' parameter tolerates, which the schema's plain example does not convey.

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?

Names a specific verb+resource ('autocomplete: up to 8 search phrases for typed text') and adds scope details (max 8 results, Finglish/colloquial normalization). This clearly separates it from tb_search, which consumes the phrases rather than producing them.

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 tb_search' gives explicit sequencing guidance relative to the most likely alternative. It also notes it remains available while other calls are blocked. No explicit when-not-to-use condition is given, but the intended workflow 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 read-only, idempotent, non-destructive and open-world, so safety is covered. The description adds the return structure (category, sample product per trend), which is genuinely useful since no output schema exists, but says nothing about how many items come back or how the limit behaves.

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 efficient sentence with no filler, and the defining scope ('right now') is stated early. It is slightly under-specified rather than bloated, but nothing in it is wasted.

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, low-complexity read tool with no output schema, the description covers the return shape adequately and annotations cover safety. It is still missing any note on result volume defaults or ordering ('trending' order), which an agent might reasonably need.

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 one parameter with 0% schema description coverage, but its type, default of 10 and 1-30 bounds are fully expressed in the schema, so its meaning is unambiguous without prose. The description adds nothing about the limit, which is the only real gap.

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

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

The description names the resource precisely ('what people search on Torob right now') and discloses the payload shape (category plus one sample product), which sets it apart from siblings like tb_search and tb_suggest. It lacks an explicit verb such as 'list' or 'get', so it falls short of the 5 bar.

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?

'Right now' weakly implies a recency-based, non-query use case, but there is no explicit when-to-use statement and no mention of alternatives such as tb_suggest or tb_search despite many closely related siblings.

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. The description adds one genuinely useful behavioral fact — that pricing is per-variant and cheapest-per-variant — but says nothing about how many variants come back, ordering, or whether all configurations or only priced ones are returned.

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?

One compact sentence that front-loads the core idea (sibling variants) and then the pricing detail. Nothing is redundant; the only weakness is that the fragmentary phrasing takes a moment longer to parse than a verb-led sentence would.

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 one-parameter, read-only lookup with full schema coverage and rich annotations, the description covers what the tool returns well enough to call it correctly. Without an output schema, a brief note on result shape or variant count would have closed the last 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 coverage is 100% for the single product parameter, and the schema already explains that it accepts a UUID or a torob.com URL plus its length bounds. The description adds no further meaning about the identifier, which is acceptable but adds nothing beyond the structured field.

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 identifies the resource (sibling variants of a given product) and the key payload (each variant's cheapest price), which is enough to tell it apart from tb_product or tb_price_history. It is a noun phrase rather than a verb-led statement, and it never distinguishes itself from the close neighbour tb_similar, 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?

There is no guidance on when to call this instead of tb_product, tb_similar, tb_cheapest, or tb_compare. The agent must infer from the name alone that this is the right tool when it wants variant-level pricing rather than a single product's data.

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