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

Annotations already cover read-only, idempotent, non-destructive, closed-world. The description adds real behavioral context beyond them: the data is append-only and never overwritten, the trend is defined as change_pct between first and latest, and observed_at vs as_of are distinguished. It does not mention the limit/cap behavior (default 100, max 500), which is the remaining gap.

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 dense sentences with the core claim front-loaded. The parenthetical about append-only and the trend definition earn their place; the trailing instruction about single-observation series is slightly meta but still useful.

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?

An output schema exists, so return structure does not need explaining, and the read-only annotations cover safety. What an agent still lacks is guidance on result size/pagination and the role of the use_case parameter, but the essential semantics for calling it correctly are present.

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 only 40% (limit, provider, and use_case are undocumented in the schema). The description clarifies 'series' as a filtered view and explains time semantics relevant to 'since', but leaves 'limit' and 'use_case' unaddressed. It also says 'for a job and/or provider' while the schema exposes 'use_case' rather than a job parameter, which mildly muddies the mapping.

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 resource and scope: every recorded price observation for a job and/or provider, grouped into series with a trend metric. That grouping/trend framing implicitly separates it from get_prices and compare_providers, but no sibling is named explicitly.

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 only directive is about output handling ('If every series has one observation, say so'), not about when to choose this tool over get_prices, compare_providers, or estimate_cost. No prerequisites, no when-not-to-use conditions are given.

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