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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the safety profile is covered; the description adds a genuine behavioral fact not in the annotations — 'Works signed out' — plus the expectation that results include negative answers ('what we cannot do'), which prepares the agent for category entries showing no coverage. No pagination, units, or result-shape detail is given, keeping it below a 5.

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?

Three short sentences with the primary output description front-loaded and the usage cue second. 'It is the honest answer about what we cannot do' is slightly rhetorical rather than factual, but it earns its place by signaling that negative coverage is reported explicitly.

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 one-parameter, non-destructive read with full annotations and no output schema, the description covers what is measured (coverage per category per market), what else is returned (unpriced categories), auth behavior, and when to call it. Only the concrete return structure (per-category fields, units of 'how much') is left unstated.

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?

There is a single parameter with 0% schema description coverage; the enum values are self-explanatory but nobody documents what the default does. The phrase 'for a market' is the only hint that the parameter selects the market/country, so the description compensates only partially for the missing schema text.

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 names a specific resource and dimension ('sold-price data we hold per category for a market') plus a second output facet ('which categories can never be priced'), which is far more informative than the title 'Comp coverage'. It implicitly contrasts itself with 'the comps tools', so an agent can tell it apart from get_sold_comps and get_sold_history, though the operative verb ('report/measure') is only implied.

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?

'Check this before building on the comps tools' gives an explicit precondition and ordering relative to the sibling comps tools. It does not spell out the inverse case (e.g. 'once coverage is confirmed, call get_sold_comps for actual prices'), but the usage context is clear enough to act on.

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