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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the tool's safety profile is known. The description adds substantial behavioral context beyond that: entry is the next bar's open, the list is computed after the bar closes, lookback periods differ by timeframe (20/60/120 days), results are null when counts are below threshold, and units (_pct/_pp/_krw) and excess_pp are defined. These details are not in the annotations and materially affect interpretation.

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 and bilingual, with the Korean section repeating and extending the English summary. Though it is front-loaded with the core purpose and organized into a main description plus caveats, the overlap between languages makes it less concise than it could be. Every sentence adds some value, but the duplication costs clarity.

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?

Given the tool's complexity and the presence of an output schema, the description is highly complete. It covers the key context: population scope, comparison to a sibling tool, entry timing, lookback variation, null thresholds, unit conventions, and a clear instruction not to use it for stock-specific buy/sell decisions. There is no missing context that would cause an agent to call it incorrectly.

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 coverage is 100%, so the baseline is 3. The description adds value for the free-form pattern parameter by listing the concrete pattern categories (golden cross, moving-average stack, RSI oversold, Bollinger bands), which are not enumerated in the schema. It also explains the lookback differences across timeframe values, helping the agent understand how the timeframe parameter changes behavior. Exact string keys for pattern are still not given, so it's not a perfect 5.

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 explicitly states the tool evaluates classic chart patterns (golden cross, moving-average stack, RSI oversold, Bollinger bands) over the entire population of KOSPI/KOSDAQ stocks since 2020, on daily/weekly/monthly bars. It also calls itself a historical statistics lookup tool and distinguishes itself from maedong_signal_stats by noting the denominator difference, so an agent can clearly identify what this tool does and how it differs from siblings.

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 explicitly names the sibling maedong_signal_stats and explains the denominator difference, telling the agent when to use this population-wide tool versus the sampled alternative. It also provides a clear when-not: 'Do not use to generate buy/sell decisions for a specific stock' in Korean, plus practical caveats about entry timing and timeframe comparability.

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