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 that linked products and categories are returned, useful context, but does not mention truncation behavior or what happens when post_id is invalid. With annotations carrying the safety burden, this is moderate added value.

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, no filler, with the core purpose front-loaded and the workflow guidance second. Every sentence 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?

An output schema exists, so return-value documentation is not required, and the description covers purpose and workflow nicely. It could be slightly more complete by noting truncation semantics or error behavior for unknown post ids, but nothing essential is missing for correct invocation.

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

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

Schema description coverage is 100% and both parameters are documented there (post_id sourced from ab_blog_posts, max_chars truncation cutoff). The description adds no parameter-level detail, so the baseline 3 for schema-driven documentation 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') and clarifies the payload beyond the raw text ('plus the products and categories it links to'). It is clearly distinguishable from the sibling ab_blog_posts, which lists posts, whereas this reads a single 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 says when to use it ('Use after ab_blog_posts to answer care questions from the shop's own guides') and routes follow-up work to ab_search and ab_browse. It gives no when-not-to-use condition, but the sequencing and alternatives are clear enough for selection.

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, openWorld behavior, so the safety profile is covered. The description usefully adds result ordering and the kind of content returned, but omits anything about pagination behavior or result-size limits beyond what the schema states. Adequate, moderate added value.

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, front-loaded sentences with zero filler; the scope statement comes first and the usage routing second.

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 full annotation coverage, the description supplies exactly what is missing: what the tool lists, ordering, and how it fits into the read-one workflow. Nothing an agent needs to select or call it is absent.

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

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

Schema description coverage is 100%, so page, limit, and query are already documented in the schema. The description only hints at query usage via advice examples and adds no new syntax or format guidance; 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 (list blog posts) plus the content domain (skin/hair care guides, routines, comparisons) and ordering (newest first). It also implicitly separates itself from the singular sibling ab_blog_post, which it names as the follow-up read tool.

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 (advice-style questions) with two concrete example queries, and names the alternative workflow step ('find a matching post, then read it with ab_blog_post'). The agent knows both the trigger and the handoff.

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/openWorld, so the safety profile is covered. The description adds genuinely new behavior: default ordering by product count descending, approximate catalog size, and the Persian-vs-Latin slug matching quirk with concrete examples. It does not mention pagination or result caps, which keeps it short of a 5.

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

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

Three short sentences, front-loaded with the core action and scale, then usage routing, then the practical slug tip. No sentence is redundant with the name or schema.

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 described, and annotations carry the safety profile. With only two optional, fully documented parameters and an explicit usage routing hint, 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 parameters are already documented, including 'biggest first' for limit. The description only reinforces the sort order and hints at query values; it adds no syntax or matching-rule detail beyond what the schema states. 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 ('List the brands Asal Banoo sells') and adds distinguishing detail: scale (~250), fields returned (slugs and product counts), and ordering (biggest first). An agent can distinguish it from ab_categories or ab_filters without opening any schema.

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

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

Explicitly names the downstream consumer ('Use to get the brand slug for ab_browse / ab_filters'), which tells the agent when this tool is the right first step. It gives no explicit exclusion or negative case, but the routing intent is unambiguous.

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

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

Annotations already declare readOnly/idempotent/openWorld/non-destructive, so safety is covered. The description adds non-obvious behavior: 'Variable products show their cheapest variant as final_price and max_price as the top of the range', plus which sibling to consult for filters and details.

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 and scope, then examples, then slug sourcing, then edge-case behavior. Every sentence carries information; nothing is redundant with the schema.

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?

Covers purpose, filter vocabulary sources, cross-tool routing, and the one ambiguous return-value behavior, with an output schema present to carry the rest. An agent has everything needed to call this correctly.

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

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

Schema coverage is 100%, so the schema already documents all 10 parameters (baseline 3). The description still adds value beyond it: price units in Toman, the attribute-filter shape sourced from ab_filters, and the variant-price semantics of final_price/max_price.

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

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

Opens with a specific verb+resource+scope: 'List the products of a category or brand (or the whole shop)' and enumerates the filter dimensions. It also names the sibling tools that supply inputs and drill-downs (ab_categories, ab_brands, ab_filters, ab_product, ab_reviews), so an agent can place it in the tool graph without opening schemas.

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

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

Gives concrete natural-language queries it serves ('cheapest shampoo for oily hair', 'Graph brushes under 800,000 Toman') and explains that category, brand, both, or neither may be passed. It does not explicitly contrast with the closest siblings ab_search and ab_find_cheapest, so the routing for search-style requests is left to inference.

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

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

Annotations already declare read-only, idempotent, open-world behavior, so the bar is lower. The description still adds valuable semantics: the 'count includes out-of-stock products' caveat and the parent=0 top-level convention, which 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-loaded with purpose, followed by usage routing and the two key caveats. No filler sentences; 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?

Output schema exists so return values need not be described, and annotations cover safety. The description still supplies the cross-tool slug workflow and count semantics. Mildly incomplete in not clarifying query matching behavior, but adequate.

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 'query' parameter is fully documented in the schema including a Persian example, so the description need not repeat it. The description instead explains the domain convention for 'parent' (0 = top level), but parent is not in the schema; 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 (List) and resource (Asal Banoo's product categories), plus concrete scope (~70 categories across named domains) so the agent knows exactly what it returns. Distinct from siblings like ab_browse (navigation) and ab_filters (facets).

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: 'Use to get a category slug for ab_browse / ab_filters.' This directly routes the agent to the downstream tools that consume the output, which is exactly the guidance needed.

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

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

Annotations already declare read-only, idempotent, non-destructive and open-world, so the safety burden is covered. The description adds real behavioral context beyond that: result ordering by discount size and the expectation that most discounts sit around 10%, which shapes how an agent interprets empty or thin results.

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 lines with the core action and ordering front-loaded, followed by usage triggers and the optional category constraint. No filler and nothing restating the tool name or title.

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

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

Only two optional parameters, an output schema that covers return values, and rich annotations covering safety semantics. The description supplies the remaining gaps (ordering, use cases, category source), so 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% and both parameters already carry examples ('hair-shampoo', 'sunscreen') and bounds, so the baseline is 3. The description's contribution is the cross-tool routing hint that the slug comes from ab_categories, which is mildly useful but largely duplicative of 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 ('List the discounted in-stock products'), adds ordering ('biggest discount first') and an anchor to the site's known page, so an agent can distinguish it from ab_search and ab_find_cheapest without opening schemas.

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

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

Explicitly names the triggering intents ('what's on sale', 'discounted sunscreens') and points to ab_categories as the source of the optional category slug. It stops short of stating when NOT to use it versus ab_search or ab_find_cheapest, which would be needed for 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, non-destructive, open-world, so the safety profile is covered. The description adds real behavioral context beyond them: counts cover in-stock items only, and the output is intended as input to ab_browse filters.

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

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

Three tight sentences: purpose first, then usage routing, then a scoping note on counts. No filler, front-loaded.

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

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

Output schema exists so return values need no explanation, annotations cover safety, params are fully documented, and the description supplies the only missing piece: when and how to use this tool relative to ab_browse.

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 both params (brand, category slugs) are well documented, so baseline is 3. The description adds meaning by explaining the relationship between the returned attribute map and ab_browse's filters argument, which the schema does 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+resource: lists attribute filters of a category or brand listing, with concrete examples (volume, hair type, skin type) and notes each value carries a product count. It is clearly distinct from siblings like ab_browse and ab_categories.

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

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

Explicitly routes the agent: use before ab_browse when the user wants a size or type inside a category, and it even shows how to feed the result ({attribute: [value, ...]}) into ab_browse's filters. This is the when-to-use plus the inter-tool handoff.

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/openWorld, but the description adds substantive behavior beyond them: the site search also matches descriptions, so titles containing every query word are kept by default; variable products are listed at their cheapest variant only; and pagination is signaled via a 'complete' flag. This is meaningful operational context an agent could not derive from the schema alone.

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

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

Front-loaded with the core purpose, then usage, then the two edge-case behaviors. Every sentence earns its place, though the third paragraph's edge-case detail is dense enough that it slightly dilutes the crisp opening.

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

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

An output schema exists, so return values need not be explained, and the description covers the remaining gaps: filtering default, variable-product handling, and the scan/complete continuation loop. An agent has everything needed to call this correctly.

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

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

Schema coverage is 100%, so the baseline is 3, and the description adds real value on top: it gives the currency (Toman), explains the sorted-by-current-price ordering, and ties the 'complete' output to the 'scan' parameter. It doesn't restate limit/match_all_words, but that is precisely because the schema already covers 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+resource+scope ('Find the cheapest in-stock products for a keyword, one flat list sorted by current price'), which is instantly distinguishable from generic siblings like ab_search. The 'cheapest' framing pins down the differentiator without needing to open 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?

Explicitly says when to use it ('Use when the user wants the lowest price for X') and routes to the alternative for a related need ('check ab_product for the size you need'). It even documents the failure/continuation condition ('complete=false means more in-stock matches lie past scanned: raise scan'), leaving little to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds one behavioral nuance about the data (stock with the exact count when low) but says nothing about failure modes, auth, or staleness for a tool that hits a live catalog.

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 and the payload list, then the usage note and the sibling pointer in two short trailing lines. The parenthetical field enumeration is slightly over-long but every element maps to a real field.

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 and the description still spends most of its text enumerating return fields, which is partly redundant. It nonetheless covers trigger, scope, and the reviews alternative, so nothing an agent needs in order to invoke it is missing.

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

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

Schema description coverage is 100% and the single parameter already documents its origin and format ("product id from ab_search / ab_browse, e.g. 6963"). The description adds no syntax or range guidance 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+resource ("Get one product's record") and enumerates the exact payload: price/discount in Toman, stock, per-variant price and stock, brand, categories, rating and key facts. This is clearly separable from the list-oriented siblings ab_search and ab_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?

Gives an explicit trigger ("Use after ab_search / ab_browse when the user picks a product") and routes a related need away to another tool ("Customer reviews: ab_reviews"). The when-to-use condition and the alternative are both named.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds genuinely new behavioral context: newest-first ordering, that rating is null for star-less questions, what verified_buyer means, that shop answers are included, and that dates are Jalali (1405-07-13) — a format quirk an agent could not infer from structured fields.

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

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

Front-loads the core purpose in the first sentence, then layers usage and data quirks. Every sentence is informative, though the parenthetical detail and closing sentence make it slightly denser than strictly necessary.

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 annotations covering safety, the description needn't explain return values, yet it still supplies the interpretation cues (null rating, verified_buyer, Jalali dates) that make the output usable. Nothing critical is missing for selecting or invoking the 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 coverage is 100%, so both parameters (limit, product_id) are already fully documented in the schema. The description echoes ordering but adds no parameter syntax or format detail beyond what the schema provides, so the 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 ('Read customers' reviews and questions about a product') and pins down ordering and content scope, making it easy to distinguish from siblings like ab_product or ab_search which cover product data rather than 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 explicit use contexts ('quality check before recommending a product', seeing the shop's skin/hair advice), which tells the agent when this tool is the right call. It stops short of naming an alternative sibling or stating when not to use it, so it lands at a clear but non-exhaustive 4.

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 readOnly/idempotent/non-destructive, so the description's added value is the broad title+description matching behavior and the note that out_of_stock_matches counts sold-out items. That is genuinely useful beyond structured fields, though it doesn't cover pagination limits or result ordering nuances beyond what the schema states.

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

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

Front-loaded with the core action and routed alternatives in four tight sentences with no filler. Slightly dense with sibling references, but each 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?

An output schema exists so return values need not be spelled out, and the description still flags the one non-obvious return field (out_of_stock_matches). Combined with full schema coverage and clear sibling routing, nothing needed to call this tool 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 meaning by clarifying that matching spans both title and description (which shapes how the query parameter behaves) and hinting at the in-stock-first listing behavior. This edges above the schema-only baseline.

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

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

States a specific verb (search) and resource (Asal Banoo products) and immediately names the fields returned (price, discount, stock, rating). It explicitly differentiates itself from siblings ab_find_cheapest, ab_browse, and 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 concrete trigger phrases ('price of X', 'do you have X') and routes to alternatives with the exact conditions that select each: ab_find_cheapest for the cheapest match, ab_browse for a whole category/brand, ab_product for details and variants.

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 useful behavior beyond that: how the content is rendered (Q/A pairs for FAQ versus free text) and a dated, scope-qualified content summary. It does not discuss pagination or page size, but for a small read-only page fetch that is minor.

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 and trigger examples are front-loaded and zero-waste. The trailing 'Summary (2026-10)' block is longer than necessary and hard-codes shop policy facts into the tool definition, which risks staleness, though it is clearly scoped and dated rather than vague padding.

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

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

An output schema exists and annotations carry the safety profile, so the description need not restate return values or permissions. It covers purpose, routing examples and output shape adequately; the only real gap is that it never states whether all four topics are always available or how missing content is surfaced.

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

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

Schema description coverage is 100% and the single enum parameter already documents each of faq/terms/about/contact in detail, so the schema does the heavy lifting. The description adds only the faq-specific return format (question/answer pairs), which is a marginal increment over the enum description rather than new meaning.

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 clarifies the output shape (FAQ as question/answer pairs, other pages as text). This clearly distinguishes it from the retrieval siblings like ab_search, ab_product and ab_reviews, which return products or reviews rather than policy 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?

Provides concrete trigger queries ('how long does delivery take', 'do you ship with Tipax', 'can I return it', 'where is the shop'), which tells the agent exactly what class of question routes here. It does not, however, name any sibling as an alternative or state a when-not-to-use condition, so it stops short of full routing guidance.

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