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

Annotations already declare readOnlyHint, openWorldHint, and destructiveHint, so the base safety profile is clear. The description adds non-obvious behavioral context: the credit cost formula, weekly rather than daily aggregation, and the presence of a history array in the response. It does not contradict the annotations and usefully elaborates on cost and granularity.

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 compact paragraphs are front-loaded with purpose, followed by use-case routing and then the cost/default rule. The 'time machine' and 'deepest competitive-intelligence tool' phrasing is mildly promotional but not harmful. Overall, each sentence contributes to tool selection or invocation guidance.

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?

For a read-only tool with three parameters and no output schema, the description adequately covers when to use it, how to size history_range, and what the response contains (weekly aggregated history). It does not explicitly state that history_range '0' returns only the current snapshot, though the schema does cover that. The output shape beyond 'history array' is not specified, but enough context is present for a competent agent.

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?

The input schema already documents all three parameters with 100% coverage, so the baseline is 3. The description adds extra selection guidance: the cost per month, the recommendation to default to 3 months, and the weekly aggregation semantics that affect interpretation of history_range. It avoids merely repeating schema text while still enriching parameter decisions.

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 verb and resource: 'Retrieve a product's historical performance over up to 12 months,' and enumerates the exact metrics returned (views/traffic, sales, price, Best Sellers Rank). It also differentiates from get_product_detail by labeling this the 'deepest competitive-intelligence tool' and explicitly excluding simple price checks.

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?

It gives concrete use cases: trend forecasting, seasonality analysis, conversion-rate estimation, and due diligence. It also tells the agent when not to use it, naming the alternative 'get_product_detail is 5x cheaper for that,' and instructs how to choose history depth: ask the user or default to 3 months. This is explicit routing.

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