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

The annotations already mark it as read-only and safe, so the description adds substantial behavioral detail beyond that: history depth bounded by a 60-day TTL, snapshots written only on cache-miss (meaning gaps indicate no scan), and decay computed from daily closes rather than intraday. These are critical nuances that affect interpretation of results and are not captured in annotations. The description also explains the response structure thoroughly, covering tracked[], expired[], and snapshot_dates[].

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 typical, but it is well-structured with clear sections (Args, RESPONSE, LIMITS) and front-loads the purpose. It is not unnecessarily verbose for the amount of critical information it conveys, though it could be slightly tightened. Each section earns its place.

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?

The tool has no output schema, so the description must explain the return structure on its own—and it does so exhaustively. It covers the meaning of each response field, the interpretation of lifespan, limitations from TTL and data gaps, and the source of decay values. This is a complete picture for an agent to invoke the tool and understand results without further guesswork.

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 schema already fully documents both parameters (days: lookback with default/clamp, window: family with enum). The description repeats the defaults and adds the term 'snapshot family' but does not add meaning beyond the schema's descriptions. Since schema coverage is 100%, the baseline is 3, and the description provides marginal extra value.

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, action-oriented purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It clearly answers a concrete question ('how long has this edge existed and is it shrinking?') and distinguishes itself from sibling tools by focusing on temporal analysis rather than just current edges. This is more than just a restatement of the name.

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 provides clear context for when this tool is relevant: you use it to understand edge persistence/decay, and it contrasts a fresh edge with an old one. It does not explicitly name alternatives or state exclusions, but it implicitly differentiates from the related 'polymarket_edges' tool by being built on its snapshots. The intended use case is clear enough for an agent to select it appropriately.

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