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

Annotations already declare readOnlyHint=true and openWorldHint=false, and the description goes well beyond them: exact price (0.10 USDC on Base), no trial and no automatic payment, what is explicitly NOT disclosed (paid-response caching, replay/idempotency, header parser behavior, settlement-before-delivery), that resource binding is 'advertised only', and that results are not an audit or safety guarantee. It even gives an illustrative output showing assessment_complete=false and unknown_count=5, correctly labeled as not a live result, and prescribes behavior for an unknown payment outcome rather than auto-retrying.

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?

Core facts are front-loaded, but the body is heavily padded with near-duplicate disclaimers: two separate 'Illustrative output excerpt' passages and repeated 'not a live result / signature / approval / guarantee' caveats around an already-shown example. The payment safety instructions are valuable yet restated in multiple forms, roughly doubling the length without adding new information.

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?

For a paid, no-output-schema tool this is thorough: price and asset/network, example arguments, an illustrative (clearly marked non-live) response shape, explicit statement of which risks remain unmeasured, and the exact payment handshake. An agent has everything needed to decide whether it can call this and how to proceed if payment is demanded.

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 0% for the single report_id parameter, so the description must carry the meaning — and it does: the id must come from an existing, unexpired, complete free Lint report, and an example UUID is supplied. What is missing is whether an expired or incomplete id produces a specific failure mode beyond the generic 'freshness/data/availability checks still apply' line.

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 states the resource and scope precisely: detailed passive findings plus source-linked fixes drawn from an already-existing, unexpired free Lint report, with 'No new target request' making clear it does not scan anything new. That implicitly separates it from the scanning sibling (lint_endpoint), though the sibling is never named directly, so an agent must infer the handoff relationship.

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?

Explicit sequencing: inspect the free Lint summary first, obtain a current complete report_id, use only an x402-capable MCP client, and on payment-required STOP and get explicit wallet/budget approval before letting the client attach _meta["x402/payment"] and retry the identical arguments. It also names the failure mode ('a generic MCP connector without payment support cannot complete a paid continuation') and forbids silent fallback from free to paid, which is unusually complete routing guidance.

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