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 mode-dependent output context (landings/promotion pages linked from home page vs carousels with a few products and links), which is useful beyond the annotations, though it does not mention rate limits 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?

The purpose is front-loaded in the first line, followed by two tightly scoped bullets for each mode and a single routing sentence. Every sentence earns its place with no filler.

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

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

An output schema exists so return-value detail is not required, and both params are schema-covered. The description covers both invocation modes and the sibling hand-off, leaving only minor gaps such as pagination or limits for large campaign lists.

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 (code, products_per_section) are already fully documented in the schema. The description's mode split largely restates what the schema says about omitting 'code', so it adds little beyond the baseline.

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

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

The description gives a specific verb and resource ('List current campaigns, or show one campaign's sections and products') and splits the tool into two clear modes keyed on the presence of 'code'. It distinguishes itself from tl_category_products by routing product listing there, though it does not explicitly differentiate from nearby siblings like tl_deals or tl_categories.

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 explicitly when to use each mode ('Without code' vs 'With code') and names the alternative tool (tl_category_products) with the condition that selects it, including a caveat that products_in_carousel counts only the carousel, not the page. Nothing about selection 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, openWorld, and non-destructive, so safety behavior is covered. The description adds one useful trait: with neither input only top-level categories and child titles are returned (no urls), and it does not say what happens if both url and query are supplied. No contradiction with 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?

Three one-line bullets after a single-sentence purpose statement, front-loaded with the primary use case (query for urls) and no filler. Every line carries distinct routing 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?

Return values are covered by the existing output schema, and the description fully explains the three input modes, so an agent can call it correctly in the common cases. The only gap is undefined behavior when both optional params are provided simultaneously.

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 examples for both params, so the baseline is 3; the description goes beyond by explaining the behavioral meaning of each param's presence/absence and treating them as mode selectors rather than independent filters. It still doesn't state precedence when both are passed.

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

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

Opens with a specific verb and resource ('Find category pages and their urls') and names the sibling tool it feeds (tl_category_products), so the agent knows this is the category-navigation entry point rather than a product/search tool. The three input modes are enumerated up front.

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

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

Explicitly routes the caller: use query to match categories by name ('best way to get a url'), use url to list a category's sub-pages, and use neither for the top-level tree. This is a near-complete when-to-use map for a 2-parameter optional-input 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 already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered structurally. The description adds value by explaining what the returned codes are for and that they feed a downstream filtering call, which is genuinely useful behavioral context 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?

Two sentences, zero filler. The purpose is front-loaded and the usage guidance follows immediately, with the filter-code mappings packed into a single efficient clause.

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?

An output schema exists, so return values need not be explained. The description covers purpose, sequencing with the sibling, and what the output codes are used for — everything an agent needs to call it correctly.

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

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

Schema description coverage is 100% and the url parameter is fully documented with a pattern and examples, so the schema does the heavy lifting. The description implies the url points at a category/brand/promotion page but adds no syntax or format detail beyond what the schema already provides, so 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 verb and resource ('List the filters of a category, brand or promotion page') and enumerates exactly what those filters contain (brands, categories, price range, attributes). It names the sibling tl_category_products and positions itself relative to it, so an agent can distinguish the two 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?

Explicitly states 'Use before tl_category_products' and maps each filter type to the code argument it enables (brand_codes, category_codes, attribute_codes). This is a clear when-to-use plus alternative/sequencing, leaving nothing 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 readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds the two-step workflow dependency on tl_category_filters and notes what each result carries, but says nothing about rate limits, result caps across pages, or how the re-sorted price ordering behaves beyond what the schema already states.

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

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

Two compact sentences, front-loaded with the core capability, followed by usage and the prerequisite/alternative routing. No filler or restated name/title content.

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 11 parameters fully covered by the schema and an output schema present, the description does not need to explain return values. It supplies the missing pieces an agent needs: the prerequisite call for filter codes and the free-text alternative, which is complete for this tool's complexity.

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 (url, page, sort, limit, in_stock, price bounds, brand/category/attribute codes) is already documented in the schema with examples. The description only alludes to 'filters' generically and adds no syntax or provenance detail beyond what the schema provides, 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 first sentence gives a specific verb (List), a precise resource (products of a category, brand or promotion page), and the returned fields (prices, discount, stock, rating). It also explicitly contrasts itself with tl_search for free-text queries, so an agent can separate it from siblings without opening any schema.

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

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

It states when to use it (browsing a product type or brand, sorted and filtered), names the prerequisite step ('Get brand and attribute codes ... from tl_category_filters first'), and routes free-text intent to tl_search. When-to-use, prerequisite ordering, and alternative are all explicit.

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/no-destruction, so the bar is lower. The description adds valuable non-obvious behavior: the specs keying is {section: {spec: values}} with values ordered per product, and specs no product fills are omitted – details an agent couldn't infer from 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 with the core action, then two compact sentences on specs shape and routing. Efficient, though the specs-shape sentence is dense and the line breaking is slightly odd.

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?

Output schema exists, so return values needn't be explained, and the description still usefully explains the specs structure. It could be more complete on category-comparison limitations or error behavior, but for a 1-param read-only tool it's solid.

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 documents the format, pattern, and 2-5 range. The description restates the 2-5 constraint and adds the ordering rule for specs values, but that ordering pertains to the return shape rather than the parameter itself, so it's roughly baseline.

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

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

States a specific verb (compare) and resource (products) with scope (2-5, side by side). It also distinguishes from the sibling tl_product by explicitly routing single-product seller/color needs there.

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 routing rule to tl_product for the seller/color use case and notes that same-category products compare best. It doesn't, however, cover the other ~17 siblings or state when not to use 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?

Adds substantial context beyond the readOnly/idempotent annotations: deal_ends is UTC, total is the pre-filter list size, and biggest_percent/min_discount_pct cause each page to scan the next 100 deals and return the best `limit`, with more_on_page counting the cut-off matches. That is genuine operational behavior an agent cannot get from 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?

Dense and front-loaded: the tool's identity leads, then behavior, then the alternative. Some clauses (the 100-deal scan explanation) are tightly packed but each earns its place; nothing is padding.

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

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

An output schema exists, so return format need not be described, and the description covers paging, filtering, and the sibling alternative well. It leaves minor ambiguity about how page numbering advances through the 100-deal scan window, but is otherwise sufficient for correct invocation.

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

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

Schema coverage is 100%, so baseline is 3, but the description goes further by explaining the interaction between sort, min_discount_pct and paging (scan window, more_on_page) and by clarifying that total ignores min_discount_pct. It still doesn't explain how page interacts with the scan window, leaving a minor 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?

States specific verbs and resources: in-stock discounts from the main deal list (تکنوآف) plus timed home-page deals (تکنو تایم) on page 0. An agent can distinguish this immediately from tl_category_products, tl_find_cheapest, and the other 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?

Directly answers the selection question with 'Use for "best deals right now"' and routes the category-scoped case to a named alternative (tl_category_products with sort=biggest_discount_toman), including the exact parameter value needed.

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 still adds operational behavior: how to phrase queries ('short single words match best') and how to interpret an empty result set, which the annotations cannot convey. It does not discuss rate limits or result counts, keeping it short of a 5.

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

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

Two compact sentences, front-loaded with the action and resource, followed immediately by when-to-use and the empty-result fallback. No filler sentences.

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?

An output schema exists, so return-value explanation is unnecessary, and the single required parameter is fully covered by schema plus description. Usage conditions and the failure-mode alternative are both present, making the definition 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 100%, so the schema already documents the single 'query' parameter including its Persian-language examples. The description adds real matching semantics beyond that ('short single words match best'), which the schema does not state.

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

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

States a specific verb and resource (search the help-center FAQ) and names the return shape (matching questions with plain-text answers). This is clearly distinguishable from the product-oriented siblings like tl_search and tl_product without opening any schema.

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

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

Gives an explicit use case (policy questions: installments, delivery, returns, warranty, invoices) and a concrete fallback path ('an empty list means try another word or tl_store_info'), naming the alternative sibling by name. 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 read-only, idempotent, non-destructive, open-world, so the safety profile is covered. The description adds genuinely new behavior: the empty-result meaning (site spells the brand differently) and the recovery path through tl_search. This is a meaningful disclosure beyond 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 paragraphs, front-loaded with the purpose, then the usage routing. No filler sentences. Slightly dense but each clause carries actionable 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?

An output schema exists, so return values need not be explained, and the description wisely focuses on how to use brand_code and brand_page downstream. For a one-parameter lookup tool it covers the important failure mode and routing. Could mention nothing further it critically lacks.

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 schema itself documents the Persian-name requirement with examples. The description reinforces the input semantics by stating the name must be the Persian site spelling and demonstrates the mismatch problem. It adds context but doesn't need to restate the parameter, so it sits slightly above the schema baseline.

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

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

States a specific verb and resource: look up a brand by its Persian name, returning filter code and brand page. Clear purpose, though the distinction from tl_search is implied rather than sharply drawn. It is a lookup helper rather than the search 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?

Explicitly tells the agent where the returned values go (brand_codes in tl_search/tl_find_cheapest/tl_category_products, brand_page in tl_category_products) and gives an exact fallback for the empty-list case, naming tl_search and the `brands` facet. When-to-use and alternatives are both concrete.

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 read-only, idempotent, non-destructive, open-world behavior, so the safety profile is covered. The description adds genuinely non-obvious behavioral context: results are in-stock only, sorted by post-discount real price, and the displayed price is the site's featured offer per product rather than necessarily the cheapest seller. No auth/rate-limit or pagination behavior is disclosed.

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

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

Front-loaded with the core purpose, then usage, then pitfalls and price semantics — a sensible order. The middle sentence is long and dense (parenthetical example plus three chained actions) but every clause carries actionable 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 an output schema present, return values need not be explained, and the description covers what matters for correct invocation: purpose, trigger condition, the accessory false-positive trap, refinement via returned metadata, and the meaning of the shown price. Minor gaps (pagination via `pages`, value of `limit`) are already handled by the schema.

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 7 parameters, including where brand_codes and category_code come from. The description adds a light workflow hint ('call again with category_code and brand_codes') but conveys no syntax, range, or format meaning beyond what the schema states. 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?

Specific verb+resource+scope: 'Find the cheapest in-stock products for a search, one flat list sorted by the real price after discount.' It also differentiates itself from the sibling tl_product (which 'shows every seller, color and installment price'). An agent can tell this apart from tl_search and tl_product without opening any schema.

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

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

'Use when the user wants the lowest price' gives a clear triggering condition, and it names tl_product as the alternative for full seller-level pricing. It also proactively warns that accessory/other-model noise matches model names and prescribes a refine-and-retry loop with category_code/brand_codes. There's no explicit when-not clause, 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.

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 by structured data. The description adds the useful detail that results carry province and city, but discloses no additional behavioral traits (rate limits, ambiguity handling, auth needs) beyond that.

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 paragraphs, front-loaded with the core operation before the usage contexts. Every sentence earns its place with no redundancy or 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?

An output schema exists so return values need no explanation, annotations cover the safety profile, and the schema fully documents both parameters. The description supplies the remaining context an agent needs: what the tool converts and why it would be called.

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 the query and limit parameters are already documented in the schema, including the Persian-language example and the 1-20 bound. The description re-touches 'address or landmark' but adds no syntax or format detail beyond the schema, 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 transformation with clear directionality: 'Turn an address or landmark into coordinates with its province and city.' This forward-geocoding direction is unambiguous and implicitly distinguishes it from the sibling tl_reverse_geocode, which does the opposite mapping.

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 concrete use cases ('tell which city an address is in' and 'find the nearest branch') and even cross-references tl_store_info for the shipping dependency. It stops short of naming an explicit alternative (e.g., tl_reverse_geocode) or stating when-not-to-use, so it is clear but not fully 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 readOnly/idempotent/openWorld, and the description adds substantial context beyond them: no persistence, no authentication, no order placement, shipping exclusion, and the max_count/over_max_count refusal behavior. These are exactly the side-effect and constraint details an agent cannot infer from structured fields.

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 outcome, then constraints in short declarative sentences. The parenthetical asides ('it needs a logged-in address') are slightly chatty but each sentence carries useful information, so little 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 an output schema present and 100% schema coverage, the description need not explain return values, and it correctly focuses on the non-obvious: guest mode, shipping exclusion, quantity limits, and the dedupe constraint. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning: it explains what max_count and over_max_count mean in the response and clarifies the one-entry-per-seller_item_id rule, which shapes how the items array must be constructed.

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

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

Opens with a specific verb and resource: 'Get the exact total for a set of seller items', and enumerates what the total includes (discounts, insurance, quantity limits, cash vs installment). An agent knows precisely what this computes, though it never explicitly names which sibling (e.g. tl_compare, tl_find_cheapest) it replaces.

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

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

Gives concrete operating context: prices as a guest, nothing saved, no login, no order, shipping excluded because an address requires login. It also constrains invocation ('each seller_item_id may appear once: compare cash and installment in separate calls'), which is real usage guidance, though no alternative tool is named.

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, so safety is covered. The description still adds real behavioral context beyond them: offers are sorted 'cheapest cash price first', and installment_price/bnpl_price represent the same seller item in different price lists and are 'null if not offered'. That ordering and nullability contract is not derivable from 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 with the return contents, then the workflow, then the semantics of the ambiguous price fields. Every sentence carries information; nothing is restated from 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 an output schema present the description need not explain return values, yet it usefully clarifies the two easily-confused price fields and the sort order. Combined with annotations and full schema coverage, an agent has everything needed to call this correctly and chain it into tl_price_basket.

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% — product_code and include_specs are both fully documented in the schema, including the TLP- pattern and the 'adds a few KB' cost note. The description's extra detail concerns returned price fields rather than the two input parameters, so it adds little on the parameter axis. 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 verb and resource ('Get one product's offers') and enumerates exactly what is returned: price per color, seller/warranty, stock, delivery time, insurance and installment prices. This is clearly distinguishable from tl_search and tl_suggest, which the description itself names as upstream steps.

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 tl_search / tl_suggest', gives the user questions it answers (cheapest, which color, warranty, shipping, installments), and routes onward: 'Pass seller_item_id to tl_price_basket for a final total.' Both the entry condition and the follow-up tool are named.

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 structurally. The description only adds that the output is an address broken into province/city/neighbourhood, which is largely duplicated by the existing output schema, so it contributes little behavioral context beyond 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 the core operation front-loaded before the usage note. No filler or repetition; only slight room to sharpen by naming an alternative 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 full output schema and fully described parameters, the description only needs to convey purpose and usage, which it does. Coverage of out-of-range coordinate behavior is handled by the schema bounds, so nothing essential is missing for correct invocation.

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

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

Schema description coverage is 100% – both lat and long carry range constraints and examples in the schema itself. The description adds no syntax, format or semantics for the parameters, so the baseline 3 applies.

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

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

States a specific verb and transformation: describe coordinates as an address with province, city and neighbourhood. This is unambiguous and clearly a reverse-geocoding operation. It does not explicitly differentiate from tl_find_location, but no sibling overlaps the coordinate-to-address direction, so the risk of mis-selection is low.

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 two concrete when-to-use scenarios (confirming a delivery point with the user, getting the city for shipping rules), which is above the minimum-viable bar. It does not name an alternative or state when NOT to use it, 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.

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds non-obvious behavior: the AI summary is null for low-review products and only appears on page 0, and the rating sorts rank only the newest 500 reviews with newest-first tiebreak. These are exactly the quirks an agent would otherwise discover only by trial.

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, front-loaded with what the tool returns, followed by a usage cue and then the two edge-case rules. No filler and nothing repeated from 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?

An output schema exists, so return structure need not be explained, yet the description still flags the nullable AI summary and its page-0 restriction. Combined with full schema coverage and a clear read-only annotation set, an agent has everything needed to call this 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 the baseline is 3, but the description adds meaning beyond the enum values: it explains what lowest_rated surfaces (complaints) and clarifies that highest/lowest_rated rank a bounded 500-review window. It does not add anything for page or limit, which the schema already covers.

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 (Read) and resource (customer reviews of a product) and enumerates exactly what is returned: average rating, star distribution, AI summary with pros/cons, and the reviews themselves. This cleanly separates it from tl_shop_reviews (store-level) and tl_product (product metadata) even though neither sibling is named.

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 as a quality check before recommending a product" gives a concrete decision context, and "sort=lowest_rated surfaces complaints" gives actionable guidance for that goal. There is no explicit when-not-to-use or named alternative, 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 declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds real behavioral context beyond that: the response also carries top matching categories and brands with filter codes, and those codes are meant to be fed back into category_code/brand_codes. It does not mention result caps or rate limits, but that is minor for a read-only 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?

Front-loaded with the core purpose in one sentence, then a compact paragraph on the returned filter codes and the sibling alternatives. No filler, though the middle sentence about passing codes back is slightly run-on and could be split for clarity.

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 an output schema present, return values need no explanation, and annotations cover safety, so the description's remaining job is routing and the filter-code round trip — both handled. Only the omission of any note on pagination depth or result volume keeps it from a 5.

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 all nine parameters are documented in detail (units in Toman, enum semantics, page/sort interaction), so the schema does the heavy lifting. The description's mention of category_code and brand_codes largely restates what the schema already says, adding only the 'phones, not phone cases' nuance that also appears in 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 Technolife products') and immediately scopes what the result contains: prices, discount, stock, rating. It also names the two siblings it must not be confused with (tl_find_cheapest, tl_product), so an agent can discriminate without opening any schema.

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

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

Explicitly routes away from this tool for two cases: 'For the cheapest offers over several pages use tl_find_cheapest; for one product's sellers, colors and installment prices use tl_product.' It also explains the intended follow-up use of returned filter codes. It stops short of stating the primary when-to-use condition or when other siblings (tl_suggest, tl_deals, tl_campaigns) are preferable.

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 useful context on what data is returned (rating scale, on-time %, time on Technolife) but says nothing about pagination, rate limits, or behavior for unknown seller codes.

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 zero filler: the first front-loads what is returned, the second front-loads the usage trigger. 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 an output schema present, return values need not be re-explained, and the description covers purpose, payload fields, and the calling context. The only minor gap is paging/sort behavior on the product list, which is left to the schema.

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

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

Schema description coverage is 100%, so page, sort, limit, in_stock, and seller_code are all documented in the schema itself. The description adds no parameter-level detail (e.g. how sort interacts with paging), so the baseline 3 applies.

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

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

States a specific verb and resource ('Get a marketplace seller's reputation... and its products') and enumerates the returned reputation metrics, so the agent knows exactly what comes back. It is clearly distinct from siblings like tl_product or tl_reviews.

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

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

Explicitly says when to use it: to judge a seller surfaced in tl_product offers before recommending that offer, which chains it to the sibling that produces seller codes. No explicit when-not or alternative tools are named, 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.

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 context beyond that: newest-first ordering, rating range 1-5, inclusion of staff replies, Jalali dates, and a data-freshness caveat that reviews may be years old.

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 with no filler; the core purpose and the sibling disambiguation are front-loaded, and the data caveat is placed last where it belongs.

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?

Because an output schema exists, return values need no explanation, and the description covers the ordering, rating scale, and the notable Jalali/freshness quirks. It is essentially complete for a simple read tool, with only minor room for more pagination guidance.

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 page and limit are fully documented in the schema, giving a baseline of 3. The description only echoes the 'newest first' ordering already present in the page parameter and adds no syntax or edge-case detail beyond 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 verb (Read) and resource (customer reviews of the Technolife shop itself), with explicit scope (service, delivery). It directly distinguishes itself from the sibling tl_reviews, so an agent can route 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 an explicit selection rule: use this to judge the shop rather than a product, and names the alternative (tl_reviews) for the product case. When-to-use and when-not-to-use are both 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 declare readOnly/idempotent/non-destructive, and the description adds real context beyond them: output is plain text, and order-specific shipping costs cannot be quoted without a logged-in address, so the agent should quote general rules. It stops short of describing pagination or page-selection 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?

Front-loads the core action, then the use cases, then the shipping caveat and fallback sibling. Every sentence earns its place with no filler.

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

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

With rich annotations, a fully documented enum parameter, and an output schema covering return values, the description supplies everything else an agent needs: what it returns (plain text), when to use it, and when to route elsewhere.

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

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

Schema description coverage is 100% with a single fully documented enum, so the schema already carries the parameter meaning. The description restates the topic areas but adds no enum syntax or format detail beyond what the schema provides, making the baseline 3 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 verb and resource ('Read one of Technolife's info pages as plain text') and enumerates the covered topics (stores, shipping, returns, payment). It explicitly distinguishes itself from the sibling tl_faq, so an agent can route between them 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 explicit when-to-use triggers ('questions about physical stores, how and how much shipping costs per city, returns and how to pay') plus a key caveat that exact order shipping needs a logged-in address, and names the alternative (tl_faq) for other questions. This is near-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 declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds useful behavioral detail beyond annotations: typeahead behavior, a maximum of 30 products, and the fact that no prices 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?

The description is three short sentences and front-loads the core behavior first, followed by usage and the alternative tool. Every sentence adds distinct routing or constraint information with no wasted 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?

Given the output schema, rich annotations, and 100% schema description coverage, the description provides everything an agent needs: purpose, scope, limit, exclusion of prices, downstream use, and the alternative for broader search. No necessary behavioral or routing context 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?

The input schema has 100% description coverage for the single query parameter, including examples in Persian and English. The description reinforces that the input is a product name but adds no syntax, format, or constraint details beyond what the schema already provides, so this is the baseline adequate score.

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 verb and resource: it turns a product name into Technolife product codes. It also distinguishes the tool from siblings by naming tl_product / tl_compare / tl_reviews as downstream consumers and tl_search as the alternative for prices, filters, and paging.

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 explicitly says to use it to resolve a name into codes for specific sibling tools, and explicitly says to use tl_search instead for prices, filters, and paging. This gives a clear when-to-use and when-to-use-an-alternative rule.

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