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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so safety is covered. The description adds valuable context: it discloses that data is updated daily, that it includes a sample of sold listings with specific fields (date, condition, carrier, storage, price), and that it accepts free-text device name or exact slug. This goes beyond annotations by explaining data freshness and output composition.

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 description is three sentences, front-loaded with the core distinction (realized vs list price) and daily update, followed by output details and the alternative tool. Every sentence adds value—no fluff. It is compact yet comprehensive.

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?

The tool has 4 parameters, no output schema, but annotations cover safety and idempotency. The description explains the output format (average + sample listings with fields), which is crucial since there is no output schema. It does not mention pagination or limits on the sample size, but for a read-only data retrieval tool, this is adequate. The description is sufficient for an agent to call it correctly.

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 each parameter is documented in the schema. The description adds meaning beyond schema by emphasizing that device can be free-text or slug, and by implying that carrier/storage filters vary by device. It also clarifies the output includes a sample of listings, which helps agents understand what parameters affect. This is slightly above baseline because it clarifies the free-text nature of device.

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 clearly states the tool's purpose: providing average realized sale prices (not list prices) per storage/variant, updated daily, plus a sample of recent sold listings. It explicitly contrasts with device_prices (active listing averages), which distinguishes it from a key sibling. The verb 'realized sale price' is specific and unambiguous.

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 description gives clear context on when to use this tool: when you need 'what did it actually sell for' versus active listing averages, and even names the alternative (device_prices). However, it does not explicitly state when NOT to use it or mention other alternatives like search_device, but the direct comparison provides strong guidance.

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