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

Annotations already declare readOnly, idempotent, non-destructive, and open-world, and the description corroborates that with 'no transaction is submitted for a committed market'. It then adds genuinely useful behavior the annotations cannot express: committed markets settle automatically, SKIPPED/COMMITTED_SETTLED only appear after a corroborated receipt, and a pending case's zero amount is an unavailable placeholder rather than a credited zero. The 'explicit batch requests' sentence is confusing given the schema has no batch parameter, which keeps it from a 5.

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 purpose is correctly front-loaded in the first sentence, but the remaining text is a dense run of status-code and flag semantics with some off-topic material about batch requests and the receipts endpoint. Several clauses would benefit from being trimmed or moved to the output schema's territory.

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?

An output schema exists, so return values need not be re-explained, yet much of the description is spent doing exactly that while leaving limit/cursor behavior unspecified. For a read-only paginated list endpoint, the missing pagination and parameter guidance is the more important gap.

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 coverage is only 33%: walletAddress is documented in the schema, but limit and cursor are not, and the description never mentions any of the three parameters. It does not explain pagination, the 200 maximum, or what happens when walletAddress conflicts with the API-key bound wallet, so it fails to compensate for the coverage gap.

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 opening sentence gives a specific verb, resource, and scope: list currently on-chain-eligible payout claims for the authenticated agent wallet. It does not name any of the adjacent claim tools (prepare_claims, simulate_claims, sweep_claims, get_claim_status), so an agent still has to infer the boundary from the schemas.

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?

Usage is implied by the eligibility framing, and the description does point at GET /claims/receipts as the route for already-credited payouts. However, that is an HTTP endpoint rather than a sibling tool, and nothing says when to choose this over kellian_prepare_claims, kellian_simulate_claims, or kellian_get_claim_status.

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