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

With no annotations, the description does the heavy lifting. It honestly discloses that points are index levels (base 100) never prices, that insufficient data returns an honest status rather than a fabricated series, and that summary/full modes differ. Minor omission: no explicit statement about side effects or permissions, but the read-only nature is strongly implied, so this is not a serious 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?

The description is longer than average but each sentence carries information: defaults, distinctions, alternative tools, and behavioral caveats. It is well-structured with clear clauses, though it could be trimmed slightly—e.g., the benchmark_id note feels appended but is still relevant.

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 no output schema, the description adequately explains the return content (date + index_level, window change, gap flags) and the insufficient_history status. It does not fully define 'gap flags' or return format, but for a history-retrieval tool this is reasonably complete, especially with the alternative-tool guidance.

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?

Although schema covers all four parameters, the description adds significant meaning: 'team' = Team/SME, provider_type returns a standalone series with its own base 100, and response_mode 'summary' returns date+index_level plus window change while 'full' adds gap flags. It also mentions a benchmark_id parameter not present in the schema, which is extra guidance.

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 clearly specifies the tool retrieves a canonical dated index series for the AEPI, distinguishing it from price-related tools. It explicitly says the series is what the /aepi page plots and contrasts with market_report or price_benchmark for capability-specific pricing.

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 states exactly when to call this tool (for charting/analysing movement) and when not to, explicitly naming alternatives: 'for pricing on a specific capability use market_report or price_benchmark.' It also explains parameter-based selection of the series (tier, provider_type, period) with defaults.

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