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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, but the description adds real context beyond them: a concrete rate-limit/cost model (100 calls/day free, then 0.002 USDC per call, prepaid in ~0.01 USDC batches), the payment-required handshake, and an explicit data-quality caveat ('may be delayed or wrong'). It stops short of describing pagination or truncation behavior at the 200-limit cap.

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 purpose and scope are front-loaded and the paragraph wastes little space on the mechanics an agent needs. The 'Education/information only; not financial advice' clause is boilerplate that does not help tool selection and slightly bloats an otherwise dense single paragraph.

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?

With no output schema, the description correctly carries the return-shape burden, listing the fields and newest-first ordering, and it covers the payment workflow end to end. What is missing is behavior at the limit boundary (truncation/pagination) and the meaning of the hours window.

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 71%, so most fields are documented, yet the description still adds meaning: it clarifies the maker/taker framing behind the role parameter and the exact pricing/batching mechanics behind payment_tx and payment_token, which the schema only sketches. It adds nothing for hours or limit, which remain undocumented defaults.

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 names a specific verb and resource ('Fills (OrderFilled) where a given DeepBook BalanceManager was the maker or the taker in one pool') and specifies return contents (time, side, price, qty, fee, tx) plus ordering ('newest first'). The balance-manager-plus-pool scoping cleanly separates it from sibling market-wide tools like get_recent_trades or get_order_book.

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?

Usage is implied by scope (fills tied to one BalanceManager in one pool) but there is no explicit when-to-use / when-not guidance and no sibling is named as an alternative. The one genuinely directive element is the two-step payment flow (free tier first, then payment_tx/payment_token after the payment-required response), which is a retrieval precondition rather than a use-vs-alternatives rule.

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