Price chart

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

The annotations already cover safety (readOnly, idempotent, non-destructive, open-world), so the description's added value is in disclosing data shape: weekly series over roughly a year, prices in Toman, and a verdict field derived from a percentile statistic. It explains the verdict's enum semantics and derivation, which is genuinely useful beyond the annotations. Minor tension: it says 'about a year, weekly' while the schema default of 26 points yields about 6 months.

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?

Two tight sentences with the core purpose front-loaded and the verdict/percentile explanation following. Every clause carries information; only the year-vs-default-points mismatch slightly muddies an otherwise clean statement.

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 must carry the return-value burden, and it only partially does: it names summary.verdict and the percentile concept plus min/average prices, but not the shape of the chart series itself. For a read-only two-parameter tool this is adequate but leaves the primary output structure underspecified.

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 both parameters (product, points) are already fully documented in the schema, making 3 the baseline. The description adds only indirect meaning, tying the weekly cadence to the series length, but does not clarify how 'points' interacts with the stated one-year window.

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 states a specific resource (a product's price chart), its granularity (weekly, about a year), the metrics returned (minimum and average price in Toman) and an added output (a buy-now verdict). That is enough to tell it apart conceptually from siblings like tb_price_history or tb_trends, though it never names an alternative 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 'buy-now verdict' phrasing implies the decision-support use case, so an agent can infer when this tool is relevant. However, there is no explicit when-to-use or when-not-to-use statement and no routing against the closely overlapping siblings tb_price_history and tb_deal_check.

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