prepare_chart_data

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

With zero annotations, the description bears the full burden — and it delivers. It discloses the response shape ({times, labels?, candles, series?, subPanels?}), the default (candles only), JPY integer rounding, automatic exclusion of all-null series, timezone label behavior, and the context-consumption cost of stacking indicators. This is a thorough behavioral contract that leaves little to inference.

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?

Well-structured and front-loaded: warnings come first with ⚠️ markers, followed by default behavior, response format, and sibling routing. The JSON response sketch earns its space, and the indicator list is reused both as reference and as a 'specify explicitly' reminder. Slightly long, and the indicator enumeration partially duplicates the input-schema enum, but every section adds operational value.

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?

Complete for a 5-parameter, no-output-schema, no-annotation tool: full response format, parameter guidance, and routing all present. Remaining gaps are minor — no semantics for pair/type, no error or auth notes (likely N/A here), and the boundary against get_candles/prepare_depth_data is implied rather than stated. Strong coverage of the core calling contract.

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 only 20% (only tz is described), so the description must compensate. It does add real meaning for limit (the recommended-default rationale and the 'only raise when user specifies a period' rule) and indicators (usage restraint plus enumeration), and it re-explains tz with a concrete example. But two parameters get zero added semantics: pair (bare 'btc_jpy' default, undocumented everywhere) and type (timeframe enum listed with no guidance on selection). Partial compensation for an 80% coverage gap is not full compensation.

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 clear mission statement — 'チャート描画の第一選択ツール' (the first-choice tool for chart drawing) — and specifies the exact resource (OHLCV candlestick chart data) with optional indicator overlays. It actively differentiates itself from siblings by routing SVG/PNG saving to render_chart_svg and indicator analysis to analyze_indicators, so an agent can distinguish this tool from its neighbors without opening their schemas.

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?

Provides concrete usage rules: default limit=30 unless the user specifies a period, indicators only when explicitly requested, and minimize indicator count to protect context. It also routes to alternatives (render_chart_svg for file output, analyze_indicators for trend/value reads). However, it never explicitly contrasts itself with get_candles or prepare_depth_data — an agent is told 'first choice' but not told when those siblings should win instead.

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