detect_whale_events

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

The description discloses a genuinely useful behavioral trait — '推測ベース' (inference/speculation-based) and '簡易検出' (simple detection) — warning the agent that output is approximate rather than exact. Since no annotations are provided, this is meaningful credit. However, it doesn't disclose whether the tool is read-only, whether it mutates state, or any data-freshness behavior.

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 compact and front-loaded with searchable keyword tags. However, the two keyword lists ('Whale / Large Orders / Big Players' and 'whale / large orders / big players / smart money') repeat the same concepts, so a sizable portion of the text is redundant tagging rather than new information.

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 3-parameter, 0%-schema-coverage tool with no output schema, the description leaves too much unknown: parameter semantics, output shape, and result granularity are all unspecified. The inference caveat is the only piece of actionable context an agent gets, which is far from sufficient to call the tool confidently.

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 0%, so the description carries the full burden of explaining pair, minSize, and lookback — and it does none of it. It never mentions that minSize is an order-size threshold, what the lookback windows mean, or the pair format, despite referencing 板 (orderbook) and ローソク足 (candles) as data sources. All three parameters are left to the agent to infer.

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 (detect/検出) and resource (whale / large orders / large investors), plus the method (orderbook × candlestick). This distinguishes it from the get_* raw-data siblings and from detect_macd_cross (indicator crossover) and detect_patterns (chart patterns). It's clear, though the meaning leans on the keyword 'whale' being self-explanatory.

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?

No guidance on when to use this tool instead of alternatives. The keyword tags imply 'whale detection,' but the description never states explicit conditions or exclusions — e.g., when get_flow_metrics or detect_patterns would be a better fit. Context must be inferred entirely from the name.

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