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

Annotations only declare the safe-read profile (readOnly, idempotent, openWorld, non-destructive), yet the description goes well beyond them: it defines the sign convention, labels the output an upper bound rather than a profit, and names the specific omissions that make it one (hourly averages, QX bid-ask spread, inter-transaction delay). That is exactly the kind of behavioral context an agent needs to avoid misinterpreting the result.

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?

Three sentences, no filler, and the core measurement is front-loaded before the caveats and the return-shape note. Dense but every clause carries information; the return-field list at the end is slightly list-like but useful given no output schema.

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 an analytical tool with no output schema, the description compensates by naming the returned keys (bothVenues, breakEvenPct, points, summary, note) and by scoping the metric's limitations. The remaining gap is routing: nothing tells the agent when to pick this over qmax_check_arbitrage or qmax_backtest.

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 67%; the description adds real meaning for reference_qu by explaining it is the trade size used to derive the break-even gap (the schema only says 'Trade size in QU'). 'Hour by hour' also conveys the time granularity behind the range parameter. The range enum itself is left without added semantics in either place.

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 states a specific measurement: the hourly price gap between QX and QSwap for a given asset, with an explicit sign convention ('positive = QSwap dearer') and a defined threshold ('wider than the trading costs for a trade of reference_qu'). It is clearly a historical/analytical measurement rather than a live quote, though it never names the sibling it is meant to be used instead of (e.g. qmax_check_arbitrage), so differentiation is implicit.

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 framing as an 'UPPER BOUND on arbitrage, not a profit' implies this is for research/backtesting rather than live execution, but there is no explicit when-to-use, when-not-to-use, or named alternative such as qmax_check_arbitrage or qmax_backtest. The agent must infer the intended context from the caveats.

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