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

Annotations only flag non-read-only, open-world, idempotent, non-destructive; the description goes far beyond by disclosing that this spends real money, the exact price tiers and upgrade proration, the Authorization: Bearer ptx_… requirement and owner opt-in for card charges, the max_price_cents safety cap, the chain 999 HyperEVM payment address dependency, and the returned unlock_token/export links.

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?

Purpose and price are front-loaded, and every clause carries operational weight (flows, auth, cap, confirmation). It is dense but long at roughly 110 words, and the x402 parenthetical, while useful, is the one segment that could be deferred to linked docs.

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?

Despite having no output schema, the description states the return shape (unlock_token and export links), covers auth, opt-in, pricing, both payment paths, the safety cap, and a money-spending user-confirmation requirement. For a 6-parameter payment tool this is complete enough to invoke 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 83%, so much is already documented, but the description adds genuine meaning: it explains the two-phase semantics of quote_id/tx_hash (step 2 of the USDC flow) and the purpose of max_price_cents as a cap rather than restating its schema text. It does not add format detail for address or tax_year beyond the schema, keeping this just under a 5.

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?

States a specific verb+resource+scope: 'Buy the full report for one wallet and tax year', immediately followed by pricing tiers. This cleanly distinguishes it from siblings like export_tax_file and get_tax_summary, which do not spend money or produce a paid artifact.

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?

Gives explicit branching guidance: method 'card' vs method 'usdc' with a full two-step flow (quote -> send USDC -> call again with quote_id and tx_hash), plus a named alternative path for x402 clients. It also states the prerequisite (owner's opt-in) and the imperative 'confirm with the user first', covering when and when-not to invoke.

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