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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so safety and idempotency are covered. The description adds that output is plain text with linked products/categories, which is meaningful behavioral context. However with no output schema, more detail on return structure and the truncation behavior would help.

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 plus a routing sentence, front-loaded with the core operation. Every clause earns its place by pointing to the source tool and follow-up tools.

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 2-param read tool with full schema coverage and rich annotations, the description covers purpose, sequencing, and how to use the linked data. It does not explain the maximum text length or truncation behavior beyond the schema, but the overall picture is complete enough to invoke 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 both post_id (source and example) and max_chars (truncation semantics, default and range) are fully documented in the schema. The description adds no format or syntax detail beyond what the schema provides, so 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 (read) and resource (one blog post), plus its scope: plain text with linked products and categories. It also references the sibling ab_blog_posts as the source of post ids. It is clear, though it doesn't explicitly contrast against other read tools like ab_product.

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 the sequencing context: use after ab_blog_posts to answer care questions. It names the right follow-up tools for the linked data (ab_search by name, ab_browse by slug). No explicit when-not-to-use is given, but the workflow guidance is concrete and useful.

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 behavior, so the safety profile is covered. The description adds the newest-first ordering and the list-then-read pattern, which is useful, but says nothing about pagination limits (100 pages, 30 max per page) or the shape of returned post objects. With annotations carrying the safety burden, a 3 is appropriate.

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

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

Two tight sentences with zero filler: the first defines the resource and ordering, the second defines when to use it and the follow-up tool. Front-loaded and every clause earns its place.

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

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

For a read-only list tool with full schema coverage and rich annotations, the description covers purpose, ordering, and the list-then-read workflow. It does not describe return payload or pagination behavior, but no output schema exists and those gaps are minor here.

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 page, limit, and query with constraints and an example. The description mentions 'newest first' which reinforces the ordering of page, but adds no further syntax or format detail. Baseline 3 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 (List) and resource (Asal Banoo blog posts), enumerates the content types covered (care guides, routines, comparisons), and specifies ordering (newest first). An agent can distinguish this listing tool from the singular ab_blog_post reader without inspecting either schema.

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

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

Explicitly names the use case (advice questions), gives concrete example queries, and prescribes a two-step workflow: find a matching post here, then read it with ab_blog_post. That routing between the sibling tools is exactly what 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, openWorld and non-destructive, so the safety profile is covered. The description adds real context beyond them: the ~250 total size, the biggest-first ordering, and the recommendation to match on Latin slugs rather than Persian spellings.

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 what the tool returns and what it is for; every clause carries information and 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 still names the returned fields (slug, product count) and the ordering, and the limit/query behavior lives in a fully documented schema. It stops short of describing pagination or whether the ~250 total is ever truncated by limit.

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 note that the Latin slug usually matches better than Persian spellings directly improves how the optional `query` filter should be constructed, beyond the schema's own examples.

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 brands') and immediately qualifies the result set: ~250 entries, returned with slugs and product counts, ordered biggest first. An agent knows exactly what it gets and how it differs from a generic listing.

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 the brand slug for ab_browse / ab_filters', which names the downstream siblings that consume this output. No when-not guidance (e.g. when ab_categories would be the better list tool), so it falls short of a 5.

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

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

Annotations already cover the safety profile thoroughly (readOnly, idempotent, openWorld, non-destructive), lowering the bar. The description adds useful behavioral context that listings default to in-stock-first ordering, but does not disclose pagination limits, how the maxProperties=5 filter cap behaves, or result-count semantics.

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 core purpose is front-loaded in the first sentence, followed by examples and then sibling routing in a compact three-block layout. Slightly dense but every element (examples, slug provenance, routing) earns its place.

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

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

For a 10-parameter, all-optional browse tool with no output schema and rich annotations, the description covers purpose, examples, input provenance and sibling routing adequately. Minor gaps remain around pagination behavior and how multiple filters compose, but nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real value beyond the schema by naming the upstream tools that supply valid category, brand and filter values. It does not explain how category+brand combine or how filters interact with the price range, so it does not reach a 5.

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 products of a category or brand') plus the scope of filters, and gives concrete query examples. It partially distinguishes itself by routing to ab_product and ab_reviews, but never explains how it differs from ab_search or ab_find_cheapest, even though the example 'cheapest shampoo for oily hair' overlaps heavily with those siblings.

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

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

Gives explicit usage examples and the key routing rule that slug inputs must come from ab_categories, ab_brands and ab_filters, which tells the agent the correct call sequence. It stops short of stating when to prefer ab_search or ab_find_cheapest instead, so the most important boundary for this tool 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/openWorld/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely useful data semantics the annotations cannot convey: the list is ~70 entries and the count includes out-of-stock products. No pagination or ordering note, but the set is small enough that this matters little.

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 core sentence is front-loaded and dense with useful facts (verb, resource, scale, return fields), and the routing sentence follows immediately. The trailing 'parent'/count line is partially wasted because 'parent' maps to nothing in the schema, costing it 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 single-parameter, read-only listing tool with no output schema and rich annotations, the description covers scope, purpose, return fields, and routing to consumers. The only blemish is the orphaned 'parent' reference, which is a minor documentation inconsistency rather than a missing capability.

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% for the single 'query' parameter, so the baseline is 3. The description's parameter line instead describes 'parent = parent category id (0 = top level)', a parameter that does not exist in the schema, which is stale or mismatched text rather than added meaning; the 'count includes out-of-stock' note is the only real semantic addition.

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 useful scope: 'List product categories (about 70) with slugs and counts.' The cardinality and the returned fields (slugs, counts) tell an agent exactly what it gets. It does not directly contrast itself with the close peer ab_brands, so differentiation is implied 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?

'Use to get a category slug for ab_browse / ab_filters' names the downstream tools and the reason to call this one, which is real routing guidance. It omits any when-not condition (e.g. when ab_brands or ab_search is the better choice), so it falls short of full alternative 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 the safety profile (readOnly, idempotent, non-destructive, openWorld), so the description's value-add is the truncation behavior: ranking is limited to the first 300 deals and complete=false signals more exist, with total available. That is genuinely useful non-obvious behavior 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?

Three tight clauses: what it lists and how it ranks, when to use it, and the pagination caveat. Leading sentence front-loads the essential behavior with zero filler.

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

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

With no output schema, the description responsibly surfaces the one return-value detail an agent needs (complete flag and total) that would otherwise be invisible. Filtering, ranking, and result-size behavior are all covered for a simple two-parameter read tool.

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

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

Schema description coverage is 100% and the schema already documents both parameters, including the category slug source (ab_categories) and the example slugs plus the limit bound. The description's category guidance therefore largely repeats structured data rather than adding new semantics.

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), resource (discounted in-stock products) and scope/ordering (biggest discount first), which separates it from siblings like ab_find_cheapest (cheapest) and ab_search (general query). An agent can pick this tool 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 concrete user-intent triggers ("what's on sale" / "discounted sunscreens") and notes the category filter is optional and single-valued. It does not explicitly name a competing sibling or state when NOT to use it, which keeps it short of a 5.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds genuine context beyond that: the response carries in-stock counts and the returned attributes are directly reusable as ab_browse filters. Pagination/rate-limit behavior is not mentioned, keeping it below a 5.

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

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

Two tight sentences: the first defines the resource and its output fields, the second front-loads the workflow directive. No filler or restatement of the 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?

With no output schema, the description must characterize the return, and it does so by naming the attribute dimensions and in-stock counts plus the filter format to reuse downstream. Minor gaps remain around overall response structure and any pagination, so not a full 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 both brand and category slugs are fully documented in the schema (including source tools and patterns). The description adds the return-shape convention {attribute: [value, ...]} but no new parameter-level detail, matching the baseline 3 for schema-dominant definitions.

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 (attribute filters of a category or brand), and enumerates the concrete attribute kinds returned (volume, hair/skin type, gender, origin) plus the in-stock counts. This lets an agent distinguish it from ab_categories/ab_brands (which list the taxonomies themselves) and from ab_browse (which consumes the 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 positions the tool relative to a sibling: 'Use before ab_browse for a size or type,' and even shows the pass-through form {attribute: [value, ...]}. It does not clarify when to supply brand versus category, nor any exclusions, 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 declare read-only, idempotent, open-world, non-destructive. The description adds real behavioral context beyond them: default word-matching on titles only, that site search also matches descriptions, and crucially the meaning of complete=false and the need to raise 'scan' to reach more matches.

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 usage and mechanics in short sentences. Slightly choppy line breaks and an unlabeled 'scanned' reference cost it a bit, but there is little wasted text.

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

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

With no output schema, the description usefully sketches the return shape (a price-sorted list) and the coverage signal (complete/scanned). It omits any mention of currency edge cases or empty-result behavior, but is otherwise sufficient for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes further by explaining result ordering (price, in Toman) and the interplay between 'scanned' and complete=false, which the schema fields 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 the cheapest in-stock products for a keyword, one list sorted by price (Toman).' The scope (in-stock, price-sorted, single list) clearly separates it from a general search, but no sibling is named to make the distinction explicit.

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 use case ('Use for the lowest price of X') and routes to an alternative ('Check ab_product for the size you need'). It stops short of stating when NOT to use it or naming ab_search as the general-purpose counterpart.

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 the safety profile is covered. The description adds useful value by disclosing return detail, notably 'exact count when low' for stock, which is a non-obvious behavior. It doesn't discuss failure modes (e.g., invalid product_id) or formatting, but is strong enough.

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: first front-loads the returned fields, second gives usage context and the review alternative. 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?

A read-only, single-parameter lookup documented rich enough for an agent to call correctly; return fields are enumerated though no output schema exists. Minor gap: no mention of behaviour when the id doesn't exist, but the core is complete.

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

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

Schema coverage is 100%: product_id is fully documented with source, type, range, and example. The description adds no parameter syntax details beyond referencing where to obtain the id, so baseline 3 is appropriate.

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

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

States a specific verb+resource ('Get one product') and then enumerates precisely what is returned (price/discount, stock, variants, brand, rating, facts, images). Clearly distinguished from siblings, which are search/browse/review tools.

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

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

Explicitly states when to use it ('after ab_search / ab_browse when the user picks a product') and routes related needs to a named sibling ('Reviews: ab_reviews'). This is a complete when-to-use and alternative routing.

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

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

Goes well beyond the readOnly/idempotent annotations: discloses 400-char truncation with the '…' marker and the full_text escape hatch, Jalali date format, rating=null meaning a question rather than a review, verified_buyer semantics, and the fact that count/star_counts cover the whole page while truncated=true signals more than `limit` exist. These are behavioral traits the annotations cannot convey.

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

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

Front-loads the core action in the first clause and packs semantic details into compact parentheticals with no filler. It is dense and slightly telegraphic, but every sentence 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?

With no output schema, the description does the work of describing the return shape — rating, verified_buyer, count, star_counts, truncated, and the truncation marker — which is close to complete. It omits error behavior for an invalid product_id and any pagination path beyond a single limit, both minor gaps for a read tool with strong annotations.

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% (baseline 3), and the description adds genuine meaning on top of it: it ties full_text to the truncation rule and explains that the returned count/star_counts aggregates describe the page rather than the whole catalog. The exact limit semantics and product_id sourcing are largely left to the schema, which already documents them.

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: reads customer reviews and questions for a given product, with the shop's replies, newest first. That distinguishes it from siblings like ab_product and ab_search, which cover product data and discovery rather than user-generated review content.

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 — quality check, and extracting the shop's skin/hair advice from staff answers. It does not explicitly name an alternative tool or state when not to use it, but the stated contexts are clear enough to route an agent.

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

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

Annotations already cover read-only, idempotent, open-world, non-destructive, so the safety profile needs no restating. The description adds genuine behavioral context beyond them: matching is broad and spans title and description (so titles must be inspected rather than trusted as exact hits), and out_of_stock_matches is only populated when nothing is in stock. A return-field caveat like that is exactly the value-add expected at this bar.

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?

Extremely dense with no filler: purpose first, then routing alternatives, then the one non-obvious return detail. Every clause carries information an agent would otherwise have to discover by trial.

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 partly compensates by naming the returned fields per match and the out_of_stock_matches counter. Combined with 100% schema coverage across 7 parameters, an agent has enough to invoke correctly; only the full response envelope (pagination fields, result array name) is left implicit, which is a minor gap.

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

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

Schema description coverage is 100% and every parameter (page, sort, limit, query, min_price, max_price, in_stock_only) is documented in-schema with units, defaults, and bounds. The description adds only the notion of keyword matching, not new parameter semantics, 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+resource ('Search products by keyword') and immediately names what each match returns (price, discount, stock, rating), so the agent knows both the action and the payload shape. It is clearly separable from ab_find_cheapest, ab_browse, and ab_product, all 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?

Explicit when-to-use ('Use first for "price of X" / "do you have X"') plus three named alternatives with the exact condition that selects each: cheapest match → ab_find_cheapest, category/brand → ab_browse, one product's variants → ab_product. Routing is fully determined without opening other schemas.

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 the full safety profile (readOnly, idempotent, openWorld, non-destructive), so the description's added value is the disclosure that output shape varies by topic: FAQ comes back as Q/A pairs while other pages come back as text. That is genuine behavioral context beyond the annotations, though it says nothing about truncation or pagination behavior.

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

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

Two tight sentences, purpose front-loaded, and the example queries earn their place by directly aiding tool selection. 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?

There is no output schema, so the description carries some return-value burden and does so partially by describing the FAQ-vs-text output shapes; the topic semantics live in the schema. For a simple read-only lookup tool this is nearly complete, with only the missing truncation/default behavior as a minor gap.

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

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

Schema description coverage is 100% and the topic enum with per-value meanings plus the full_text truncation note are all in the schema, so the schema does the heavy lifting. The description adds no syntax or format detail about the parameters themselves, making the baseline 3 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 ('Read one of the shop's policy pages as plain text') and even specifies the return shape (FAQ as question/answer pairs, other pages as text). It is clearly distinct from the product/search-oriented siblings, but never names a sibling or explicitly contrasts scope, so it stops short of a 5.

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

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

Gives concrete trigger phrases ('how long does delivery take', 'do you ship with Tipax', 'can I return it', 'where is the shop') that map cleanly to the enum topics, which is strong context for routing. It does not name an alternative tool or state when NOT to use it (e.g. product questions should go to ab_search), so it falls short of 5.

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