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

Adds substantial context beyond the annotations: result cap of 10 stones, the exact returned fields, price currency, and the important caveat that retailer names are gated behind a free sign-up and must be surfaced as a link. Read-only safety is already covered by readOnlyHint, and openWorldHint=false is consistent with a curated price index rather than a live web search.

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?

Four compact sentences with the search scope front-loaded and no filler. The sign-up/link caveat and currency note both earn their place; only the reading is slightly dense, packing return-field inventory into a single run-on sentence.

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, and the description does a good job describing the return payload, so that burden is met. However, for a 10-parameter filtered search with near-zero schema coverage, an agent still lacks guidance on filter interaction (e.g. whether arrays are OR'd) and on the 3-page pagination ceiling, leaving the definition only adequately 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?

With 10 parameters at only 10% schema description coverage, the description does almost no parameter work. "Prices in US dollars" resolves the currency ambiguity on min/max_price_usd, and "up to 10 stones" hints at paging, but shape, origin, clarity, colour, sort, and carat bounds are left entirely to bare enums and numeric ranges.

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 ("Search certified diamonds listed by retailers worldwide") plus the distinctive value proposition of cross-retailer pricing. It is clearly not get_diamond or lookup_certificate, but it never names a sibling to contrast against, so differentiation is inferred 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?

No guidance on when to reach for this versus price_check, market_overview, or get_diamond. The only directive is an output-presentation rule ("always give the user the link"), which does not tell the agent when this tool is the right choice or when it is not.

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