detect_52w_high_low

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

Annotations already declare readOnly, idempotent, and non-destructive, but the description adds meaningful behavioral details: default params hit a nightly pre-computed cache (sub-second) versus custom params computing on-demand (10-30s), data available ~17:15 JST, and plan restrictions. This goes well beyond the annotation signal and sets proper expectations for performance and availability.

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 well-structured with sections for use cases, performance, plans, and arguments, and every section earns its place. Minor redundancy exists (e.g., 'All plans' and '[Supported plans]' repeat plan info, and date constraint appears both in prose and in Args), but overall it remains readable and efficient.

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 (5 parameters, output schema present, clear annotations), the description covers the core function, alternatives, performance trade-offs, data timing, plan support, and parameter semantics. The output schema covers return values, so the description's focus on invocation and behavior makes it 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 description coverage is 0%, but the description fully compensates by explaining each argument: date format and constraint, optional code, window_sessions meaning and default, min_prior_sessions behavior and default, and detail's summary-vs-full toggle. Every parameter is given semantic meaning beyond the raw 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 opens with a specific action and resource: 'Screen for 52-week rolling high/low breakouts', supported by Japanese equivalents for clarity. It explicitly distinguishes itself from sibling tools by naming detect_52w_high_low_range for multi-date scans and detect_ytd_high_low for YTD scans, leaving no ambiguity about its purpose.

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 context is highly explicit: the description states when to use this tool ('Use for 52週高値, 52週安値...'), when to use alternatives ('For multi-date scans use detect_52w_high_low_range', 'For YTD high/low use detect_ytd_high_low'), and adds constraints like date range and data availability. This fully guides selection among siblings.

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