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

The annotations already establish readOnly, idempotent, closed-world and non-destructive behavior, so the description carries a lighter burden. It adds genuinely useful context beyond the annotations: that values come from hourly readings per supplier, and that results include each product's price before and after a change.

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 content is front-loaded onto what counts as a price change, then the filtering behavior, with no filler. The opening clause is syntactically dense ('the price changes the site's hourly readings ... attribute to the supplier') but every sentence contributes information.

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?

With no output schema, the description adequately conveys the shape of results (before/after prices, per-supplier attribution) and both optional filter modes. The main gap is the default behavior when neither parameter is passed and the time window covered by the readings, which the agent must guess.

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 the schema already documents both optional parameters with examples. The description restates the filter semantics ('supplier to narrow it', product for per-supplier history) without adding new meaning such as wildcard behavior or interaction rules when both are supplied, so 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?

The description names a specific verb (get) and resource (price changes), and enumerates the four suppliers plus the two change categories the tool surfaces (supplier-wide percentage/amount shifts and single-product price changes). It is clear what data it returns, but it never distinguishes itself from the sibling get_product_costs, which an agent could easily confuse with a price-history tool.

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?

Usage is only implied through the filter hints: 'Name a supplier to narrow it, or a product for its price history at each supplier' tells the agent how to scope, but not when this tool should be chosen over compare_suppliers or get_product_costs. No exclusions or prerequisites are stated.

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