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

Annotations already declare readOnly, idempotent, non-destructive, so the safety bar is low; the description instead earns credit for semantics: it names the source (public close records), states 'Pending scores are never read', and pins down edge cases that would otherwise be misread (expired_no_jury is not a failure, failed counts jury failures only, not_paid excludes expiries). That is exactly the kind of interpretation guidance an agent cannot get from annotations. It stops at 4 because nothing is said about volume, cost, or what a row actually contains.

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 core sentence is a single run-on that packs all nine bucket definitions into one clause chain, which is information-dense but hard to scan; the bucket glosses are load-bearing, but the reader has to parse semicolon-separated parentheses to extract them. The trailing sentences (close=, CSV path, use case) are appropriately terse.

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 reporting tool with no output schema, the critical missing piece would be what the counts mean, and the description supplies that by defining every bucket and the 'rows still open at that close' column. The CSV path and 'pending never read' line round out an agent's needs. It falls short of 5 only because the returned row shape (which fields correspond to the named buckets) is left to inference.

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 all six parameters including both enums are already documented; baseline is 3. The description adds only a small amount beyond that — 'close= keeps one close' and the open/open_panel framing — and says nothing about sort/limit/offset/segment behavior that isn't already in the schema.

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: settled answers bucketed by origin epoch, per close of a segment, read from public close records. It enumerates the exact buckets (settled, sealed, passed, expired_no_jury, failed, paid, not_paid, open, open_panel), which makes the tool's shape unambiguous. It does not explicitly contrast itself with near-neighbors like get_pending_by_epoch or get_epoch_rewards, so it stops short of a 5.

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?

There's an explicit use clause ('Use it to see how answers from each origin epoch settled, sealed and got paid') and a narrowing hint ('close= keeps one close'), so usage is more than implied. But no sibling is named as an alternative, and there is no when-not guidance — an agent must infer that pending/not-yet-settled queries belong to get_pending_by_epoch instead.

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