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

Annotations already declare readOnly/idempotent/non-destructive/openWorld, so the safety profile is covered. The description adds genuinely new behavioral context by disclosing that the return payload differs by mode (landings+page_url vs carousels+products+links) and warns that the carousel product count is partial. It omits pagination/rate details, but that gap is minor against the annotation coverage.

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 two operating modes and then bulleted by case, so the agent gets the decision rule immediately. Every line earns its place, though the 'products_in_carousel' phrasing introduces a small term mismatch that costs a bit of 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 no output schema, the description carries the burden of describing return shapes, which it does for both modes. Combined with full schema coverage and complete safety annotations, an agent has everything needed to invoke 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 coverage is 100%, so the baseline is 3. The description goes beyond the schema by clarifying the consequence of omitting `code` and by scoping the meaning of the per-carousel product count ('counts only the carousel'). Minor naming drift ('products_in_carousel' vs `products_per_section`) tempers this slightly.

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 current campaigns, or show one campaign's sections and products') and explicitly encodes the dual-mode behavior keyed on the presence of `code`. It distinguishes itself from the sibling `tl_category_products` by routing full product listing there, so an agent can tell the two apart 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 explicit when-to-use branches: omit `code` to list landings/promotion pages, supply `code` to get carousels and links. It also names the alternative (`tl_category_products`) and the condition that selects it (listing all products of a carousel).

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, and the description adds genuinely new behavior: the return shape changes with the mode (matching categories, sub-pages, or top-level categories plus child titles). It stops short of noting pagination, result limits, or whether empty results occur.

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

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

A single purpose sentence followed by three one-line mode bullets, front-loaded and waste-free. The formatting maps directly onto the parameter combinations an agent must choose between.

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 explain what each mode yields. It leaves unspecified whether the returned urls are relative or absolute strings and how results are bounded, which an agent would want before chaining into tl_category_products.

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 would be the baseline, but the description goes beyond the schema descriptions by explaining what happens when each parameter is supplied versus omitted, and how the two parameters interact (query for the menu-wide search, url for drilling into sub-pages).

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

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

States a specific verb and resource ("Find category pages and their urls") and ties itself explicitly to the sibling tool it feeds, tl_category_products. An agent can distinguish it from tl_search or 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?

Enumerates all three invocation modes (query, url, neither) with the outcome of each, and even ranks one mode as "best way to get a url." This is explicit when-to-use guidance rather than implied context.

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's added value is the output-oriented note that the result is a set of codes intended to feed other tools. It says nothing about return shape, pagination, or whether a bad path errors or returns empty, so it clears the lower annotation-adjusted bar without going further.

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, zero filler, with the scope and returned field list front-loaded and the sequencing rule immediately after. 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?

No output schema exists, and the description compensates by naming the returned filter families and codes, plus the downstream consumer of those codes. What remains thin is the failure/edge behavior of an invalid page path and whether codes are stable across calls, but for a single-parameter read tool this is close to 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% and the schema itself carries the pattern, an example path, and the origin tools. The description repeats the page-type scope (category/brand/promotion) but adds no format or constraint details the schema does not already state, 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?

Specific verb ('List') plus a precisely scoped resource ('the filters of a category, brand or promotion page') and an enumeration of what those filters are: brands, categories, price range, attributes with codes. The second sentence distinguishes it from tl_category_products by naming it and the role this tool plays in the sequence.

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 conditional workflow rule: call this 'before tl_category_products' to obtain brand_codes, category_codes and attribute_codes. It names the downstream alternative and its purpose, though it offers no explicit when-not-to-use guidance (e.g. that it is unnecessary if you already hold the codes).

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 genuine value by stating what data comes back and the required upstream call, but it does not disclose pagination limits or rate/coverage caveats beyond what the schema shows.

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

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

Three short sentences, front-loaded with the capability, then usage and routing. Every sentence carries information and none is filler.

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

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

With 11 parameters and no output schema, the description supplies the missing pieces: what fields are returned, the upstream dependency, and the sibling to use for free text. 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 description coverage is 100% and the schema already documents every parameter, including the tl_category_filters provenance for brand_codes, attribute_codes and price bounds. The description's mention of sourcing codes from tl_category_filters largely restates that, so it adds little 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 (List) and resource (products of a category, brand or promotion page) and enumerates the payload (prices, discount, stock, rating). It also distinguishes itself from tl_search by scoping to structured browsing rather than free text.

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 (browse a product type or brand by price or popularity), a prerequisite (fetch brand/attribute codes and price range from tl_category_filters first), and routes free-text queries to tl_search. All three of when-to-use, prerequisite, and alternative 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 and non-destructive, so the safety profile is covered. The description usefully adds return semantics absent from the schema: specs is {section: {spec: values}} with one value per product, aligned to input order, and empty specs are omitted — genuinely helpful since there is no output schema. 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?

Four short sentences, front-loaded with the core action and result set, then details on shape and caveats. Efficient overall, though the undefined tokens `products` and `specs` cost a little clarity for the space they take.

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 compensates by sketching the returned specs structure and the omission rule, and the annotations cover safety and open-world behavior. It remains incomplete on edge cases (incomparable categories, codes that fail lookup) and uses a parameter name that isn't in 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% for the single parameter (product_codes, with format/example and min/max items), so the schema does the heavy lifting and a 3 is the baseline. The description adds ordering intent but refers to an input called `products` that does not exist in the schema, introducing a naming mismatch that could misroute the agent.

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 — compare 2-5 products side by side on price, stock, rating and specs — which an agent can immediately distinguish from list/search siblings. Sibling routing is only partially covered: tl_product is named for sellers and colors, but no differentiation from tl_find_cheapest or tl_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?

Gives a real usage constraint ('Same-category products compare best') and one explicit alternative ('For sellers and colors use tl_product'). It lacks broader when-not guidance, e.g. what to use for a single product or for cross-category basket pricing (tl_price_basket), 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 only cover the safety profile (readOnly, idempotent, openWorld, non-destructive), and the description goes well past that: it discloses that deal_ends is UTC, that total counts the whole list before min_discount_pct is applied, that biggest_percent/min_discount_pct cause each page to scan the next 100 deals and return only the best `limit`, and that more_on_page signals matches cut off by the limit. These are non-obvious call/filter semantics that cannot be derived from the annotations or 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?

Front-loaded with the core purpose and scope, then paging/filter caveats, then sibling routing — a sensible order with little filler. The dense compressed phrasing ('total is the whole deal list, before min_discount_pct') and the newline-broken layout cost it a point but nothing is truly 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 four optional params, no output schema, and no nested objects, the description covers the important gaps: what total and more_on_page mean, the timezone of deal_ends, and how paging interacts with sort/filter. It stops short of naming the actual fields of a returned deal record, but for a read-only list endpoint that is a minor omission.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds real meaning: it explains that biggest_percent re-sorts a page of the largest Toman discounts by percent (a subtle interaction with the default sort), that min_discount_pct filters against the untruncated `total`, and that page 0 additionally returns timed deals. That is genuine added semantics beyond the per-field schema text.

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

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

States a specific verb+resource with scope: 'List current in-stock discounts' covering both the main deal list (تکنوآف) and the timed home-page deals (تکنو تایم) on page 0. It explicitly names the sibling to use for a narrower case (tl_category_products with sort=biggest_discount_toman), so an agent can separate this from the 18 other sibling tools 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 an explicit use case ('Use for "best deals right now"') and an explicit routing rule away from this tool when the scope is a single category, naming the alternative tool and the exact sort value to pass. Both the when-to-use and the when-to-use-something-else conditions are stated rather than inferred.

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

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

Annotations already declare read-only, idempotent, open-world, non-destructive behavior, so the safety profile is covered. The description adds genuinely new behavioral context: an empty result list is the expected no-match signal and suggests retry or an alternative tool.

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 and a hint line; the core action and return shape are front-loaded 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 no output schema, the description correctly states what is returned (questions plus plain-text answers) and covers the empty-result case. Enough for a one-parameter lookup tool, though it could note approximate matching or language scope.

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 already gives an example and minLength, so baseline is 3. The description adds real query-shaping guidance ('single words match best'), which is not derivable from 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 and resource ('Search ... help-center FAQ') plus what comes back ('matching questions with plain-text answers'). It names the tl_store_info fallback but does not differentiate itself from search-like siblings tl_search and tl_suggest.

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 policy questions' gives clear context, and 'empty list means try another word or tl_store_info' supplies an explicit fallback path. No when-not-to-use guidance relative to tl_search/tl_suggest, but the routing hint is 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 cover the safety profile (readOnly, idempotent, openWorld, non-destructive), but the description adds non-obvious behavior: an empty list means a spelling mismatch (هوآوی vs هواوی) rather than a missing brand. That failure-mode disclosure is genuinely useful and not derivable 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?

Four short lines, front-loaded with the purpose before the integration and troubleshooting notes. Every line earns its place, though the typographic splitting is slightly more verbose than a single tight paragraph would be.

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 correctly compensates by naming the returned fields (brand_code, brand_page). It is nearly complete; only edge cases such as multiple matches or exact-match requirements go unmentioned.

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 already gives the type, minLength and an example, so the baseline is 3. The description goes further by warning that the name must match the site's exact Persian spelling, which materially changes how the agent should construct the `name` value.

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 ('Look up a brand by its Persian name') and explicitly names the two outputs it yields: a filter code and a brand page. This distinguishes it from all siblings, which consume those outputs rather than produce them.

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

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

Explicitly routes the outputs: 'Pass brand_code in brand_codes of tl_search / tl_find_cheapest / tl_category_products, or brand_page as the url of tl_category_products.' It also provides a fallback path (the `brands` facet of tl_search) when this tool returns nothing, so the agent knows both when to use it and what to do when it fails.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, open world), so the bar is lower, and the description adds genuinely useful traits: results are flat and sorted by post-discount real price, and the quoted price is the site's featured offer rather than necessarily the cheapest seller. It stops short of stating pagination/scan cost behavior despite the `pages` scan parameter.

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 is front-loaded in the first sentence and each following sentence carries a distinct instruction (refinement loop, price caveat). Slightly dense mid-paragraph phrasing ('Accessories and other models often match a model name') costs a little readability but nothing is filler.

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

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

With no output schema, the description does the work of describing the return by naming result fields (`categories`, `brands`, titles) and the ordering of the list. It is largely self-sufficient for a 7-parameter search tool, though it leaves the `pages`/`limit` scan-cost tradeoff and pagination behavior unexplained.

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 sourcing of category_code and brand_codes (they come from the result's `categories`/`brands` or from tl_find_brand) and the purpose of filtering by category (to skip accessories). That is usage meaning the schema text alone does not supply.

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 the cheapest in-stock products for a search') plus the output shape ('one flat list sorted by the real price after discount'). It distinguishes itself from siblings by naming tl_product as the deeper seller-level tool, so an agent can separate it from tl_search and tl_compare without reading 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 rule ('Use for the lowest price'), an alternative for a different need (tl_product for every seller and installment price), and a concrete refinement loop: check the returned categories/brands, then re-call with category_code and brand_codes. Both when-to-use and when-to-look-elsewhere 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, so safety is covered. The description adds value the structured fields cannot: it discloses the return contents (coordinates, province, city) in the absence of an output schema, and flags the shipping dependency. It omits ambiguity handling (multiple matches) and any rate-limit context.

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 transformation, then the use cases. 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 two-parameter read-only lookup with full schema coverage, the description covers purpose, use cases, and return contents. It does not address what happens when the query is ambiguous or when multiple places match the default limit of 5, a minor gap given no output schema exists.

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

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

Schema description coverage is 100%: both 'query' (Persian-address example) and 'limit' (range, default) are already documented in the schema. The description adds no format or syntax detail beyond that, 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 transformation (address/landmark -> coordinates, province, city), which is a different operation from the inverse geocoding in the sibling list. An agent can tell it apart from tl_reverse_geocode without reading 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?

Names two concrete use cases (resolving an address's city for shipping, finding the nearest branch) and cross-references tl_store_info topic=shipping. It stops short of an explicit exclusion or forward-reference to tl_reverse_geocode for the opposite direction, so routing is clear but not fully disambiguated.

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). The description adds genuinely new behavioral context beyond them: pricing is done as a guest and nothing is persisted, plus it explains result semantics (max_count, over_max_count meaning the site refuses the quantity).

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 purpose in the first clause and stays compact. The trailing sentences about max_count/over_max_count are terse and arrive without framing them as response fields, which slightly hurts readability, but nothing is padded.

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

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

With no output schema, the description partially compensates by explaining max_count/over_max_count return semantics and the guest/no-save behavior. It is close to complete, though the return shape (totals, per-item breakdown) is still only partially described.

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 nested BasketItem fields are already documented. The description still adds a constraint absent from the schema — that each seller_item_id may appear only once and comparisons must be separate calls — which is real value beyond the structured fields.

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 ('Get the exact total for a set of seller items') and enumerates what the pricing covers: discounts, insurance, quantity limits, cash vs installment. This clearly distinguishes it from browsing siblings like tl_product and tl_compare.

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

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

Gives concrete usage constraints: guest pricing, nothing saved, each seller_item_id may appear once, and compare cash vs installment in separate calls. It does not explicitly name sibling alternatives (e.g. tl_product for offer lookup), so routing guidance is implicit rather than 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 the safety profile (readOnly, idempotent, non-destructive, openWorld), so the bar is lower. The description still adds real behavioral context beyond them: offers are sorted cheapest cash price first, and installment_price/bnpl_price are the same seller item in different price lists, null when not offered. Missing only peripheral details like pagination or result caps.

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 short paragraphs covering result semantics and workflow chaining. Every sentence carries information, though the dense second paragraph packs several field-level definitions into one breath.

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 must convey the return shape — and it does, listing the price/seller/warranty/stock/delivery/insurance facets and the sort order. An agent has enough to call it and interpret the response, with only minor gaps around error cases or empty results.

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

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

Schema description coverage is 100% and both parameters (product_code with its TLP- pattern, include_specs with default) are already documented there. The description adds no syntax or format guidance for the inputs; seller_item_id it mentions is an output field, not an input parameter. 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 one product's offers) and enumerates the returned facets: price per color, seller, warranty, stock, delivery time, insurance and installment prices. This distinguishes it from sibling listing/search tools like tl_search and tl_compare, which the agent can rule out 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?

Explicitly positions the tool in a workflow: 'Use after tl_search / tl_suggest' and 'Pass seller_item_id to tl_price_basket for a final total.' This names both the upstream alternatives that lead here and the downstream tool to call next, 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 fully covered. The description adds the output granularity (province/city/neighbourhood), which is useful since there is no output schema, but says nothing about coverage limits, accuracy, or failure behavior for out-of-range coordinates.

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

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

Two short sentences, zero filler, with the core action stated first and the use cases second. Nothing is redundant with the name or title.

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

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

For a two-parameter read-only tool with no output schema, the description supplies the essential return shape (address components) and the primary use cases. It stops short of noting the regional coordinate bounds or what happens when a point cannot be resolved.

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 typed, bounded, example-bearing lat/long properties, so the schema does the heavy lifting. The description adds no coordinate format, ordering, or unit guidance beyond what the schema already provides — 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 verb and resource ('describe coordinates as an address') and enumerates the returned components (province, city, neighbourhood), so the agent knows exactly what the tool produces. It never names the obvious inverse sibling (tl_find_location), so differentiation is left to inference, keeping it below 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 two concrete use cases — confirming a delivery point and resolving a city for shipping rules — which is clear contextual guidance. However, it offers no when-not conditions and does not contrast with tl_find_location (forward geocoding) or other location 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 cover safety (readOnlyHint, idempotentHint, destructiveHint=false), and the description adds genuinely non-obvious behavior: text truncated at 400 chars unless full_text=true, AI summary is null for few reviews and appears only on page 0, and rating sorts cover only the newest 500 reviews. It does not mention pagination limits or response shape, but the caveats it does give are 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?

Three short sentences with the primary purpose front-loaded and caveats trailing. Every sentence carries new information; no filler or restated field names. Slightly dense but well ordered.

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 well: it names the average, star distribution, AI summary, and review list, and explains the truncation, page-0-only summary, and sorting scope. An agent knows what it will get and the main edge cases before calling.

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 lacks: the effect of full_text (uncut vs 400-char cutoff), the purpose of sort=lowest_rated, and the 500-review scope of the rating sorts. The page parameter's role in gating the AI summary is also clarified.

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 verb and resource ('Read customer reviews of a product') and enumerates the payload: average rating, star distribution, AI pros/cons summary, and the reviews themselves. The product scope implicitly separates it from the sibling tl_shop_reviews, but that sibling is never named, so differentiation requires inference.

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 explicit usage context: 'Use as a quality check before recommending; sort=lowest_rated surfaces complaints.' That is a clear when-to-use with a concrete tactic. It stops short of naming alternatives or stating when not to use it (e.g., versus shop-level reviews).

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 is covered. The description adds real behavioral context beyond that: the result set carries category and brand codes intended to be passed back as filters, which is a round-trip behavior not derivable from annotations. It does not cover rate limits, auth, or pagination limits beyond what the schema states.

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

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

Three tight sentences, front-loaded with what the tool is, followed by the narrowing workflow and then sibling routing. Every clause carries information; no filler or restatement of the name.

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

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

With no output schema, the description compensates by naming what comes back (price, discount, stock, rating, categories, brands). Nine parameters are fully documented in the schema and the description supplies the cross-tool routing and filter-code semantics 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 coverage is 100%, so the baseline is 3, but the description adds workflow meaning the schema does not: filter codes come from the result's own categories/brands fields (or tl_find_brand) and category_code is meant to exclude accessories ('phones, not cases'). That clarifies intent rather than merely restating types.

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

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

Opens with a specific verb+resource (search Technolife products) and enumerates the returned attributes (prices, discount, stock, rating), plus the secondary payload of matching categories and brands. An agent can tell it apart from tl_find_cheapest 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?

Explicitly names two alternatives with the conditions that select them: tl_find_cheapest for cheapest across pages, tl_product for one product's sellers/prices. It also states the intended workflow for narrowing via category_code/brand_codes.

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 value beyond that by disclosing the return payload — reputation metrics plus the seller's product list — which matters since no output schema exists. It does not mention pagination behavior of the embedded product list.

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

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

Two tight sentences: the first defines the payload, the second gives the usage rule. Front-loaded and free of filler, with every clause earning 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 does the necessary work of naming the returned reputation metrics and noting the seller's products are included. The only gap is that it doesn't signal the product list is paged (default 20, max 50), which the agent must infer from 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%, with every parameter documented including the seller_code pattern and the sort enum, so the schema carries the burden. The description adds no additional parameter meaning (no note on paging through a large catalog or how in_stock/sort interact with the reputation result), 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 exact fields returned (rating 0-5, on-time %, fault-free %, time on Technolife). It also positions itself in the workflow relative to the tl_product sibling, so an agent can tell what this tool is for 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?

Gives a clear when-to-use rule: judge a seller surfaced in tl_product offers before recommending that offer. It establishes the discovery-to-evaluation flow but names no exclusions or explicit alternative (e.g., how it differs from tl_store_info or tl_shop_reviews if those overlap).

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, so the safety profile is covered. The description still adds genuinely non-obvious operational context the annotations don't carry: dates are Jalali and the newest reviews on the site may be several years old, which materially affects how an agent interprets freshness.

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 scope, with the routing rule and the data-freshness caveat packed in without any filler. Every clause carries information an agent needs.

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

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

There is no output schema, so the description must carry return-shape information; it does so partially by stating ratings 1-5 and staff replies, but it doesn't describe the review record structure or pagination behavior. For a three-optional-parameter read tool with full annotations, 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 description coverage is 100%, so page, limit and full_text (including the 400-character cut behavior) are already documented in the schema. The description adds 'newest first' but no additional parameter syntax or meaning beyond that, matching the baseline for fully-covered schemas.

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 — reading customer reviews of the shop itself, covering service and delivery — plus return ordering (newest first) and content (rating 1-5, staff replies). It explicitly separates this from the product-review sibling by naming tl_reviews, so an agent can choose 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?

It gives an explicit selection rule: 'Use to judge the shop rather than a product (for a product use tl_reviews)'. That names the alternative and the condition that routes to it, which is exactly what the sibling-collision with tl_reviews requires.

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 readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is known. The description adds genuinely new behavioral context: output is plain text, and exact shipping cost cannot be resolved without a logged-in address, so the agent should quote rules instead. That auth/limitation disclosure is the value-add; return formatting and size are otherwise unspecified.

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, purpose front-loaded, alternative routing last. Every sentence earns its place with no repetition of schema 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?

For a one-parameter lookup with no output schema, the description covers what it does, what it returns (plain text), when to use it, when to use the sibling instead, and the one behavioral caveat (auth-gated exact costs). Nothing needed to invoke 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% and the single enum already documents all four topic values, so the baseline is 3. The description restates those topics with slight added nuance ('shipping rules per city') but adds no syntax or format 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 and resource ('Read one of Technolife's info pages') and enumerates the covered topics (stores, shipping rules per city, returns, payment), which maps directly onto the enum. It also names the sibling it is not, tl_faq, so an agent can distinguish it 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?

Explicit when-to-use ('for stores, shipping rules per city, returns and payment') plus an explicit alternative and its trigger ('For other questions try tl_faq'). It even warns about the auth prerequisite, telling the agent to quote rules rather than attempt an exact cost lookup.

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 (readOnlyHint, idempotentHint, destructiveHint=false), so the description earns credit by adding return-behavior context: typeahead semantics, a cap of up to 30 products, and the explicit absence of prices. It still doesn't say whether results are ranked, fuzzy-matched, or what happens on no match, but the added detail goes meaningfully 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 short paragraphs, front-loaded with the core transformation and scope, followed by the routing guidance. No sentence 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 no output schema, the description compensates by describing what comes back (codes, up to 30, no prices) and where those codes are consumed. 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 coverage is 100% with a single 'query' parameter that already documents Persian/English input and the 'آیفون 16' example, so the description's example repeats the schema. Baseline 3 applies since the schema carries the parameter burden.

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 transformation: turns a product name into Technolife product codes, and explicitly frames itself as a typeahead. The parenthetical scope ('up to 30 products, no prices') further sharpens what it does versus what it doesn't.

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 both the when-to-use ('resolve a name like آیفون 16 to codes for tl_product / tl_compare / tl_reviews') and the when-not-to-use with the alternative ('For prices, filters and paging use tl_search'). An agent can route between tl_suggest and tl_search without opening either schema.

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