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

Annotations already declare readOnly/idempotent/non-destructive, so the burden is lower; the description still adds real value by disclosing data sources (SSE yunhq, SZSE ssjjhq), that they are keyless, and the history depth limit (weekly up to ~6 years / 312 bars). It does not cover rate limits, freshness/latency, or failure modes for unsupported codes.

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?

Front-loads the resource, then coverage, then depth/limits, then example questions — a sensible order. It is dense with code lists and quotes that border on redundancy with the schema's index description, costing a little tightness.

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?

With no output schema, the description correctly fills the gap by saying what a bar contains (OHLC + volume + turnover) and that `years` returns close plus year-over-year pct_change. Combined with source and depth limits, an agent has enough to call this correctly without further inspection.

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, and the description goes beyond it by mapping modes to real questions ('5 years of annual closes for CSI 300') and repeating the override semantics that `years` supersedes weeks/days. It adds semantic grounding rather than just restating parameter names.

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?

States a specific verb+resource: daily/weekly/annual OHLC + volume + turnover bars for named China A-share indices, and enumerates exactly which indices are covered with codes and exchanges. It never names the sibling ashares_market_bars, so an agent must infer that index bars are distinct from stock bars rather than being told.

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 contexts via sample questions ('Shanghai Composite last 10 days', 'CSI 300 annual close 2020-2025') and explains that `years` is for multi-year annual-close questions, which implicitly routes the agent between modes. It does not state when to avoid this tool or point at the sibling index/stock alternatives.

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