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

Beyond the annotations, the description adds substantial behavioral context: WAIT is common and is context rather than instruction, confidence is normalized against reachable evidence, suppressed reads are explicitly shown rather than hidden, and payment retries are idempotent so the same tx_signature is never charged twice. These are meaningful operational traits not visible in annotations.

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 description is long, but the length is justified by the x402 payment protocol and the tool's nuanced outputs. It is front-loaded with the core result before explaining payment, and the Args section is cleanly separated. Minor redundancy with the idempotence hint exists, but the extra explanation is useful rather than wasteful.

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?

The description covers the return payload, the meaning of WAIT, confidence calibration, suppressed-read policy, the full payment flow, auth bypass with a Pro key, and spend caps. Given the tool's complexity and the presence of an output schema, an agent has enough information to call and interpret the tool correctly.

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?

With 0% schema description coverage, the description fully compensates by explaining all three parameters: tx_signature is a signed x402 settlement tx and should be empty on first call, chain specifies the payment rail with allowed values and default, and ref is an optional attribution tag. This adds real semantics beyond the bare schema.

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 verb and resource: it returns the current directional posture (bullish / bearish / WAIT) along with regime, zone, reason, confidence, btc_price and timestamp. It clearly signals the decision-context purpose and differentiates it from a raw data dump, though it does not explicitly distinguish itself from sibling brs_market_state.

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 description gives a precise call workflow: call without tx_signature, handle the PAYMENT_REQUIRED response by reading error.payment, pay on an advertised rail, then re-call with tx_signature and matching chain/ref. It also states when a Pro key bypasses payment and imposes spend-cap guidance, but it does not contrast this tool with its siblings.

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