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

With no annotations supplied, the description carries the full behavioral burden and does substantial work: it discloses that returned prices are landed USD totals inclusive of duty, shipping and clearance, that every SKU is returnable for 14 days, and that dispatch is 48h with 7-12 day delivery. What it does not disclose is whether results reflect live stock, how many results come back by default, or any ordering of 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?

The trigger condition is front-loaded in the first clause, and the subsequent sentences each contribute distinct information (price composition, returns, lead time). The returns sentence is slightly over-detailed for an invocation decision ('no return is needed' is commercial reassurance rather than a search parameter), which is the only wasted space.

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 six-parameter, no-annotation, no-output-schema tool, the definition covers the commercially important ground an agent needs to answer a shopper: total-cost framing, returnability, and delivery window. It falls short only on retrieval mechanics — result count, pagination, and the effect of the in_stock and limit defaults.

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 50%: q, ships_to and max_price are documented, while limit, in_stock and min_price are bare. The description does add real meaning by establishing that price figures and therefore price filtering operate on landed USD totals, but it says nothing about what limit controls, what the default in_stock=true excludes, or how min_price pairs with 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?

The description makes clear this is a discovery/search tool for people who describe a need rather than a part number, using concrete examples ('router bit set', 'cobalt drills under $60'). It implicitly separates itself from model-number lookup, but never states plainly that it searches the catalog by keyword, so the verb+resource pairing is inferred from the examples 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?

The opening 'USE THIS when a human asks what to buy, or names a tool type but no model number' is a crisp, front-loaded trigger that tells the agent when to reach for this tool. The negative case (a model number is named) is implied as someone else's job, but no alternative tool is named, so the guidance stops just short of explicit routing.

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