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

Annotations are sparse (readOnlyHint=false, idempotentHint=true), and the description adds substantial context they don't carry: a $0.25 USDC price on Base or Arbitrum One, a required x402 v2 PAYMENT-SIGNATURE header, the paid endpoint URL, and the idempotency-replay behavior. It also clarifies no orders are placed despite the non-read-only hint. It stops short of explaining what "delayed scan" or "freshness-labeled" concretely mean.

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 text is short and front-loads the purpose before payment mechanics, which is good. But the opening clause is compressed to the point of obscurity, and payment/URL details are interleaved with scope statements rather than grouped, forcing the agent to parse several dense fragments.

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?

An output schema exists, so return values needn't be explained, and the payment workflow is covered. Still, key concepts an agent would need to interpret results or choose parameters — what "delayed", "freshness-labeled", and "expressions" mean — are left undefined for a five-parameter paid tool.

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 description coverage is 100%, so every parameter is already documented, including the query grammar, objective options, and budget tiers. The description only restates the budget-omitted-means-uncapped rule and adds no new meaning about objective selection or max_rows behavior; baseline 3 applies.

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 says to "Shop an idea" and mentions "expressions fitting your budget, freshness-labeled, signed receipt," which hints at returning candidate trade ideas for a ticker/theme, but the phrasing is idiosyncratic jargon ("delayed scan", "expressions") that an agent must interpret. It never plainly states the verb+resource (e.g., "returns ranked ticker/option ideas"), and it does not distinguish itself from close siblings like compute_spot_prices or compute_spot_sealed.

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?

"Ideas only — no orders placed" is a genuine scope exclusion, and "budget_usd omitted: uncapped" plus the query examples imply when the tool fits. However, there is no explicit guidance on when to prefer this over the sibling compute/check tools, nor any stated prerequisites for obtaining an x402 payment signature before calling.

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