Find cheapest product

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.