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

Annotations already declare this a safe read (readOnly, idempotent, non-destructive), so the bar is lower; the description still adds real substance by disclosing what gets computed: net P&L after four taker fees, live-book slippage and stablecoin conversion, with funding per 8 h broken out separately. It also states the response carries a tier and reasons plus historical convergence frequency and time-to-converge, which an agent could not infer from annotations alone.

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?

Every clause carries information, but it is delivered as one long run-on sentence stitched with semicolons, so the net-after-costs point and the historical-convergence point blur together. The economics are front-loaded ahead of the secondary stats, which helps, yet a two-sentence split would have made the primary capability scannable.

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 and four parameters, the description must carry the return shape, and it largely does: cost-adjusted net, convergence frequency and duration, separate funding, tier and reasons. What is missing is any note on ordering, page size behavior, or what happens when no pair passes the actionable filter, which matters for a default-true filter.

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 75% and notional already carries a description, so the schema does most of the work. The phrase 'net at your size' reinforces that notional is per-side position size in USD, but base, limit and actionable_only receive no treatment in the description, and the 7-day lookback is presented as fixed rather than as something the caller controls.

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 pins down a specific resource and method: the same coin's perpetual priced differently on two exchanges, long the cheaper and short the dearer, close on reversion to the 7-day median. An agent can recognize it as a spread-convergence scanner rather than a generic basis or funding tool, though it never states a verb such as 'find' or 'list' and never names the sibling (basis_trades, spread_chart) it most overlaps with.

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?

There is no explicit when-to-use or when-not-to-use guidance, and no sibling is named as an alternative despite basis_trades, best_opportunities, spread_chart and execution_cost sitting in the same family. The only implicit routing signal comes from the schema default actionable_only=true, which hints the tool returns live-passing pairs, not that the description says so.

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