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

Annotations cover the safety profile (readOnlyHint=true, openWorldHint=true, idempotentHint=false), but the description adds substantial non-structured behavior: it is a paid x402 tool, an unpaid call returns a structured payment_required challenge rather than fabricated data, a refusal refunds the debit, refusal codes follow a published taxonomy, and results require polling /v1/resolutions/:id until horizon_end. These are genuine operational facts an agent needs and cannot get from the schema or annotations.

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 LIVE set listing is a long, machine-dumped enumeration with obvious duplication (X05 five times, X06 five times, X07 five times, X08 six times, X09 six times) that consumes most of the text without adding selection value. The instruction "After paying, poll /v1/resolutions/:id until horizon_end" is also stated twice verbatim. The opening leads with payment-rail jargon instead of the tool's purpose.

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-value detail is not required, and the payment/refusal behavior is thoroughly covered. What is missing is the semantic content of the result: the description never says what the "profile" read actually contains or how it differs from wallet_state, which is the one thing an agent choosing this tool needs.

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 0%, so the description carries the burden. It explains `payer` well (a Base 0x… address, suppliable as a tool argument, an x-tollbridge-payer header, or an x402 PAYMENT-SIGNATURE), which is the hardest parameter. But `chain` and `address` are only implied ("Base address") and never explicitly defined as the target of the read.

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?

It states the resource ("Wallet intel on a Base address") and gestures at a verb ("the profile read"), which partially distinguishes it from the sibling tollbridge_wallet_state. However, "intel" is vague and the follow-on sentence ("the profile/state reads here are the raw surfaces") blurs rather than sharpens the profile-vs-state boundary. An agent cannot confidently tell what data this returns versus wallet_state.

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 does route one class of work elsewhere — S09/S10 account decision questions go through tollbridge_decision, with this tool framed as the "raw surfaces". That is real, if cryptic, usage guidance. But it never states when to choose this over the close siblings tollbridge_wallet_state or tollbridge_get_intelligence, leaving the main selection decision to inference.

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