detect_ytd_high_low

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

Beyond the readOnly/idempotent annotations, the description discloses substantial behavioral context: it compares today against every session since the first trading day of the calendar year, matches Kabutan/Yahoo! conventions, uses a nightly pre-computed cache for default params (sub-second), requires date within the past 52 weeks, and notes data availability at ~17:15 JST. This fully informs the agent of performance and data freshness characteristics.

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 and front-loaded, but it contains slight redundancy: 'All plans.' appears both in the first sentence and again in the '[Supported plans]' line. Otherwise, every sentence earns its place, and the Args section is clear. A minor deduplication would make it perfect.

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 an output schema is present, the description does not need to document return fields. It covers purpose, usage boundaries, behavior, supported plans, and all parameters with semantics and defaults. It also explains the historical comparison convention and cache behavior. No critical information is missing for correct tool selection and invocation.

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?

The input schema provides only types and defaults (0% description coverage). The description's Args section fully compensates by explaining each parameter: date format and range, code's optionality and cross-sectional behavior, min_prior_sessions meaning including the disable value (1), and detail's effect on output (summary counts vs full array). This is exemplary parameter documentation.

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 verb-resource pair: 'Screen for year-to-date high/low records.' It also provides Japanese equivalents (年初来高値/安値) and explicitly differentiates from sibling tools by naming detect_ytd_high_low_range and detect_52w_high_low, making the purpose unmistakable.

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 gives explicit usage guidance: 'Use for 年初来高値, 年初来安値, YTD high/low, 年初来高値更新.' It also states when NOT to use it: 'For multi-date scans use detect_ytd_high_low_range (not repeated calls here). For 52-week rolling window use detect_52w_high_low instead.' This is a model of clear when/when-not guidance.

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