Volume-price wave structure

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

Annotations declare readOnlyHint and openWorldHint, but the description adds meaningful behavioral context: it requires real exchange volume (spot FX has none), notes that two events came out REVERSED against tradition, and warns that session='full' can return 422 NO_EXTENDED_VOLUME and to obey retryable. This exceeds the annotation coverage without contradiction.

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 four sentences, each earning its place: definition, measured outcomes, FX/volume caveat, and session recommendation. It is dense but not bloated; all information is relevant. Slightly longer than necessary, but the structure is logical and front-loaded with the core purpose.

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?

Without an output schema, the description must convey what is returned, and it does: waves with summed volume, the five events, and their win rates. It also covers data requirements, error handling, and session semantics. Missing is a precise output format or example, but for the complexity, it is sufficiently complete.

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 covers both parameters 100%, so baseline is 3. The description adds value by advising to use CME currency futures instead of spot FX due to volume requirements (relevant for symbol selection) and by recommending the session parameter based on the reference-rate window, which is a meaningful use-case nuance beyond the schema's technical detail.

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 clearly defines the tool as a Weis Wave volume-price structure analyzer, grouping price into waves and summing volume, plus identifying five classical volume-price events with measured win rates. It explicitly answers the question 'is there volume behind this move,' and is distinct from siblings like day_type, max_pain, and gamma.

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 states when to use this tool ('Answers is there volume behind this move'), provides an explicit alternative for spot FX ('use CME currency futures (6E=F) instead'), and gives session selection guidance ('full' to match published rates, default 'rth' for regular-session reads). This goes beyond simple context to explicit when-not and alternatives.

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