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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, so the safety profile is fully covered without the description. The description adds modest value by noting the return is plain text and includes a category id, but says nothing about truncation behavior, pagination, or failure modes for a bad slug.

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

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

A single front-loaded sentence with no filler. It is arguably too terse in its phrasing ('with its category id for sh_browse'), but every clause carries information.

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

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

With no output schema, the description does the minimum job of indicating the return shape (plain text plus category id), and annotations cover safety. The only real gap is truncation/format detail, which the max_chars schema description largely covers.

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 slug and max_chars are already documented in the schema with format, range, and default. The description adds no parameter-level meaning 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 ('Read one blog post') plus the output form ('as plain text') and an extra artifact ('its category id'), which clearly separates it from sh_blog_search and sh_browse. The parenthetical workflow note is slightly compressed but the core purpose is unambiguous.

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

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

The 'after sh_blog_search' clause tells the agent this is a second-step tool fed by a search result, and naming sh_browse signals where the returned category id is consumed. It gives clear sequencing context but no explicit when-not-to-use or error/fallback guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so safety is covered. The description adds genuinely new behavior: results are ordered newest-first and omitting the query returns the latest posts. It does not cover result shape or result-count limits, but the ordering/default semantics are meaningful additions.

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 primary purpose and ordering front-loaded before the workflow routing. The trailing 'then sh_search' is slightly terse and its sequencing is a bit compressed, costing a point.

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 search with no output schema, the description covers purpose, default behavior, ordering, and the follow-up workflow. Nothing essential to correct invocation is missing, though the relationship between the blog search and the generic sh_search could be spelled out more fully.

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 (page, query) are already documented, including the 3-per-page size and the Persian-language query example. The description only restates the null-query default ('no query = latest posts'), which the schema already declares as default null; 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 and resource ('Search the style blog'), scopes it ('guides and model galleries', 'newest first'), and differentiates it from the sibling sh_blog_post, which it names explicitly. An agent can distinguish it from sh_search and sh_blog_post 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 concrete use cases ('what is in fashion or which model to choose') and routes the agent to the correct sibling for the follow-up step ('read a post with sh_blog_post(slug)'), plus names sh_search as the next stage. The when-to-use condition is explicit 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 readOnly, idempotent, non-destructive, open-world behavior, so the safety profile is covered. The description adds genuine context beyond that: the returned data feeds sh_browse's brand_id filter, and the shop_id variant only works for watch shops, which is a real behavioral constraint.

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 with a parallel 'Without shop_id: ... With shop_id: ...' structure that is front-loaded and wastes no words. Both sentences earn their place by describing distinct result modes.

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

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

For a single-optional-parameter read tool with no output schema, the description covers both invocation modes, the output content (brand shops vs. brand ids), and the downstream use of those ids. Minor gaps like pagination or result ordering are not addressed but are not critical.

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

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

Schema coverage is 100% and there is only one optional parameter, so the schema already documents shop_id. The description still adds meaning by contrasting the no-shop_id and with-shop_id result sets and noting the id output is intended for the brand_id filter, beyond the schema's 'Watch shop id, e.g. 1771'.

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 specifies the resource (brands) and gives distinct semantics for each mode: featured official brand shops without shop_id, and the brands a given shop sells with shop_id. It is clear about what is returned in both branches, though the verb 'lists/returns' is implicit rather than stated.

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 routes the agent explicitly: browse a featured brand shop via sh_browse(shop_id=...), and use the returned ids as the brand_id filter for sh_browse. It does not cover when to prefer this over sh_shops or sh_categories, so it stops short of full when/when-not coverage.

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

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

Annotations already cover read-only, idempotent, non-destructive, open-world behavior, so the bar is lower. The description adds genuinely useful operational detail the annotations lack: pagination via next_cursor passed back as cursor with the other arguments unchanged, and the fallback behavior when no scope filter is given.

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 paragraphs with purpose first, then intent examples, then id sources and pagination. Every sentence carries information; the illustrative examples in quotes are dense but each maps to a distinct parameter pattern, so there is little waste.

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 15-parameter, zero-required browsing tool with no output schema, the definition covers scope, defaults, id provenance, and paging. Minor gaps remain around what a product entry contains and how multiple filters combine (e.g. brand_id plus category_id), which the agent must infer from the schema alone.

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 value beyond it by cross-referencing where each id comes from (sh_categories, sh_shops, sh_brands, sh_filters) and by showing how free-text intents map onto sort/filter combinations. It stops short of explaining interactions among the 15 parameters.

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 with the exact scope: listing products of a category, shop, tag or curated listing. The explicit inventory of what can be browsed, plus the note that omitting all of them browses all shops, cleanly separates it from siblings like sh_search and sh_deals.

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?

Maps concrete user intents to parameter combinations ("cheapest manteau in size L under 2,000,000 Toman", "biggest discounts in bags" -> discounted_only + biggest_discount), and points to sh_categories/sh_shops/sh_brands/sh_filters for obtaining ids. It never explicitly contrasts sh_browse with sh_search or sh_find_cheapest, so the when-not is left to inference.

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

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

Annotations already declare readOnly, idempotent, non-destructive and open-world, so safety is covered. The description adds genuinely non-structured behavior: the page contains product rows with prices plus tabs, and tabs are not resolved inline but must be fetched via sh_browse or sh_deals. Pagination and the exact row/tab response shape remain undisclosed.

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 primary action and output, then the routing table for tab sources. No filler, though the backtick/arrow notation is terse enough to require a second read.

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 tool with full schema coverage and no output schema, the description supplies the essentials: what the page yields, how tabs resolve, and which sibling tools continue the flow. It omits pagination and whether per_row changes the returned structure, which are minor gaps.

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

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

Schema description coverage is 100%, so both `slug` and `per_row` are already documented in the schema, including the slug pattern, defaults and bounds. The description's mention of 'campaign or landing page' only loosely corroborates the slug semantics and adds no format or constraint detail, so the baseline of 3 applies.

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

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

States a specific verb ('open') and resource ('campaign or landing page') and enumerates the returned content (product rows with prices, tabs). It also distinguishes itself implicitly by routing tab sources to sh_browse and sh_deals, though the boundary versus sh_shop is not drawn explicitly.

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

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

Gives conditional routing: a tab whose source is `listing`, `shop_id` or `category_id` goes to sh_browse, and `flash_sale` goes to sh_deals. That is clear follow-up guidance, but there is no explicit statement of when to call sh_campaign instead of sh_shop or sh_search.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds real behavioral context beyond that: that a query switches the tool from a depth-limited listing to a full-depth search, and that counts are aggregates. Pagination and result-size limits are not mentioned.

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 with the output contents front-loaded, followed by the downstream use and the query/max_level behavior. No filler or redundancy.

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

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

With no output schema, the description carries responsibility for return values and does describe them (ids, paths, levels, product/shop counts). The parameter interaction is covered too. It stops short of describing ordering, size, or pagination of the returned tree.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema does not: the interaction between the two parameters (max_level applies only when query is absent; a query searches every level). That is genuine semantic value above the per-field descriptions.

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 category tree) and enumerates the returned fields (ids, URL paths, levels, product/shop counts), which distinguishes it cleanly from siblings like sh_brands and sh_shops. An agent knows exactly what this tool produces.

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 agent: use it to obtain a category_id for sh_search / sh_browse / sh_find_cheapest, and explains the two operating modes (no query = levels up to max_level, query = all levels searched). No explicit when-not-to-use case is given, so it falls short of a full 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, openWorld), so the bar is lower. The description nonetheless adds useful behavior: results are ordered biggest-discount-first, include flash sales with end times, best sellers, themed rows, campaigns and discount codes. It stops short of disclosing freshness semantics (how 'today' is computed) or any rate/limit 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-loaded with the core resource and scope, followed by ordering, a usage trigger, and two pointer sentences. No filler; every clause carries information the 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?

With no output schema, the description compensates by enumerating what comes back (flash sale with end time, best sellers, themed rows, campaigns, shop discount codes) and the sort order. Combined with annotations covering safety, an agent has everything needed 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% for the single 'limit' parameter with a clear default and range, so the schema does the heavy lifting. The description adds no extra meaning about limit (e.g. how it distributes across deal types), which is the expected baseline when coverage is complete.

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 ('today's home-page deals... plus running campaigns and shop discount codes'), and names the scoping distinctions that separate it from siblings. An agent can tell it apart from sh_browse and sh_campaign 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?

Explicitly says 'Use for "what's on sale"' and routes two adjacent cases to alternatives: sh_campaign(slug) for opening a campaign and sh_browse(discounted_only=true, sort='biggest_discount') for category discounts. When-to-use and when-to-use-something-else 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 establish readOnly/idempotent/non-destructive/openWorld, so the safety profile is covered. The description adds genuinely new behavioral detail beyond them: price ranges are raw Toman with no server-side range enforcement, brand filtering must be resolved through sh_brands, and color filtering is unsupported. It does not describe the shape of the returned filter lists, which is the main remaining gap.

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

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

Purpose and scope are front-loaded in the first sentence, and the follow-up sentence packs prerequisites and caveats into one line. The trailing fragment ("No color filter works") is slightly clipped in tone but carries real information, so nothing is wasted.

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

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

With a one-parameter schema, no output schema, and read-only annotations, the description is nearly sufficient: it enumerates the filter domains an agent will receive and explains the category_id branch. It stops short of describing how the values are structured (list of ids vs. labels) or that size/sort tokens must be passed verbatim to sh_search.

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 category_id parameter, and the description's "with category_id, a category's sub-categories" essentially restates the schema text. It does imply the contrast case (omitting it yields global filter values), but that is inference rather than added specification, so the baseline 3 applies.

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

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

The description uses a concrete verb ("List") on a concrete resource ("the filter values sh_search / sh_browse accept") and enumerates the return categories: size systems/sizes, sorts, courier cities, and category sub-categories. By naming sh_search and sh_browse as the consumers, it is immediately distinguishable from siblings like sh_categories or sh_brands.

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 the triggering condition ("Use before filtering by size or city"), points to the alternative tool for a related need ("brand ids: sh_brands"), and closes off a dead end ("No color filter works"). That covers when to call it, what to call instead for adjacent data, and an explicit non-capability.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive). Beyond that the description discloses real behavior: it drops loose matches via match_all_words, drops unpriced items, reports the cheapest variant price, and explains the complete=false/scanned/scan pagination loop. Return format isn't described, but the operational traits are well surfaced.

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 purpose, then layers triggers, caveats, and pagination hints in compact prose. Dense but every clause carries information; minor terseness ('price to pay') doesn't hurt readability enough to drop below 4.

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

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

For a 6-param read tool with full schema coverage and safety annotations already handled, the description covers filtering behavior, the key cross-reference (sh_product for variants), and partial-result handling via complete/scan. No output schema, but the flat sorted list is implied, so remaining gaps are minor.

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?

With 100% schema coverage the baseline is 3, but the description adds genuine meaning: it explains that match_all_words filters loose matches and unpriced items are excluded, and that 'scan' governs how far past the results pagination goes. This clarifies the intent behind scan/limit beyond the terse 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 ('Find the cheapest in-stock products for a keyword across all shops') and adds the differentiator of a single price-sorted list. It doesn't explicitly name the sibling it is not (unlike a 'use X instead' pattern), but the scope is unambiguous enough to distinguish it from sh_search or sh_browse.

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 the lowest price of X' gives a clear positive trigger, and it routes the user to sh_product for size/color variant checks. It stops short of explicit when-not-to-use or naming alternative siblings for broader searches, so it's clear context rather than a full routing guide.

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, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds genuine behavioral value by spelling out the shape of the returned payload (variants each carrying their own price and stock, trust signals on the selling shop) — information the annotations do not convey. It stops short of noting any rate limiting or truncation behavior beyond what the full_text param implies.

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 what-it-returns inventory is front-loaded and the routing alternatives are compressed into a single dense line with no filler. The first sentence is a long comma-chained list, which is efficient but slightly taxing to parse; otherwise 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?

There is no output schema, so the description must carry the burden of describing return content — and it does, enumerating every significant field of the product record. For a two-parameter, single-record lookup with annotations covering safety, nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100%, so both product_id and full_text are already documented in the schema, including the "uncut" semantics of full_text and the example id. The description only alludes to these fields indirectly by listing size guide and description as part of the record. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description opens with a specific verb+resource ("Get one product's full record") and enumerates exactly what that record contains — price, per-variant price/stock, size guide, description, tags, shop trust signals, site link. That level of detail lets an agent distinguish this from sh_similar, sh_browse, and sh_shop 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 the triggering condition ("when the user picks a product"), the purpose of the call (check size/color stock and shop trustworthiness), and then names three concrete alternatives with the parameter that selects each: sh_similar for the same item elsewhere, sh_browse(shop_id=...) for more from the shop, sh_browse(tag=...) for related items. This is explicit routing, not 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=true, idempotentHint=true, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds behavior beyond that: the shape of each result (price to pay, discount, stock, selling shop) and the cursor round-trip for paging. It stops short of stating rate limits or result-count behavior, so it is strong but not exhaustive.

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 purpose then routing then pagination; every line carries information. The telegraphic fragment style ('Variants (size, color, stock): sh_product') is dense but readable, with 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?

For a 13-parameter search with full schema coverage and no output schema, the description supplies the missing routing layer and the pagination contract. It does not need to explain return values, but it could say more about how the many filters combine or what an empty result means, which keeps it short of 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 description coverage is 100%, so the baseline is 3 and the schema already documents city, sort, sizes, price bounds, category and the rest with examples. The description's only parameter-adjacent content is the cursor instruction, which largely restates the schema's own 'next_cursor of the previous reply' note, so it adds little 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?

Starts with a specific verb+resource ('Search products across all shops by keyword') and immediately lists what each result carries (price to pay, discount, stock, selling shop). It also names the two most confusable siblings, sh_find_cheapest and sh_product, so an agent can separate this broad search from the cheapest-only and variant-lookup 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 entry condition ('Use first for "price of X" / "where to buy X"') and routes two distinct cases to named alternatives: sh_find_cheapest for a flat cheapest list and sh_product for size/color/stock variants. It closes the loop with a pagination rule ('pass next_cursor back as cursor'), 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 and destructiveHint=false, so the safety profile is covered. The description adds useful context about what data is returned, but says nothing about pagination, rate limits, or how 'similar_shops'/'full_text' change the payload.

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 clauses, front-loaded with the resource and payload, followed by usage and cross-references. Every sentence carries information; 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?

There is no output schema, but the description compensates by enumerating the profile fields returned. It omits any note on response shape or size limits, so it is slightly short of fully complete, but adequate for a read-only profile fetch.

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 'shop', 'full_text' and 'similar_shops' are already documented in the schema. The description adds no syntax, format, or default guidance beyond that, which is the expected baseline when the schema does the heavy lifting.

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

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

States a specific verb ('Get') and resource ('shop's profile') and enumerates the returned content: ratings, buyer survey %, followers, product count, categories, courier city, contacts, website. It also differentiates itself from siblings by routing product and brand lookups elsewhere.

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 ('judge whether a shop is trustworthy') and names the alternatives with their conditions: products via sh_browse(shop_id=...) or sh_search(shop_id=...), brands via sh_brands. 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 readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety and mutation profile is fully covered externally. The description adds only the returned attribute list; it says nothing about result counts, pagination interplay with page/limit, or rate limits, so the added behavioral context is modest.

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

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

Two sentences, front-loaded with purpose followed by usage, with no filler. The second sentence's embedded example is slightly awkwardly punctuated but still earns its place by demonstrating a realistic invocation.

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 7-parameter, zero-required, no-output-schema search tool, the description covers filters, returned fields, and downstream routing well. It is thin on pagination/result-volume expectations and on how the default 'relevance' ranking behaves, which are the remaining gaps for an agent planning a query.

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 all seven parameters are documented in the schema itself and the baseline is 3. The description's phrasing ('by name, category group, gender or courier city') largely restates the schema's query/category_group/gender/city fields rather than adding syntax, format, or interaction rules; the only genuine additions are the 'courier city' gloss and the order='most_followed' usage example.

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

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

The description opens with a specific verb and resource ('Find shops') and enumerates the exact filter dimensions (name, category group, gender, courier city), which lets an agent distinguish it from siblings like sh_search or sh_browse. It also states what each result carries (rating, surveys, followers, product count), so the tool's output surface is identifiable 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?

It explicitly says the tool is for obtaining a shop_id for downstream calls to sh_shop / sh_browse / sh_search, and gives a concrete example query with the order parameter ('best-known women's clothing shops in Tehran'). It does not, however, state when NOT to use it versus siblings such as sh_filters, sh_categories, or sh_brands, so the routing guidance is clear but incomplete.

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 structurally. The description adds one genuine behavioral fact beyond that ('itself left out') and the cross-shop search scope, but says nothing about result volume, ordering behavior, or how results are aggregated across shops.

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, no filler, with the core action front-loaded and usage guidance second. The parenthetical exclusion note is placed immediately after the action it qualifies.

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

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

For a 5-parameter read-only tool with 100% schema coverage and no output schema, the description covers purpose, triggers, and the key parameter pairing. It stops short of describing what the returned product records contain or how the cross-shop results are ordered beyond the sort parameter.

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

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

Schema description coverage is 100%, so baseline is 3. The description exceeds that by tying parameter values to intent (kind='visual' with sort='cheapest' for the cheaper-alternative use case), which is meaning the schema enumerations alone do not convey.

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

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

States a specific verb and resource ('find products like this one') plus a scope qualifier ('at other shops') that clearly separates it from sh_search (query-based) and sh_product (single-item detail). The exclusion of the source product is stated explicitly, so an agent knows exactly what the result set contains.

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 trigger conditions ('out of stock or too expensive') and even prescribes a parameter combination for the cheaper-item goal (kind='visual', sort='cheapest'). It does not, however, distinguish itself from the closest sibling sh_find_cheapest, leaving some routing ambiguity.

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