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

The annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered; the description adds substantial behavioral context beyond that: history depth bounded by the 60-day snapshot TTL and snapshotting-enablement start, data gaps meaning 'nobody scanned that day' (cache-miss write semantics), decay computed on daily closes of edge_pp_net rather than intraday, the signed-value convention (negative = SELL YES), and the median-lifespan 'competition clock' framing. This provenance and computation-basis disclosure is exactly what an agent needs to correctly interpret results.

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?

Though lengthy, every sentence earns its place: the purpose is front-loaded, args are summarized in one clause, the RESPONSE section is needed because there is no output schema, and the LIMITS section discloses TTL, provenance start, and computation basis. The organization (purpose → args → response → limits) makes the density navigable, and even the conversational aside ('wide for a reason nobody is willing to take') carries interpretive value for trade assessment.

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 carries the full burden of explaining the return shape, and it does so exhaustively: tracked[] with edge_pp_net time-series, first_seen, trend enum values, and decay_pp_per_day; expired[] with lifespan_days and its interpretive meaning; snapshot_dates[] with the cache-miss gap explanation. Combined with the LIMITS caveats, an agent has everything needed to call the tool correctly and interpret results — nothing material is missing.

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 per the baseline rule a 3 applies even without param info in the description. The description does restate the parameters ('days (lookback, default 14, max 30), window (snapshot family, default "1wk")') with a marginal addition — the phrase 'snapshot family' links window to the snapshot-storage concept — but it does not materially extend what the schema already documents.

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+resource: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots,' and immediately frames the core question ('how long has this edge existed and is it shrinking?'). It clearly distinguishes itself from the sibling polymarket_edges by positioning itself as the historical-persistence layer on top of those snapshots, while the concrete contrast ('a fresh wide edge and a 3-week-old wide edge are different trades') makes the purpose unmistakable.

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 gives strong contextual signals about when to use it — the entire framing is temporal ('how long has this edge existed', 'first_seen', 'lifespan_days', 'decay_pd_per_day'), and it references its relationship to polymarket_edges ('built from daily polymarket_edges snapshots'), letting an agent infer that point-in-time edge scanning belongs to the sibling tool. However, it never explicitly names an alternative or states 'use X when ... not Y,' so the when-not-to-use guidance is left to inference.

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