Grocery store reviews

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

Annotations already establish readOnly, idempotent, and non-destructive behavior, so the description only needs to add what structured fields cannot. It does that well by disclosing the fixed 30-comment result set and explicitly stating there is no paging, which prevents wasted paging calls. It does not mention ordering/recency semantics of 'most relevant' or failure behavior for an unknown code.

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, both earning their place: the first defines the payload, the second gives the usage trigger, and the no-paging note closes the loop. Nothing redundant with the 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?

With an output schema present, return-shape details are rightly omitted, and the description covers the calling caveats an agent actually needs: the fixed 30-item payload and the absence of paging. Complete for a single-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 coverage is 100% – vendor_code has a pattern, an example, and a pointer to market_search / market_stores as its source. The description adds no parameter guidance, so the baseline 3 applies; the schema is doing all the work here.

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 a store's 30 most relevant customer comments') and even scopes it with a count and rating scale. It implicitly distinguishes itself from food_reviews by targeting stores rather than restaurants, but it does not name a sibling outright.

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 as a quality check before recommending a store' gives a clear condition for reaching for this tool over store metadata tools. It stops short of naming alternatives (e.g. market_store_info for factual attributes vs reviews for sentiment) or stating when not to use it.

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