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

Annotations already establish read-only, idempotent, closed-world behavior, so the bar is lower. The description adds genuinely useful context beyond that: default 90-day window measured against the log's latest date, the newest-and-largest sort order, the before→after record shape, and the explicit guarantee of an empty list when nothing moved. It does not mention pagination or whether a limit truncation is signalled.

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 sentences, well front-loaded: what it returns, how to narrow it, and what happens when the result is empty. The parenthetical aside 'a quiet window is honestly quiet' is a small flourish but is doing real work by warning the agent not to retry on an empty response.

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?

All four parameters are optional and fully documented in the schema, there is no output schema, and the description compensates by describing the shape of each returned record, the ordering, and the empty case. An agent has everything it needs to call this correctly and interpret the result.

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 description coverage is 100%, so all four parameters are already documented with defaults, enum values, and the slug-resolution rule. The description restates the 90-day default and the kind/category filters without adding syntax or edge-case meaning beyond the schema. Baseline 3 applies.

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 — 'Recorded price MOVES across the index' — plus the ordering ('newest-and-largest first') and the unit of return ('each a dated before→after change of a tracked entity'). That is far more precise than the title 'Price movers' alone. It stops short of naming how it differs from close siblings like get_price_history, whats_changed, or most_volatile_in_category.

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 implies usage through the filtering options and the recency window, and it covers the empty-result case. But it never says when to pick this over get_price_history, whats_changed, volatility_for_entity, or most_volatile_in_category, all of which an agent could plausibly reach for instead.

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