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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, yet the description adds substantive epistemics beyond them: observed prices stay user-supplied, missing variants and former prices stay unverified, unknown shipping stays unknown, and observed/known totals are kept distinct from market history. That tells an agent how to frame and hedge results, not just that the call is safe.

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 action and input modes, then layered caveats; every sentence carries information. Minor waste: 'Read-only; no checkout or alerts' restates the readOnlyHint annotation, and 'unknown shipping remains unknown' is echoed in the postal_code schema description.

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 five-parameter, all-optional tool with a nested observed_price object and an output schema, the description covers every input path, the identity-confidence model, and the limits of what it asserts. Return values are handled by the output schema, so nothing an agent needs to call or interpret 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 coverage is 100%, so the baseline is 3, but the description adds real meaning: it explains that barcodes and reviewed variant-identifying URLs establish exact identity while text similarity 'does not establish an exact retailer match,' and that product_id reflects an explicit user selection that still does not prove a listing match. Those are semantic distinctions the schema descriptions only partially 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 and resource ('Checks an offer') and enumerates the four accepted input modes (BestPrice URL, reviewed merchant URL, barcode, screenshot text). It also implicitly separates itself from price-history tooling by saying it 'compares current eligible offers ... separately from market item-price history,' but it never names a sibling tool, so differentiation is inferential.

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 clear guidance on which input produces which outcome: barcodes and 'reviewed variant-identifying URLs' yield exact identity, while text queries 'return candidates for explicit user selection.' It does not state when to prefer this over compare_offers, get_price_history, or search_products, so the routing guidance to siblings remains implicit.

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