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

Annotations only declare readOnly and openWorld; the description adds substantial context: price of $0.005 USDC per call, x402 in-call payment or a Skyfire/kya-pay token via header or argument, the fact that failed calls are not charged, and free 304 revalidation with the ETag within the same UTC day. It further discloses a methodological behavior that would otherwise be invisible—sweeps are estimated from a random sample of one-visit payers when counts are large, with the uncertainty expressed as a range in the band edges.

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 and band scheme are front-loaded, which is good, but the single dense paragraph mixes purpose, methodology, caching, and two payment mechanisms; the kyapay-token is explained both as a header and as an argument in successive sentences, which is redundant. The key caveat that sweeps are sampled from a random subset is buried mid-sentence rather than given its own short clause.

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 must carry the return shape, and it does: shares of payers and revenue, split by sweeper/grader and returning, each as one of five named bands. Payment, auth, caching, and the sampling caveat are all covered, which is strong for a paid read tool. It leaves minor gaps—whether a band with no qualifying payers is omitted or returned, and how the band edges handle the sampled range—but nothing that blocks a correct call.

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 three parameters are already documented, including the required address pattern and the if_none_match ETag semantics; that sets the baseline at 3. The description restates the address meaning and the 304 behavior rather than adding new parameter-level detail such as band-boundary edge handling or what happens when the sample is below a threshold.

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 states a concrete resource and dimensions: the share of payers and revenue to a seller's pay-to address on Base over the last 7 days, split into sweeper/grader share and return share, each expressed as a band with the five band edges enumerated. It also explicitly distinguishes itself from 'the payers tool' for the full list, so an agent can tell it apart. The rhetorical question opener ('Who pays this x402 address, in bands?') makes it slightly less crisp than a direct verb+resource statement.

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 gives clear routing to the sibling: 'The full payer list is the payers tool,' implying this tool is for aggregate banded shares rather than row-level detail. It also specifies the reuse condition (asking again the same UTC day with the ETag yields a free 304) and the two payment paths. It never states when this tool is not appropriate (e.g., for a single payer lookup), so it stops short of full when/when-not guidance.

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