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 value by disclosing the return shape (plain text) and a side output (category id) that the annotations cannot express.

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

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

Two short sentences with zero filler; the core action and return format come first, and the workflow hint follows. Every clause carries information.

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

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

With an output schema, full parameter descriptions, and a complete annotation set, the only thing the description must add is workflow placement, which it does. Nothing needed to invoke this simple read tool 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%: both parameters are documented in the schema, including the slug example and the truncation semantics of max_chars. The description adds no parameter 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 ('Read one Shopino blog post'), names the output format (plain text), and adds a distinguishing detail (returns the category id for sh_browse). An agent can separate this from sh_blog_search, which finds posts rather than fetching one.

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 sequences the tool ('Use after sh_blog_search') and states the goal ('answer style questions with the post's advice'). It gives clear context but names no when-not condition or alternative for the case where a post is unknown.

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

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

Annotations already declare readOnly, idempotent, openWorld, non-destructive, so the safety profile is covered. The description usefully adds behavior beyond that: results are ordered newest first and omitting the query returns the latest posts. It doesn't discuss paging behavior, though the schema documents it.

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?

Compact and front-loaded, with scope and ordering in the first sentence and the workflow in the second. The parenthetical content list is slightly dense but every line carries information; nothing is redundant.

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

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

An output schema exists, so return values need not be explained. Between the scope statement, the empty-query behavior, and the sibling routing, an agent has everything needed to select and call this tool correctly.

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

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

Schema coverage is 100%, so both parameters are already documented, giving a baseline of 3. The description adds real meaning for the nullable query parameter by stating that an omitted query returns the latest posts, which the schema's 'default: null' does not explain.

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 Shopino blog') plus its content scope (style guides, model galleries) and ordering (newest first). It is clearly distinguishable from siblings like sh_search (products) and sh_blog_post (read a single post).

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 the triggering question ('what is in fashion or which model to choose') and lays out the follow-on workflow: read with sh_blog_post(slug), then find products with sh_search. It both says when to use it and which sibling to use next.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the description's added value is the dual-mode semantics and the 'only watch shops have brands' constraint, which prevents a failed call. It adds no notes on return shape, but an output schema exists so that burden is lifted.

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 conditional structure is front-loaded and each sentence carries information, but the heavy parenthetical nesting makes it denser than it needs to be. Still, no sentence is filler.

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

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

With an output schema present, one optional parameter, and full annotation coverage, the description supplies everything an agent needs: both modes, the downstream use of the returned brand ids, and the eligibility constraint. Nothing material is missing.

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

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

Schema coverage is 100%, so the baseline would be 3, but the description genuinely adds meaning beyond the schema by defining what the absence of shop_id returns versus what passing it returns. The schema alone only documents the positive case.

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

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

The description states a specific resource (brands) and splits it into two clearly distinguished behaviors based on the presence of shop_id, which an agent can act on directly. It also disambiguates from siblings by pointing at sh_browse and the brand_id filter of sh_search.

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

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

It gives explicit when-to-use cases ('show me brand X' to find its shop, or to filter a watch shop by brand) and names the concrete alternative tools (sh_browse, sh_search) plus the constraint that only watch shops carry brands. Nothing about routing 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, idempotentHint and non-destructive, so the safety profile is covered. The description adds genuinely useful behavior: pagination via next_cursor with identical other arguments, and the fact that an unfiltered call spans all shops. It does not discuss result volume, ranking caveats, or rate 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?

Dense but front-loaded: purpose first, then example invocations, then fallback behavior, then id lookups, then routing, then pagination. No filler sentences; the telegraphic style is appropriate for a high-parameter browse tool.

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

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

An output schema exists, so return values need not be explained, and all 15 parameters carry schema descriptions. Combined with the description's coverage of pagination, defaults, id provenance and sibling routing, 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%, so every parameter is already documented in the schema, including id sources, size systems and filter applicability per tag/listing. The description restates id sources and notes the discounted_only + biggest_discount combination, which is marginal added value over structured fields. Baseline 3 applies.

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

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

Opens with a specific verb (List) and enumerates the exact resources it browses (category, shop, tag, curated listing), plus sorting/price/filter scope. It is immediately distinguishable from sh_search (query-driven) and sh_product (single-item details), both of which are named.

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

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

Gives concrete when-to-use examples ('cheapest women's manteau in size L under 2,000,000 Toman', 'biggest discounts in bags'), states the no-filter fallback behavior (browses all shops, e.g. today's discounts), and routes to siblings for ids (sh_categories, sh_shops, sh_brands, sh_filters) and for details (sh_product). Alternatives and conditions are 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 declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds the structural fact that tab contents are not resolved in-place but must be fetched via other tools, which is genuinely useful behavioral context. It does not mention pagination, auth, or how many tabs/rows a real campaign returns, so it stays at a solid-but-not-rich 3.

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

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

Front-loads the core action in one sentence, then follows with a compact, structured mapping of tab types to sibling calls. Nearly every token earns its place; the arrow notation is dense but readable and avoids narrative padding.

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

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

With an output schema present, return values need not be explained, and annotations carry the safety profile. Parameters are fully described in the schema, and the tab-routing note closes the main ambiguity (where product content actually comes from). Only minor gaps remain, such as no note on slug validity beyond the pattern or on empty/invalid campaigns.

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 slug (with pattern, examples and source) and per_row (default 6, range 1-12) are fully documented in the schema. The description adds no parameter-level detail beyond what the schema states, 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 (Open) and resource (Shopino campaign or landing page) and names what it returns: product rows with prices and tabs. The tab-routing sentence explicitly distinguishes this tool from sibling surfaces (sh_browse, sh_deals), so an agent can tell what this tool owns versus what it delegates.

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 mapping of tab types to the sibling tool and parameter that resolves them (listing/shop_id/category_id -> sh_browse, flash_sale -> sh_deals), which is real routing guidance. It stops short of an explicit 'use this instead of X when Y' statement, but the slug description ('campaign slug from sh_deals campaigns') implies the discovery-then-open workflow.

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 mark this readOnly/idempotent/non-destructive, and the description goes beyond that with real behavioral detail: without a query only levels up to max_level are returned, with a query every level is searched, and the payload includes counts. That conditional scope behavior isn't derivable 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?

Two short paragraphs, front-loaded with what is returned and then how to use it. The parenthetical category enumeration ('clothing, bags, shoes, ...') is mildly expendable but adds domain grounding without bloating the text.

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

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

An output schema exists, so the returned-field list is partly redundant, but the description covers the mode selection, parameter interaction, and downstream purpose needed to call it correctly. Nothing operationally important is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds the interaction between the two parameters — query triggers a full-depth search while max_level only applies when no query is given. That cross-parameter semantics is not stated in 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+resource ('List Shopino's category tree') and enumerates what is returned: ids, URL paths, levels, plus product and shop counts. That detail plus the category examples clearly separate it from siblings like sh_brands and sh_filters.

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 to get a category_id for sh_search / sh_browse / sh_find_cheapest', naming three sibling tools and the condition that selects them. It also states the query vs no-query behavior, so the agent knows which mode to pick.

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

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

Annotations already declare readOnly, idempotent, non-destructive and open-world, so the safety profile is covered. The description adds genuinely new behavioral detail: results are ordered biggest-discount-first and the payload includes flash-sale end time and shop discount codes – facts an agent cannot derive 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, then supporting content detail, then usage and alternatives in two tight sentences. No filler and no repetition of structured fields.

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

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

An output schema exists, so return values need no explanation; the description still conveys scope, ordering, and when to prefer siblings. For a read-only single-parameter listing tool, everything needed to select and invoke it is present.

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

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

Only one parameter (limit) and schema description coverage is 100%, so the schema already documents it. The description says nothing about the limit or its default of 30, which is acceptable but adds no value over the schema – the baseline 3.

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

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

States a specific verb+resource ('List today's featured deals from the Shopino home page') and enumerates the content rows returned (flash sale, best sellers, newest, themed, campaigns, discount codes). It is immediately distinguishable from sh_browse, sh_search and sh_campaign by naming 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?

Gives an explicit trigger ('Use for "what's on sale" / "best discounts today"') and routes to alternatives with their conditions: sh_campaign(slug) to open a campaign, sh_browse(discounted_only=true, sort='biggest_discount') for every discounted product in a category.

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 non-obvious behavioral context: price is unconstrained by Toman range, brand filtering is watches-only, and the color filter is non-functional. It does not discuss pagination or result size, which is the only gap.

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

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

Front-loaded with the core deliverable in sentence one, followed by usage triggers and caveats. The parenthetical enumerations are dense but each earns its place; the trailing color-filter aside is slightly tangential but genuinely useful.

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

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

With an output schema present, annotations covering safety, and the parameter fully documented, the description's remaining job is to say when and why to call it — which it does, including cross-tool routing and known dead ends.

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

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

Schema coverage is 100% and the single parameter is already documented in the schema. The description adds a semantic layer the schema lacks: that supplying category_id switches the output to that category's sub-categories, which clarifies the mode change rather than just the field type.

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 (list) and resource (filter values accepted by sh_search/sh_browse), then enumerates what those values cover: size systems, sort orders, cities, and sub-categories. It explicitly ties itself to the sibling tools whose behavior it describes, making it instantly distinguishable from 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 gives an explicit trigger ("Use before filtering by size or city") and routes the agent elsewhere for related data: price is a free-range input, brand ids come from sh_brands. It also warns that the site's color filter is broken, which prevents a wasted call path.

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, yet the description adds real behavioral context: results are sorted by price to pay, loose matches lacking a query word and price-less items are dropped, and complete=false indicates matches continue past `scanned` requiring a higher scan. This is substantive disclosure beyond the structured data.

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 sorting behavior are front-loaded, then usage, then edge cases, with every sentence carrying information. Formatting is a bit run-on/inline rather than cleanly bulleted, which slightly hurts scannability, but there is no filler.

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

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

For an open-world 6-parameter tool with an output schema, the description covers what the list contains, how it is ordered, how to narrow, how variants relate to price, and the pagination/scan caveat. An agent has everything needed to call it correctly without guessing.

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

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

Schema description coverage is 100%, so the 3 baseline applies, but the description adds genuine meaning: it explains that match_all_words drops loose title matches, ties category_id to sh_categories and city to sh_filters, and explains scan/complete interplay. That goes beyond the schema's per-parameter 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 and scope: find the cheapest in-stock products for a keyword across all shops, returned as one flat list sorted by price to pay. An agent can distinguish it from sh_search, sh_deals and sh_similar without opening schemas, since the cheapest-price intent is explicit in both name and description.

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

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

'Use when the user wants the lowest price for X' gives a clear trigger condition, and it routes refinement to siblings (category_id via sh_categories, city via sh_filters, variant checks via sh_product). It doesn't explicitly state when NOT to use it versus sh_search/sh_deals, so it falls short of full exclusion guidance, but the positive routing is strong.

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 by enumerating the fields a record carries (variants, stock, shop rating, buyer survey), but says nothing about auth needs, rate limits, or behavior when the product id is stale/removed. Adequate but not rich beyond structured data.

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 a dense field list, then routing guidance. Every clause is informative, though the long comma-separated field inventory is close to the limit of what belongs in a description when an output schema already exists.

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-id lookup with full schema coverage, complete annotations, and an output schema, an agent needs purpose, trigger, and sibling routing — all present. Nothing required to invoke or interpret the call 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?

Only one parameter, and schema coverage is 100% — the schema already documents product_id with bounds (1..100000000) and an example id (2578018) plus its provenance. The description adds no additional parameter semantics, 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 and resource ('Get one product's full record') and then enumerates the actual contents (price/discount in Toman, variants with stock, size guide, shop rating, original link). This clearly distinguishes it from sh_search/sh_browse (which find products) and sh_similar (which finds substitutes).

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

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

Gives an explicit trigger ('Use after sh_search / sh_browse when the user picks a product') plus the intent behind the call (check size/color stock, price, shop trustworthiness), and names concrete alternatives with argument hints: sh_similar, sh_browse(shop_id=...), sh_browse(tag=...).

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, openWorld, idempotent, and non-destructive. The description adds operational context: city filter means same-day courier availability, and cursor pagination requires keeping other args constant. No safety or mutation details are contradicted, but no additional auth or rate-limit behavior is disclosed.

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

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

Front-loaded with purpose then usage guidance, with no wasted sentences. Each sentence (purpose, usage, alternatives, pagination) earns its place for a complex 13-parameter tool.

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

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

All structured fields are rich: 100% schema coverage, full annotations, and an output schema. The description provides routing guidance and pagination behavior, leaving return values to the output schema. Nothing critical is missing for an agent 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%, so all 13 parameters are fully documented in the schema. The description echoes some filters (category, shop, size, price, city) but adds no new syntax or constraints beyond what the schema provides. 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 ('Search products') and resource with scope ('across all Shopino shops by keyword') plus what data is returned (price, discount, stock, selling shop). It also distinguishes itself from sh_find_cheapest and sh_product, so an agent can route correctly.

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

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

Explicitly tells the agent to use this first for price/buy queries, names filters to narrow results, and directs to alternatives for cheapest matches (sh_find_cheapest) and variant details (sh_product). It also explains pagination via cursor, covering when to use, when not to, and alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered. The description adds the shape of the returned profile (survey percentages, courier city), but says nothing about permissions, rate limits, or freshness of ratings, so it adds only modest context beyond structured fields.

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

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

Two sentences, front-loaded with the verb and payload, followed by selection guidance and cross-references. The field enumeration is dense but every item earns its place by helping the agent judge relevance.

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

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

With an output schema present, annotations covering the safety profile, and 100% schema description coverage, the description only needs to supply purpose and routing — both are present and unambiguous. Nothing required for correct invocation is missing.

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

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

Schema description coverage is 100% and both parameters ('shop' id/username pattern, 'similar_shops' boolean) are documented in the schema, so the baseline is 3. The description never mentions the shop identifier semantics or the similar-shops option, so it adds nothing 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 ('Get a shop's profile') and enumerates the exact contents (rating, buyer survey, followers, product count, categories, courier city, contacts, website), so an agent knows both what it returns and how it differs from sh_product / sh_shops. No ambiguity about scope.

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 ('judge whether a shop is trustworthy before buying, or to see what it sells') plus concrete routing to alternatives with parameter hints: products via sh_browse(shop_id=...) or sh_search(shop_id=...), brands via sh_brands. This is exactly the sibling differentiation an agent needs.

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 genuinely non-structured context: the data universe is Shopino shops including Instagram shops, and each result carries rating, buyer-survey count, followers and product count. It does not discuss pagination or result limits, which is the only real gap.

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

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

Two sentences, front-loaded with the verb and resource before the routing advice. The second sentence packs several downstream tool references and an example, which is dense but each clause carries routing value.

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

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

With an output schema present and 100% parameter coverage, the description only needs to establish the discovery role, the data scope, and downstream consumers — all of which it does. Minor omission: no note on pagination semantics or result-set size limits.

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 every parameter (city, query, gender, category_group, order, page, limit) is already documented in the schema with examples. The description restates the same filter fields without adding syntax or interaction rules, so it sits at the baseline 3.

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

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

States a specific verb+resource ('Find Shopino shops') and enumerates the filterable dimensions (name, category group, gender, courier city) plus the returned attributes, so the agent knows exactly what surface this tool covers. It also names the sibling tools it feeds (sh_shop, sh_browse, sh_search), which cleanly separates it from 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 says when to use it: to obtain a shop_id for sh_shop / sh_browse(shop_id=...) / sh_search(shop_id=...), and gives a worked example ('best-known women's clothing shops with delivery in Tehran' → order='most_followed'). It stops short of excluding the other discovery siblings (sh_filters, sh_categories, sh_brands), so the 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 declare this a read-only, idempotent, open-world, non-destructive operation, so the safety profile is covered. The description adds a real behavioral detail beyond them: the queried product itself is excluded from results, which shapes how the agent interprets the output set. It does not discuss result volume or defaults, but that is largely schema territory.

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 the core action and followed by the usage conditions; no padding or repetition of schema details. 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 an output schema present, return-value explanation is unnecessary, and the description still names the key payload fields. Purpose, trigger conditions, scope exclusion, and a recommended parameter pairing are all present, leaving nothing material missing for correct invocation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description goes beyond that by recommending a specific parameter combination ('kind=\'visual\', sort=\'cheapest\') tied to a concrete user goal, which is semantic guidance the schema's per-field text 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?

The description states a concrete verb and resource ('Find products like this one at other shops') and enumerates the data returned (prices, discount, stock, shop), plus the scope exclusion ('The product itself is left out'). It is clearly distinguishable from sh_product or sh_search in intent, though it does not explicitly name any sibling it competes with, so it falls just short of a 5.

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

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

It gives explicit triggering conditions: use when the product is out of stock, too expensive, or to check whether another shop sells it cheaper. It even supplies the parameter pairing (kind='visual', sort='cheapest') for that scenario. It stops short of naming alternatives such as sh_find_cheapest for price-hunting, so no exclusion routing is provided.

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