Is this return stream distinguishable from noise? Seeded sign-flip permutation test (PAID $0.05)

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

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true), and the description adds genuinely new operational context: the call costs 0.05 USD, is paid via x402/base/usdc on eip155:8453, and is reachable at POST /v1/quant/significance. That cost/payment disclosure is exactly the kind of extra behavioral fact annotations don't carry. It does not explain how the charge is enforced (preflight? automatic deduction), nor what the seeded/non-idempotent pairing implies for repeat calls.

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?

Two short lines, purpose front-loaded, transport/payment details second. The opening sentence is a verbatim copy of the title, which is mildly redundant, but it does establish the tool's purpose independently. Brevity is appropriate; the problem is under-specification, not padding.

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 described, but for a six-parameter statistical tool with zero schema descriptions the entry leaves the agent unable to construct a correct call (what units 'returns' expects, what 'null' values are allowed, whether benchmark_returns is required for certain nulls). It also omits any tie-in to the payment/preflight siblings for a paid endpoint.

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?

Six parameters with 0% schema description coverage, and the description explains none of them. The bare word 'seeded' faintly hints at the seed parameter and 'return stream' at returns, but null (default 'zero_mean'), trials, as_of, and benchmark_returns — including whether a benchmark makes the test comparative — are entirely undocumented, leaving the agent to guess. This is a clear case where the description had to compensate and didn't.

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 title/description names a concrete method and domain: a seeded sign-flip permutation test answering whether a return stream is distinguishable from noise. That is far more specific than a generic 'quant analysis', and the method name implicitly separates it from siblings like v1_quant_monte_carlo or v1_quant_risk_of_ruin. It stops short of an explicit sibling contrast, hence 4.

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 question phrasing ('Is this return stream distinguishable from noise?') implies the use case: call this when you have a return series and want a significance test. Nothing is said about when NOT to use it, whether a benchmark series is optional or when to supply benchmark_returns, or how it relates to the other quant tools. Usage is inferable but not stated.

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