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

The description goes beyond annotations by explaining that it returns an UNSIGNED base64 tx, reverts unless repaid in-transaction, verifies the borrowed token, requires x402 payment past the free tier, and supports idempotent retry. This richly discloses operational behavior and does not contradict the readOnly=false/destructive=true 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 description is front-loaded with the most important purpose and then covers the execution model, safety behavior, fee requirement, and optional idempotency semantics. Every sentence provides necessary information and there is no filler.

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?

Given the complexity and 0% schema coverage, the description covers the core mechanics and safety profile well. It does not fully document all optional parameters or explain how to construct instructions beyond 'JSON ix', but it is near-complete for safe invocation.

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?

With 0% schema coverage, the description compensates well for key params: instructions, allow_unverified, payment_header, and idempotency_key. However, caller_id and pay_in_crank are not explained, and amount, wallet_address, and marginfi_account rely on their names rather than explicit semantics.

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 'Marginfi flash loan for arbitrage (non-custodial, atomic)', which gives a specific verb, resource, and use case. It clearly differentiates this tool from generic lending tools like lend_borrow by emphasizing the atomic, non-custodial, borrow-plus-repay mechanics.

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?

The description specifies the intended context: arbitrage, non-custodial, atomic, and repaid within the transaction. It does not explicitly say 'use this instead of X' or name alternative lending tools, so the guidance is clear but not exclusionary.

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