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

Annotations already cover the safety profile (readOnly, idempotent, openWorld, non-destructive), so the bar is lower, and the description adds real value beyond them: each name resolves to its top search match unless an exact id is passed, and the call 'costs up to 2 requests per item'. It does not say what happens when no single shop carries every item, which is the main remaining 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?

Front-loaded: the first sentence delivers the whole purpose and the two result shapes, then a short second block explains resolution and cost. It is tight overall, with only minor density issues from the inline backtick references.

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 explaining both returned structures and the per-item resolution field. Given five parameters and an open-world search backend, it is nearly complete; the missing piece is behavior when the list cannot be fulfilled by one shop or by any shop.

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. The description adds useful semantics for `items` (fuzzy name resolution vs exact ids, and that resolution is surfaced in `items[].name`), but says nothing about `min_score`, the one parameter left blank in the schema, nor adds detail to `city`/`condition`/`installment_only`.

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 verb and resource — it computes the cheapest basket for a whole shopping list — and names the two outputs (`single_shop`, `split_cart`). It is distinguishable from single-item siblings like tb_cheapest or tb_compare by the multi-item scope, though it never names an alternative tool to sharpen the boundary.

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 context is implied: this is for buying a multi-item list and weighing one delivery against the cheapest per-item split. There is no explicit when-to-use versus tb_cheapest/tb_compare/tb_best_value guidance and no exclusions, so the agent must infer the fit from the scope alone.

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/open-world, but the description adds real behavioral context: ranking is by price reach/popularity/cheapness because Torob has no quality score, only in-stock products with at least `min_shops` shops are returned, and it explains the `budget_used_pct` computed value. It stops short of describing output shape or pagination.

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 front-loaded sentences with no filler; the core purpose leads and caveats follow. Fairly dense with parenthetical asides but each sentence carries information, so 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?

With 86% schema coverage, no output schema, and full annotations, the description fills the remaining gaps: ranking rationale, in-stock/min_shops constraint, and sibling handoff to tb_compare. A brief note on return shape would make it fully self-sufficient.

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 86%, so the enum semantics for rank_by, condition, and min_shops are already documented in the schema. The description largely restates these ("at least `min_shops` shops") and adds little new parameter meaning beyond the structured data, so the baseline 3 applies.

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

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

States a concrete verb+resource (rank product picks under a budget) and anchors it with an example query ("best phone under 30 million"). It also routes to tb_compare for spec checking, but does not explicitly distinguish itself from sibling listers 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?

The example query gives a clear when-to-use scenario (budget-constrained "best X under Y" shopping), and it tells the agent to follow up in tb_compare to check specs. No exclusions or explicit comparison against the search/cheapest siblings are given.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds only the workflow hint that returned ids feed tb_search's brand= parameter; it says nothing about pagination behavior or result ordering, which is a modest addition over 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?

Two short sentences with zero filler; the scoping statement comes first and the routing guidance second. Both sentences carry distinct information.

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

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

With no output schema, the description does state the return contents (brands plus ids), which is the key detail for a lookup tool. It omits pagination/limit behavior and what happens when a category has no brands, leaving a small but real 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 67%: 'category' and 'search' are documented in the schema, while 'limit' (default 60, max 100) is undocumented in both places. The description adds cross-tool meaning for the returned ids but no syntax or semantics for the parameters themselves, so the baseline 3 applies.

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

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

States a specific resource and scope: all brands of a given category, returned with their ids. It also names the sibling relationship explicitly (tb_search brand=), so an agent can distinguish it from tb_search without opening either 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 a clear trigger condition ('Use when you know the category and need a brand id') and immediately notes the alternative path ('tb_search also accepts the brand name directly'), which effectively tells the agent when this tool is unnecessary.

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 safety profile is covered. The description adds real behavioral value beyond them: 'parents and children come with each reply' and the disclosed limitation that Torob has no tree endpoint so per-sub-category counts are unavailable, which prevents an agent from expecting aggregate counts.

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

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

Two short sentences with the parenthetical caveat attached to the relevant clause; the resource definition is front-loaded before usage guidance. Every sentence earns its place.

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

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

With no output schema, the description usefully states what a reply contains (parents, children, top products) and where a limitation exists. It stops short of covering paging behavior for the 'page' parameter, but the agent has enough to call the 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 83%, so sort, brand, limit, category, and max_price are already documented in the schema; the description only alludes to the category parameter via the tb_search(category=) reference. No additional syntax, format, or interaction detail is added, so the baseline 3 applies.

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

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

The description names a specific resource (a category page) and enumerates exactly what it contains: tree position, sub-categories, and top products. It also distinguishes itself from the closest sibling by pointing at tb_search(category=) for in-category text 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?

It gives two explicit use cases (walk the category tree; list a category's products) and names the alternative plus the condition that selects it: 'For text search inside a category use tb_search(category=).' Nothing 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 cover read-only/idempotent/non-destructive, so the bar is lower, yet the description adds real behavior: it skips unreliable and out-of-stock offers, examines top `candidates` matches rather than the lowest card price, and discloses request cost ('1 + candidates requests'). It also flags a failure mode (mismatched product name) that no structured field captures.

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?

Short and front-loaded: purpose first, then the usage trigger, then mechanism and cost caveat. Every sentence carries information. Slightly fragmented by line breaks and the abrupt final cost sentence, but 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 6-parameter tool with no output schema, the description does the needed work: it explains what is returned (best offer per match plus the overall cheapest), the filtering policy, and the cost. It is close to complete; only alternative-tool routing and result-format details (e.g. fields per offer) are absent.

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

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

Schema description coverage is 100%, so baseline is 3. The description's only added parameter meaning is the cost consequence of `candidates` ('Costs 1 + candidates requests'), which the schema already partially implies with 'one request each'. It adds little beyond the schema for city, condition, min_score, or installment_only.

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 resource and mechanism — 'Cheapest trustworthy offer for a product named in words: searches, then looks at every shop's offer.' The phrase 'named in words' implicitly distinguishes it from URL-based siblings like tb_product_url, and the two-stage 'searches, then looks at every offer' differentiates it from a plain search tool.

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 "where is X cheapest"' gives an explicit trigger condition. It also warns to verify the matched product name. However, it never names alternatives (e.g. tb_best_value, tb_compare, tb_offers), so the agent must infer routing among several price-comparison 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 readOnly, idempotent, non-destructive and open-world, so the safety profile is covered. The description adds value the annotations don't: concrete id mappings (392 Tehran, 468 Mashhad, 240 Isfahan) and the behavioral difference between the search and non-search paths. It says nothing about ordering, pagination or empty-result behavior.

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

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

Two dense sentences with zero filler; the consumption context is front-loaded and the mode switch follows. Every clause carries information.

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

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

With no output schema, the description usefully signals that responses are city id/name pairs via the inline examples, and explains both modes. The only real gap is the undocumented `limit` behavior and result ordering for the browse mode.

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 50% — `search` is documented in the schema, `limit` is not. The description compensates by making the search/no-search branch semantics explicit and by hinting at the default listing behavior, though the `limit` parameter remains unaddressed.

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 resource (city ids) and its exact role: the `city` filter for tb_search, tb_sellers and tb_stores. It also names which siblings consume these ids, so the agent can place the tool in the 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?

Explains the two invocation modes clearly: with `search` it resolves a name to a city, without it returns the most visited cities. It also names the downstream tools that need these ids. It stops short of an explicit 'call this before X' instruction or any exclusion, so it's strong context rather than complete 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 cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower, yet the description still adds substantive behavior: the shape of `differences`, the null-means-nothing-listed convention, the meaning of `cheapest`, and the 'One request per product' operational constraint. This is useful disclosure beyond the annotations.

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

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

Front-loaded purpose sentence, then usage, then field semantics, with no filler. The trailing 'One request per product' is slightly cryptic in isolation but still earns its place as an operational 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?

With no output schema, the description carries the return-value burden and does so adequately, explaining `differences`, `cheapest`, and the price window. A little more detail on the price-window fields would make it fully complete, but nothing essential for calling the tool 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 there is a single parameter, so the schema already fully documents `products`. The description's only added semantics are the ordering guarantee tying `differences` values to the order of `products`; otherwise the baseline 3 applies.

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

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

States a specific verb and resource ('Side-by-side comparison of 2-5 products') and enumerates exactly what is returned: differing specs, price window, cheapest flag. It is clearly distinct from a single-product tool like tb_product, though it does not distinguish itself from the semantically adjacent tb_cheapest / tb_best_value siblings.

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

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

'Use after tb_search / tb_similar to choose between models' gives an explicit workflow position and names the tools that precede it. It does not state when NOT to use it versus tb_cheapest or tb_best_value, so it stops short of full alternative routing.

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/open-world/non-destructive, and the description adds genuinely new behavior: the explicit cost of 2 requests, the internal sources it calls (chart + sellers), the scoring heuristic, and the `reasons` output field. That is well beyond what the annotations declare.

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

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

Front-loaded with the purpose and result before any methodology, and each sentence earns its place (bands, cost, reasons field). The heuristic paragraph is dense but justified since it explains how to interpret the output; only the '(documented, not Torob's)' aside borders on expendable.

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

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

With no output schema, the description carries the return-value burden and does cover the score scale, the `reasons` field, and the request cost. It stops short of enumerating the full response shape, but for a read-only scoring tool this is nearly complete.

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 baseline is 3, but the description adds real meaning: it explains how the price input is used (percentile against the past year's weekly minimums, penalty when above today's cheapest usable offer) and confirms the default. This clarifies the parameter's role in the algorithm, not just its format.

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

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

Opens with a specific question ('Is this a good price?') and states exactly what it produces: a 0-100 score derived from price history and today's offers. This clearly separates it from data-returning siblings like tb_price_chart or tb_price_history, which report numbers rather than render a verdict.

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 framing question plus the score bands (70+ good deal, 40-69 fair, below 40 wait or shop around) make the intended use case and interpretation clear. However, it never names a sibling as an alternative or states when-not to use it (e.g. vs tb_cheapest or tb_best_value), so an agent must infer the routing.

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 bar is lower. The description still adds real behavioral context the annotations cannot: a query or category is required in practice (both schema params are optional), and brand coverage is only exhaustive once a category is known — an important completeness caveat for the agent's downstream filtering.

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

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

Two short blocks, zero filler: the return surface is front-loaded, then the usage rule and the completeness caveat. Nothing is repeated from the schema and no sentence is decorative.

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 work of describing the return shape (the list of filter dimensions), and it warns about incomplete brand data without a category. The one residual ambiguity is what happens if neither optional parameter is supplied, which is left unspecified.

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 a 3 is the baseline. The description earns above baseline by stating the at-least-one-of relationship between the two optional parameters — an invariant the schema does not enforce — and by tying `query`/`category` to concrete downstream uses (category id, brand id, attribute slugs).

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 first sentence names the resource (search filters) and enumerates exactly what it returns: category children, brands, price span, sort options, attributes. That is specific enough to separate it from tb_search, though it does not acknowledge the overlap with siblings like tb_category and tb_brands, which also surface some of this 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?

"Use before tb_search when you need a category id, a brand id, or the exact attribute slugs and values" gives an explicit sequencing rule and trigger conditions. What is missing is any exclusion — nothing tells the agent when to call tb_category or tb_brands instead of this tool.

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 fully cover the safety profile (readOnly, idempotent, non-destructive, openWorld). The description goes beyond them by disclosing the informally-sourced directory endpoint and the tolerant parsing of its reply, which warns the agent that fields may be missing. It also names the returned fields (id, name, city, score), valuable given 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?

Two tight sentences, purpose front-loaded, with the implementation caveat and return fields placed second. The second sentence is slightly meta but earns its place by disclosing fragility and return shape. 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 5-parameter search tool with no output schema, the description covers the purpose and partial return shape but omits pagination behavior and result-count semantics, which an agent needs to iterate results correctly. Adequate but with a clear 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 60%: city, kind, and query are described in-schema, but page and limit have no descriptions anywhere. The description adds nothing about pagination or the max 30/50 bounds, so it does not compensate for the coverage gap. Baseline 3 for a moderately documented schema.

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

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

States a specific verb and resource (find shops by name or domain) and even names the downstream consumers (tb_shop, tb_shop_products), which helps an agent place it in a workflow. It stops short of distinguishing itself from plausible siblings like tb_stores or tb_shop, which also deal with shops.

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 implies the usage pattern (resolve a shop name/domain to an id before calling tb_shop), but never states when to choose this over tb_stores, tb_sellers, or a plain search. No exclusions or prerequisites are given.

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

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

Annotations already declare readOnly, idempotent, non-destructive and openWorld, so safety is covered. The description adds genuinely non-annotation behavior: the result is organized into themed rows, each with a theme title and product cards, which tells the agent what the payload looks like. It doesn't mention pagination limits, but the schema already carries those.

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 lines: identity/native name first, use case second, follow-up tools third. No filler and the most distinguishing information is front-loaded.

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

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

With no output schema, the description usefully sketches the return shape (rows with titles and product cards) and the chaining path. Combined with fully documented parameters, an agent has enough to call and consume this tool; only explicit pagination/volume guidance is absent from the prose.

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

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

Schema description coverage is 100% and all three parameters (page, size, limit) are documented with defaults, ranges and even the reason for small sizes. The description adds nothing about parameters, so the baseline 3 is correct.

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

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

The description names the specific resource (Torob's special-offers feed, native term 'پیشنهاد ویژه') and its shape: themed rows of discounted or promoted products. That is far more concrete than a generic 'get offers', and it implicitly separates it from tb_search/tb_deal_check, though it never names a sibling 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?

'Use for "what is on sale"' gives a clear use context, and 'Follow with tb_product / tb_sellers' supplies an explicit next-step chain. It stops short of naming alternatives or when-not-to-use cases (e.g., versus tb_deal_check or tb_cheapest).

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 a cost/latency signal ("one cheap call") that is genuinely beyond the annotations, but says nothing about return shape or pagination. With annotations carrying the behavioral load, a 3 is fitting.

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 resource and its dimensions, with the routing hint second. 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 simple read-only, single-parameter tool, the description plus annotations cover purpose, dimensions, and when to use it. The only gap is that, absent an output schema, the precise return structure is only hinted at via "price window" rather than stated.

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?

Only one parameter and schema description coverage is 100%, so the schema already documents the accepted product id/path/URL formats. The description adds no parameter detail beyond that, which is the expected baseline when the schema does the work.

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 resource (a product's shop presence) and enumerates exactly what it measures: online shops, in-person stores, installment shops, Torob-warranty shops, and price window. This is clearly distinguishable from siblings like tb_sellers and tb_stores, which it names.

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 when (judge availability first) and names the alternatives to use for deeper digging (tb_sellers, tb_stores). The routing decision is stated outright rather than left to inference.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, open-world), and the description adds real operational context: the ~1-year weekly data window, Toman pricing, ISO dates converted from Jalali, and how the verdict is derived. It stops short of any rate-limit, auth, or pagination guidance, so not a full 5.

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

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

Front-loads what the tool returns, then interpretation rules, then sibling routing — a sensible order with no filler sentences. The line break inside the verdict paragraph is slightly awkward but costs nothing.

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

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

There is no output schema, so the description carries the burden of explaining returns, and it does: min/average price, the great/fair/high verdict values, and the percentile scale where 0 means cheapest. An agent can both call and interpret the result correctly.

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

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

Schema coverage is 100%, so both `points` and `product` are already documented, including the default of 26 and the ~52-point cap. The description's "about a year, weekly" adds only loose framing and doesn't explain what a smaller `points` value does to the verdict window, so the baseline 3 is correct.

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

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

States a specific resource (product price chart), its scope (~1 year, weekly), and exactly what it returns: minimum and average price in Toman plus a buy-now verdict. It also distinguishes itself from tb_price_history and tb_deal_check by name, so an agent can route without opening schemas.

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 selection condition ("Use to see if now is a good time") and names two alternatives with the conditions that select them: tb_price_history for notable moves only, tb_deal_check for a full buying decision. Nothing 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 declare readOnly/idempotent/non-destructive/openWorld, and the description adds behavior beyond that: data provenance (weekly minimum series, Torob's own event feed deliberately not used), the per-week-not-per-day granularity caveat, currency (Toman), and result ordering. It does not cover pagination or rate limits, but the added context is substantive.

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

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

Front-loaded with the resource and its ordering, then the provenance caveat, then the use case. Slightly over-explained in the parenthetical about which feed is not used, but every sentence carries real information for an agent.

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

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

With no output schema, the description carries the return-value burden and largely does so by enumerating the event types and ordering, plus stating the currency. Remaining gaps are the shape of returned fields and how 'limit' truncates results, which are minor for a read-only list 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%: 'product' and 'min_change_pct' are documented in the schema, while 'limit' is not. The description adds no parameter-level detail (no mention of limit behavior or accepted product identifier forms), so this sits at the baseline where the schema does the heavy lifting.

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

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

Specific verb+resource: it lists exactly what is returned (drops, rises, lowest/highest point, last change) and in what order (newest first). It also implicitly differentiates itself from the sibling tb_price_chart by stating the data is derived from the chart's weekly minimum series and is therefore per-week, not per-day — enough for an agent to tell the two apart.

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

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

It gives a concrete triggering question ('did the price just drop') and constrains the interpretation (weekly granularity, so it is unsuitable for same-day detection). It does not explicitly name an alternative tool or state when NOT to use it, so it stops 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 adds genuine data-semantics context beyond them: price_min/price_max span all offers including unreliable ones, while cheapest_offer is the cheapest *usable* offer among those embedded in the page — a distinction that matters for interpreting results. It doesn't mention rate limits or cost, which keeps 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?

Front-loads the return contents, then routing, then the price-field caveat. No filler sentences; each clause either defines scope, routes to a sibling, or disambiguates a field.

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 the description must describe returns — and it does, naming the fields and clarifying the price semantics. With 2 params at 100% schema coverage and annotations covering safety, nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100% and both parameters (product with min/max length and accepted id formats, full_specs boolean) are already documented in the schema. The description's price-field detail actually explains response fields, not parameters, so it adds little parameter-level meaning. Baseline 3 applies.

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

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

States a specific verb+resource ('Full record of one product') and enumerates the returned fields: name, price range across shops in Toman, category path, brand, key specs, cheapest offer. An agent can distinguish this from tb_search or tb_sellers purely from the description.

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 says 'Use after tb_search' and names three alternatives with their selecting conditions: tb_sellers for per-shop prices, tb_deal_check for a buying decision, tb_compare for model comparison. Both when-to-use and when-to-use-something-else are covered.

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/non-destructive, but the description adds real behavior the agent cannot get elsewhere: there is no upstream batch endpoint, so this issues one spaced-out request per product (latency/rate-limit implication), and individual failures land in `errors` without aborting the rest. That partial-failure contract is exactly the kind of context annotations cannot express.

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: the first front-loads what comes back, the second front-loads when to use it and then the failure semantics. No filler, no repetition of the schema.

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

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

With no output schema, the description usefully discloses one return key (`errors`) and the per-item fan-out behavior, which is the main thing an agent needs for a batch call. It stops short of describing the success payload shape or whether ordering matches the input list, which matters for a 10-item batch.

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 `products` array is already documented down to accepted formats (UUID, /p/<id>/ path, full URL) and 1-10 bounds. The description only echoes the max-of-10 limit, adding negligible meaning beyond the schema, so the baseline 3 applies.

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

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

States a specific resource and scope ('Short records ... for up to 10 products at once') plus the returned fields (name, price window, shop counts, category, brand), which is far more specific than a bare name restatement. It doesn't name the single-product sibling tb_product or otherwise differentiate itself from the other product-shaped tools in the list, 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?

'Use to refresh a list of known ids' gives a clear selection condition: many ids, already known. However, it never states the inverse (use tb_product for one id, use tb_search when ids are not known) or any exclusions, so the agent must infer the boundary against 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 readOnly, idempotent and non-destructive, but the description adds real behavioral context beyond them: no request is sent, and Torob redirects the result to the canonical page carrying the product name. That is meaningful for deciding how to present the output.

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, both front-loaded with substance: the first defines the operation and inputs, the second defines the use case and result behavior. 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 one-parameter, no-output-schema utility, the description covers input forms, side-effect profile (no request) and the user-facing result (redirect to canonical page). Nothing an agent needs in order to call it correctly is missing.

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

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

Schema description coverage is 100%, so the single 'product' parameter is already fully documented. The description's list of accepted input shapes mirrors the schema rather than adding format or validity rules, so it earns the baseline 3.

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 operation (build/clean a torob.com product URL) on a specific resource (product), and identifies the three accepted input forms. The note that 'no request is sent' sharply distinguishes it from request-performing siblings like tb_product 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?

'Use to hand the user a link' gives a clear use context that an agent can act on, and the accompanying redirect note explains what the user will see. It stops short of naming an explicit alternative or a when-not condition, so it is 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 cover safety (readOnly, idempotent, non-destructive, openWorld), yet the description adds substantial behavioral detail beyond them: `price` null when no listing, `low_confidence`/`unmatched_terms` on weak matches, spellcheck/suggested_queries for rephrasing, `count` capped at 1200 with `count_capped`, `ad` marking sponsored cards, and that min/max_price span the unfiltered result. This is rich disclosure that annotations alone would not convey.

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

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

Front-loaded with purpose and return shape before the routing list, and every sentence carries information (return unit, alternatives, edge cases). It is dense — the parenthetical sibling list packs several tools into one clause — but not padded, so it stays efficient without being sparse.

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 15 params, no output schema, and a complex open-world search tool, the description covers the missing pieces: what a card contains, the product-vs-offer distinction, price-null and low-confidence semantics, and the count cap. An agent has everything needed to call it correctly and interpret the result.

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

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

Schema description coverage is 100%, so the schema already documents all 15 parameters (city, filters, brand, condition, etc.) with examples and constraints. The description adds only the caveat that min/max_price in the reply span the unfiltered result, which is marginal beyond the schema. Baseline 3 is appropriate.

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

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

States a specific verb+resource ('Search Torob for products') and immediately specifies the unit of return ('cards are products, one per model/variant, not shop offers'). It explicitly distinguishes itself from sibling tools like tb_sellers and tb_offers, so an agent can route 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?

'Use first for any "find / how much is X" question' gives an explicit entry-point rule, and the 'Next:' clause names the alternatives (tb_sellers for all offers, tb_cheapest for the best offer, tb_product for specs) with the condition that selects each. This is a complete when/when-not map.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the bar is lower, yet the description still adds real behavior: "Torob returns all offers at once; limit slices them" reveals a fetch-then-truncate pattern, and it defines `unreliable` (bait/stale) and clarifies that `stats` are computed over usable offers only. It stops short of stating rate limits, auth needs, or failure modes for a bad 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?

Purpose and ordering are front-loaded in the first sentence, followed by usage, a field glossary, and parameter notes — a sensible order with no filler. It is dense and runs long, but the field glossary is doing necessary work because there is no output schema, so almost every clause 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 must explain the return shape, and it does so field by field (price in Toman, null when out of stock, score/votes, flags, updated, stats with min/median/max and price_spread_pct). Combined with 100% parameter documentation and 8 params, an agent has everything needed to call and interpret this tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3 and the schema already carries city, limit, min_score and the boolean filters. The description still adds meaning the schema cannot: the default hiding of unreliable offers, that `city` selects shops serving that city, and above all that `limit` slices a full upstream result set rather than constraining the query.

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 first sentence states a specific resource (every online shop offer for a product) with an explicit ordering rule (cheapest first) and the extra data attached (trust, warranty, installment, delivery). An agent immediately knows this is a per-product offer listing. It does not, however, name or differentiate itself from close siblings such as tb_offers, tb_cheapest or tb_compare, so the reader must infer the boundary.

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" gives an implied use case (buy-decision comparison), which is genuine guidance but not a when/when-not rule. No alternative tool is named for the adjacent jobs (single cheapest price, side-by-side compare, deal checking) despite several siblings clearly overlapping. Usage is inferable rather than specified.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the bar is lower. The description nonetheless adds real behavioral context: it discloses that contact details are deliberately omitted and warns that shop-written text is data, not instructions, which is useful for prompt-injection handling. No return format is given, but with annotations carrying the safety profile this is solid.

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: the resource and its fields are front-loaded, the usage condition follows, and the privacy/injection notes close. Every sentence carries distinct information with no padding.

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

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

For a single-param read tool with no output schema, the description compensates by enumerating the returned fields and calling out what is deliberately excluded. Combined with annotations, an agent has enough to invoke it correctly without further inference.

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

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

Schema description coverage is 100% and the single parameter is fully documented in the schema itself, including the tb_sellers source and an example value. The description only restates that the id comes from a tb_sellers row, adding no new syntax or constraint beyond the schema, so the baseline 3 applies.

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

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

The description names a concrete resource (a shop's trust profile) and enumerates exactly what it contains: score and votes, e-Namad seal, time on Torob, city, website, delivery and payment terms. It ties itself to tb_sellers as the source of the id, which implicitly separates it from product/search siblings. It stops short of an explicit verb and doesn't name which siblings it is not, so a 4 rather than 5.

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

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

It states a clear context for use: 'Use to judge a seller found in tb_sellers (its `shop_id`) before buying,' which tells the agent both when and where the id comes from. There are no explicit exclusions or named alternatives, so it falls short of a 5.

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

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

Annotations already cover the safety profile (readOnly, idempotent, openWorld, non-destructive), so the bar is lower. The description adds genuine behavioral context beyond them: the card price is the cheapest across all shops rather than this shop's own, and the endpoint is scraped from site code with a tolerantly parsed reply, which sets expectations about data fidelity.

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?

Short, front-loaded, and every clause carries information: scope, prerequisite, price caveat, and the alternative route. Only the trailing note about the endpoint source is slightly tangential, but it still earns its place as a reliability signal.

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 work of explaining card semantics (cheapest across shops) and data-quality expectations. It leaves pagination behavior to the schema's page/limit constraints, which is acceptable for a read-only list tool.

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

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

Schema coverage is 60%: sort, query, and shop_id are described in the schema, while page and limit carry only min/max/default constraints. The description adds no parameter detail beyond an implicit nod to 'the page', so it neither compensates for the gap nor duplicates the schema.

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

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

States a specific resource and scope: 'Products one shop sells on Torob, with the price range of the page.' It is immediately distinguishable from tb_shop (which finds shops) and tb_sellers (which handles the shop's own offer), and the price-range clause clarifies the return shape.

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 orders usage ('Use after tb_shop') and routes the agent to an alternative when a different need arises ('call tb_sellers on a product for the shop's offer'). The condition selecting each sibling is stated, not inferred.

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

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

Annotations already cover read-only, idempotent, non-destructive, open-world behavior, and the description adds a genuinely new trait: Torob ignores page size, so truncation happens locally at `limit`. That is useful, but other behavior (whether an unknown/redirected product id errors or returns empty, ordering of the similar list) is left 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?

Four short sentences, each carrying distinct information: what is returned, when to use it, a non-obvious truncation caveat, and the next-step tool. Front-loaded and waste-free.

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 full schema coverage on inputs, the description supplies the missing return-shape hint (cheapest price, shop count) and the limit caveat, which is enough to call the tool correctly. Remaining gaps (result ordering, empty-result behavior) are minor for a simple 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 coverage is 100%, so baseline is 3, and the description earns a bump by explaining that `limit` is applied locally because the upstream source ignores page size — context the schema does not convey. It says nothing about the `product` parameter, but the schema documents accepted id/path/URL forms thoroughly. Note the schema's own default value (10) conflicts with its property text ('default 15'), which the description does not resolve.

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 specific resource ('Products Torob shows as similar') and what each row carries (cheapest price, shop count), which is more than a restatement of the name. It does not explicitly contrast with the closest retrieval siblings like tb_product or tb_variants, so sibling differentiation is only partial.

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 use case ('Use for "what else is like this"') and routes follow-up work to tb_compare. It stops short of stating when NOT to use it (e.g. vs tb_variants or tb_products_batch), but the intended context is clear.

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 bar is low. The description adds real value beyond them: shelf prices are shop-set and can be stale, with the `price_updated` field as the staleness marker, and that city filtering happens server-side on Torob.

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

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

Front-loaded with the resource definition first, then the usage trigger, then the tool routing. Three tight blocks with no filler; the parenthetical field list is dense but earns its place as a return-value preview.

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

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

With no output schema, the description carries the burden and does so: it lists the returned fields (address, hours, open-now, shelf price and age) and discloses the price-staleness caveat. Nothing an agent needs to call or interpret this tool 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 baseline is 3, but the description adds meaning the schema does not: `city` narrows results server-side to a single city, and `price_updated` contextualizes the returned price age. This is genuine incremental semantic value over the schema text.

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

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

Names the specific resource ('in-person (offline) shops that stock a product') and enumerates the payload fields, giving an agent a precise picture of what it returns. It explicitly separates itself from tb_sellers for online offers and from the shop-lookup siblings.

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

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

Gives a concrete user-intent trigger ('can I buy it today near me') and names the alternative tool (tb_sellers) for online offers, plus notes the city scoping behavior. It lacks an explicit 'do not use when' beyond the online/offline split, but the routing is clear.

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

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

Annotations already declare readOnly, idempotent, non-destructive and openWorld, so the safety profile is covered. The description adds genuinely new behavioral context: a bounded result set (up to 8), Finglish/colloquial normalization, and the absence of Torob-side rate limiting. Missing only response shape/pagination detail.

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 the identity and result bound, then the routing guidance and the rate-limit caveat. No filler; every clause carries information.

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

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

For a single-parameter read-only lookup with no output schema, the description covers purpose, return size, input tolerance, sibling routing, and availability. Nothing an agent needs to invoke it correctly is absent.

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 already documents the single 'text' parameter with examples, so the baseline is 3. The description adds meaning beyond the schema by noting the input tolerates Finglish and colloquial wording, clarifying acceptable input forms.

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 ('autocomplete: up to 8 search phrases for the typed text') and explicitly scopes it as a pre-search phrasing lookup, distinguishing it from tb_search. An agent can tell exactly what it returns 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?

Names the downstream alternative and the condition that selects this tool ('before tb_search'), and adds a concrete usage window ('works while other calls are blocked'). No explicit when-not-to-use case, so it falls just short of a 5.

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

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

Annotations already declare readOnly/idempotent/non-destructive safety, so the bar is low. The description adds value beyond them by disclosing freshness ('right now') and the per-entry return shape (category and a sample product), which the annotations never convey.

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, lead sentence states the payload, second states usage and follow-up. No filler; every clause 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?

For a zero-required-param read tool with no output schema, the description covers intent, return fields, and the chaining pattern. It could note ordering/stability of the trend list, but nothing essential for correct invocation is missing.

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

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

Schema description coverage is 100% and the single limit parameter is fully documented with default and bounds, so the baseline is 3. The description adds nothing about limit semantics (e.g. ordering or what happens at max 30).

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 (search trends on Torob) and the payload shape (category + one sample product), which is more than a restatement of the name. It does not explicitly distinguish itself from tb_suggest, which plausibly also surfaces queries, 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?

Gives an explicit trigger ('what is trending') and a concrete workflow ('to pick a query'), plus the chaining target tb_search(query=...). No when-not-to-use guidance versus tb_suggest or tb_search itself.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds real behavioral value the annotations don't: the result set is variants each priced at their cheapest, and the returned option `id` is designed to be chained into other tools.

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 resource and its payoff, then the usage and chaining instruction. Zero filler.

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

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

With no output schema, the description carries the return-value burden and does partially cover it (variants, cheapest price, reusable option ids). It still doesn't sketch the response fields beyond variant attributes and price, leaving a small gap for a multi-variant list 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?

The single `product` parameter is fully documented in the schema at 100% coverage, including accepted id/path/URL forms. The description adds nothing about the input parameter—its 'id' mention refers to returned option ids, not the input—so the baseline 3 applies.

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

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

States a specific resource (product variants) and the distinguishing attribute set (storage+RAM, colour, region) plus what each carries (its own cheapest price). An agent can tell it apart from tb_offers, tb_compare, or tb_product 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 a concrete question it answers ('what does the 512 GB version cost') and an explicit follow-up: pass an option's `id` to the other tools. It lacks any when-not or named alternative sibling, so it stops 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.