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

Annotations only declare readOnly=false, idempotent=false, openWorld=true, destructive=false. The description goes far beyond: it flags irreversibility ('claiming cannot be undone'), a 10/hour rate limit, the auth material required, the side effects on reviews/sales/stars, and a full error taxonomy with reason codes. It also discloses that endpoint-supplied fields are wrapped under _untrusted, which is important context the annotations do not convey.

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 action and its prerequisites are front-loaded and almost every clause carries behavioral weight (error codes, rate limit, review-migration rules). It is, however, one very dense block; the long list of failure reasons and side effects would read better as structured bullets, costing it the top score.

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?

There is no output schema, so the description must cover returns, and it does: source becomes 'listed', plus reviews_moved, reviews_by_proof, and own_reviews are named. Combined with the error taxonomy, irreversibility warning, and rate limit, an agent has everything needed to call 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 coverage is 100%, so the baseline is 3, but the description adds real meaning: the wallet_proof must be valid for 10 minutes and signed by the key of pay_to_address, and it maps each failure to a reason code. That is beyond what the schema states, though idempotency_key semantics are left to 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 precise verb+resource ('Claim a listing we indexed') and immediately states the mechanism and outcome ('prove you control the wallet the endpoint is paid to and it becomes yours'). This cleanly separates it from createListing (you author it) and updateListing (you modify one you already own).

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 explicit prerequisites (API key + wallet_proof), a documented alternative for a different state (updateListing to set status active on an unreachable listing), and a pre-call instruction (read getReviews before signing). Failure routing is enumerated by condition (already claimed, seller-created, >200 reviews, unknown/deleted), so the agent knows exactly when this tool applies versus others.

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