Check if a price is a good deal

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

The description goes beyond the readOnlyHint/openWorldHint/idempotentHint annotations by explaining that price history accumulates over CartScout reads and that first-time products have little to compare against. It also states the rating basis (average, lowest, highest). This is useful behavioral context with no contradiction to the annotations.

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 two sentences with no filler. The first sentence front-loads the core action and comparison inputs, while the second adds an important behavioral caveat about new products. Every phrase contributes to the agent's judgment.

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?

Given complete parameter descriptions, an output schema, and strong annotations, the description focuses on the genuinely missing context: history behavior and the limitation of first-time products. It does not need to explain return values because the output schema already exists, though it could have more explicitly listed when to prefer sibling tools.

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?

All three parameters already have solid descriptions in the schema, so the description does not need to repeat them. It adds high-level context about the timeframe and comparison basis, but it does not materially deepen meaning for url, days, or refresh beyond what the schema already states.

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 opens with a specific predicate ('rate whether a product's current price is a good deal') and a clear resource ('recorded price history' with average, lowest, and highest price). This makes it easy to distinguish from get_product, compare_products, and get_price_history even without baking alternatives into the text.

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 the tool is most meaningful after a product has been read enough times to build history, and it calls out the first-visit limitation. However, it never explicitly says when to prefer check_deal over get_price_history or compare_products, nor gives concrete guidance such as a minimum history threshold.

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