overshoot_signal

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

Annotations already cover read-only, open-world, idempotent, and non-destructive traits. The description adds value beyond those: it flags the tool as a 'PREMIUM SIGNAL' (suggesting access gating), clarifies it operates on a time-constrained recent window, and specifies the two computed outputs. No contradiction with 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?

Two well-organized sentences: the front-loaded label ('PREMIUM SIGNAL — overshoot/fade detector') conveys the tool class and gated status, and the second sentence carries the input/output detail. No wasted filler, though 'PREMIUM SIGNAL' is slightly marketing-toned.

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 a 4-parameter tool with no output schema and 0% schema coverage, the description gives the gist of input and output but not enough precision: the return format for 'fade setup active' and 'reversion tendency' is unspecified, and parameter semantics remain ambiguous. Adequate for a basic call but gaps remain for correct parameter tuning.

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 must explain the parameters but only does so loosely: token_id maps to 'a token's', hours/lookback_s map to 'recent price series', and threshold maps conceptually to 'panic jumps'. It never states what threshold is compared against, how hours relates to lookback_s, or what the defaults (6, 0.05, 60) mean.

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 names the resource (a token's recent price series), the specific action (analyzes for fresh panic jumps), and the two outputs (whether a fade setup is active, historical reversion tendency). It is clearly distinguishable from sibling order/position/balance tools by function, though it does not explicitly name any alternative.

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?

Usage is implied by the purpose: an agent would call this to detect overshoot/fade setups after a panic move. However, it never states when not to use it or names alternatives such as price_history for raw series or dispute_risk for risk assessment, leaving the choice to inference.

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