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

With annotations already declaring the safety profile, the description goes well beyond them by disclosing the full payment/transport contract: POST JSON to paid_url, x402 v2 PAYMENT-SIGNATURE header, $0.25 USDC on Base or Arbitrum One, the concrete paid URL, and a docs link. This is exactly the behavioral context an agent needs to actually invoke a paid tool and is consistent with readOnlyHint=false (a receipt is produced).

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?

Two sentences, both front-loaded with the actionable lead (the trigger, then the payment mechanics). The first sentence is dense with a long enumerated list, but every element earns its place and nothing is redundant.

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 no prose. For a paid, remote tool the description covers cost, chain, auth header, endpoint, and the reasoning for using it — an agent has everything required to invoke it correctly.

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 idempotency_key, surface, and include_unverified are already fully documented in the schema, including enum-like slug examples and replay semantics. The description adds no parameter-level meaning, so the baseline 3 applies.

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 specific verb and resource: one call returns the ranked directory of agent-ranking surfaces, enumerating exactly what each entry contains (what it ranks, method, integrity reads, freshness, coverage, participation cost, our standing, published scoring criteria). This is highly distinguishable from all siblings, none of which touch ranking surfaces.

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 an explicit trigger ('when your agent would otherwise crawl the listing surfaces itself') and frames the value ('venue choice is one read, not a sweep'). It doesn't name a competing tool or state exclusions, so it falls just short of a 5.

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