A股数据 API (A-Share Data API)

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

No annotations provided, so the description carries full burden. It correctly identifies this as '只读查询' (read-only query), which is critical behavioral information. It also warns that historical modes require a real trading day and return empty on non-trading days ('非交易日返空'). It could go further on rate limits or response shape, but the read-only nature and the trading-day constraint are the key operational facts.

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 dense but front-loaded: it leads with the core concept and usage scenario, then enumerates modes, then lists fields. Every sentence serves a purpose, though the field enumeration (reason, pct, board_desc, etc.) is somewhat lengthy and could arguably be inferred from the output schema. Still, the structure is logical and information-rich.

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 an output schema present, the description need not explain return values in detail, yet it does list key fields, which is helpful but redundant. The description covers all three parameters' semantics, the read-only behavior, the trading-day constraint for historical modes, and the mode selection logic. The only gap is lack of explicit mention of rate limits or pagination, but for a read-only query with a limit parameter, this is minor.

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 100%, so the schema already documents each parameter and mode value. The description restates the mode enum values but adds little new semantic depth—the same information is in the schema's mode description. The date format and limit constraint appear in both places. The description does add the '历史类 mode 的 date 须为真实交易日' warning, which enriches the date parameter meaning beyond the 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 verb+resource pairing: '异动/偏离值（短线监管异动体系）' and immediately identifies it as the short-term regulatory anomaly detection system. It goes further to enumerate multiple sub-modes (严重异动, 10日100%偏离, 盯盘名单) that tell an agent precisely what data surface this tool covers. This clearly distinguishes it from siblings like ashare_changedist or ashare_lhb.

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?

Explicitly states when to use: '用户问今天有哪些异动股/偏离值/触发严重异动/被监控的票/短线风险股用这个.' It then maps each mode to its use case (deviation for today's hot list, deviation_hist needs date, abnormal needs date, watch for today, alert for severe anomaly alerts). The condition for each mode is fully spelled out.

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

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

With no annotations present, the description carries the full behavioral burden and does so in detail: refusal semantics (ok:false + reason, never substitute another field), channel isolation when scope=web/wechat and the requirement of a customer-supplied X-LLM-Key with the cost borne by the caller, the degraded-capability warning tied to interpreted.intent_source=llm vs rules_fallback, and the replay non-determinism caveat. It also discloses a subtle correctness trap — value is the verbatim source value while readable is the safe-to-quote conversion — and forbids derived quantities not present in the source.

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 purpose statement is front-loaded and correct, but the body is roughly 700 words for a 3-parameter tool, dense with ⭐/⚠️/⛔ markers increasing emphasis without increasing information. Several points are re-stated (refusal behavior appears twice, the readable-conversion rule is repeated) and a large block re-documents the return structure. Most sentences do carry real guidance, so this is bloat rather than filler, but it is well past the size the task warrants.

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 a natural-language-to-query tool with a large result envelope, the description covers what an agent actually needs to act correctly: domain coverage, refusal behavior, per-row quality thresholds (rerank_score ≥1.5 = good), and how to quote values safely. Because an output schema exists, the long walkthrough of data[]/citations[]/verification[] is largely redundant and displaces information the description genuinely lacks, such as the undocumented recency format. The result is complete on policy but over-explained on returns.

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 would be 3, but the description spends several paragraphs on `scope` and `replay=true` as though they were call arguments, and neither exists in the input schema. That is actively misleading: an agent following the text will pass scope=web or replay=true and be rejected, while the real parameters (recency, max_results) get no explanation beyond their schema strings. The valuable semantic content it does add (max_results caps evidence rows, q accepts full sentences) is already in the 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 opening line names a specific transformation: natural-language question → our own data endpoint, returning a structured row plus evidence fields (value_hash / source_endpoint / params / as_of). It explicitly separates itself from ashare_evidence (keyword search over announcements/news/research) which is a genuinely useful sibling distinction. What it does not do is distinguish itself from the many structured siblings that answer the same questions directly (ashare_fund_flow, ashare_quote, ashare_lhb, ashare_news), so an agent still cannot tell when the NL wrapper beats a typed endpoint.

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?

Gives a concrete, actionable routing rule: "问'多少/怎么样/是什么'用这个；问'发了什么公告/有什么新闻'用 evidence" — a real when-to-use vs. when-to-use-other statement. It also enumerates supported domains and, unusually, an explicit not-supported list (sectors, market stats, technicals, fundamentals, attribution, prediction) with the promise of ok:false refusal rather than substituting fields. The gap is that it never tells the agent when to prefer a specific typed sibling over this wrapper, and the routing rule only covers one of ~70 siblings.

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

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

With no annotations, the description carries the full burden and does well: it discloses read-only behavior, that the tool does not select or predict, and an important behavioral fork — optional BYOK via the X-LLM-Key header for model-polished output versus deterministic review without it. It does not cover cost, latency, or failure behaviour when the snapshot ID is invalid, which keeps it out of 5 territory.

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?

Two tight, front-loaded blocks: purpose plus output, then the operating constraints and the BYOK caveat. The warning glyph makes the optional-header nuance scannable. Slight redundancy in enumerating return fields that the output schema already defines.

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?

An output schema exists, so return values need not be described, yet the description names them anyway as a helpful orientation. Combined with the read-only declaration and the BYOK path, an agent has enough to call this correctly; only edge cases (invalid snapshot, what a 'data gap' means in practice) are unaddressed.

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 100%, so the schema already documents focus (overall/winners/losers/attribution) and horizon (1/5/20). The description only restates the snapshot_id input and adds no further meaning about how focus or horizon change the report, so the baseline 3 applies.

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 role (复盘分析师), a specific input (scanner 快照 ID), and a concrete output set (收益/基准/超额/命中率、赢家输家、数据缺口、复盘报告), so the agent knows exactly what this tool produces. The scope negation '只读、不选股、不预测、不推荐买卖' separates it from screening/selection siblings like ashare_scanner or ashare_screen, though no sibling is named directly.

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 requirement to supply a scanner snapshot ID implies the workflow ordering (scan first, then review), and '不选股' implies when-not-to-use. But there is no explicit statement of when to pick this over ashare_snapshot, ashare_review, or ashare_scanner, and no exclusions or prerequisites spelled out beyond the ID format.

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

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

No annotations are provided, so the description carries the full behavioral burden, and it does: it discloses the 1-4 option return shape, that option explanations are model-generated, that quality degrades without the X-LLM-Key header (raw candidates only), and the precise meaning of the needs_clarification flag. Auth context and degraded-mode behavior are both covered.

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-loaded with the core purpose and organized under clear markers (when-to-use, caveats, exclusions), with the most decision-relevant information first. It is somewhat dense and emoji-heavy, but each line carries distinct actionable content rather than filler.

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?

An output schema exists, so return values need no explanation, yet the description still supplies the two decision-critical flags (needs_clarification, chosen_code) and the X-LLM-Key dependency. For a disambiguation gatekeeper tool, an agent has everything needed to call it and act on the result.

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?

Only one parameter with 100% schema description coverage, so the schema already documents q fully (raw question, passed verbatim without simplification). The description adds no syntax or format detail beyond that, making the baseline of 3 correct.

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+scope: ask the user when the entity reference is ambiguous, returning 1-4 annotated candidates rather than choosing for the caller. It explicitly distinguishes itself from siblings with '本工具不查数据，只做消歧' and names ashare_agent_search / ashare_quote as the follow-up tools.

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?

Explicit when-to-use ('用户只给了模糊名称…不确定指哪家公司时') and when-not-to-use (it does not fetch data; use ashare_agent_search or ashare_quote after obtaining the code). It also explains the escape hatch: when needs_clarification=false the ambiguity is already resolved and chosen_code should be used directly.

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

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

With no annotations, the description carries the full burden and does it: it declares the tool read-only, discloses that it is a paid feature gated to the ¥99 professional tier, explains the exact rule behind is_limit_up/is_limit_down, and warns that mode=stock is current-day only. These are exactly the traits an agent cannot get from schema or annotations.

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?

Purpose and trigger examples are front-loaded, then mode semantics, then output fields, then constraints. Dense but organized; the field-by-field enumeration (up_px/down_px/hprice/lprice/open_px/preclose_px) is somewhat redundant given an output schema exists.

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?

For a 3-parameter read tool with an output schema, the description covers trigger conditions, mode selection, date requirement, access tier, and read-only safety. An agent has everything needed to call it correctly without follow-up.

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 100%, so baseline is 3. The description still adds value by spelling out that mode=stock is minute-level tick data, stock-history is second-level, volume is a single point, and that date must be a real trading day — nuance the terse schema strings do not convey.

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: intraday call-auction (集合竞价) data for an individual stock, including limit-up/limit-down touch detection. The three modes and the derived flags (is_limit_up / is_limit_down) make it clearly distinct from generic siblings such as ashare_minute or ashare_quote.

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?

Gives concrete user phrasings that select this tool ('竞价分时 / 竞价怎么走的 / 哪些票竞价就涨停了') and explicitly routes history requests to mode=stock-history with a required date. It never names a sibling tool as the alternative for the non-auction minute data case, so it stops short of full when/when-not coverage.

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

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

With no annotations, the description carries the full burden and does so well: it discloses the two modes and their constraints, that portfolio intervals are limited by preset batches, that inv_vol requires portfolio mode plus institutional tier, that it is a paid tool with tiers (¥29.9+ Standard, Pro+ for portfolio/batch) and separate daily quota checkable via ashare_usage. It stops short of stating latency/expected runtime or failure behavior, which keeps it below 5.

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?

Purpose and trigger phrases are front-loaded, and the ⚠️ blocks make the high-risk constraints (mode/code pairing, tier requirement, cost) scannable. It is dense and emoji-heavy, but essentially every warning carries decision-relevant information, so little is wasted.

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?

An output schema exists, so return values need not be explained. For an 8-parameter, paid, mode-dependent tool, the description covers everything blocking a correct call: the mode/code pairing, weighting availability, prerequisite lookup via ashare_strategies, quota/pricing gating, and the batch alternative.

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% and the schema descriptions already state the mode=single/code dependency, the inv_vol restriction, and the include_equity data-volume tradeoff, so the description mostly restates structured data. It does consolidate the cross-parameter conditional logic into a usable decision framing, but adds little meaning that the schema does not already carry — baseline 3 is appropriate.

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?

Opens with a specific verb+resource ('量化回测：按策略跑历史收益') plus the concrete outputs (收益/最大回撤/交易次数/净值曲线), so the agent knows exactly what comes back. It explicitly differentiates from siblings by naming ashare_backtest_batch and ashare_strategies as the tools for multi-target runs and strategy discovery.

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?

Gives direct user-phrase triggers ('回测一下/这个策略收益如何/买卖点效果/最大回撤') that select this tool, and explicit exclusions routing to ashare_strategies (to see strategy lists) and ashare_backtest_batch (multi-target × multi-strategy). Nothing about tool selection is left to inference.

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

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

With no annotations, the description carries the full burden and does well: it discloses hard limits (≤20 codes, ≤10 strategies, ≤60 combos), that over-limit fails loudly rather than silently truncating, that combo strategies are unsupported, and that it is a paid tool requiring Pro (¥69) with its own daily quota. It stops short of describing auth mechanics or response shape, but the safety/constraint profile is well covered.

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 key point (batch multi-symbol × multi-strategy comparison) is front-loaded, followed by routing guidance and warnings. It is dense and emoji-heavy but nearly every clause earns its place; the formatting is slightly noisy but not padded.

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?

An output schema exists, so return values need not be explained, and the description still notes the comparison-matrix output. Combined with the limits, paid-tier requirement, and strategy-type restriction, an agent has everything needed to invoke this correctly versus its sibling.

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, but the description adds value beyond the schema: parameters may be passed as lists and are auto-converted to comma-separated strings, and per-parameter count ceilings are restated. This exceeds what the schema alone conveys.

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 states a specific verb+resource (批量回测: 多标的 × 多策略, returns a comparison matrix) and explicitly contrasts itself with the sibling ashare_backtest (single strategy). An agent can distinguish this tool from ashare_backtest and ashare_strategies without opening any schema.

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?

It names the exact user phrasings that should trigger this tool ('这几只股票用不同策略分别跑一下/批量回测/策略对比') and gives the alternative plus the condition selecting it (ashare_backtest for a single strategy). When-to-use and when-to-use-the-other are both explicit.

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

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

No annotations exist, yet the description discloses the traits that actually block misuse: only current-day data (most recent trading day on holidays/pre-open, verifiable via top-level `day`), an in-progress point count (~242 points, growing during the session), the aggregation caliber of the metric, and that non-institutional tiers get an explicit message plus upgrade link rather than silent failure. That is exactly the behavioral context annotations would otherwise carry.

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-loaded: definition and `net` semantics first, then usage triggers, then caveats, then sibling split. Every caveat carries real information, but the heavy ⚠️/emoji formatting and repeated warnings make it denser than a scanning agent would prefer.

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?

Output schema exists so return values need not be explained, and the description still points to the top-level `day` field an agent must read. Access gating, timing behavior, metric caliber, and the sibling boundary are all covered — nothing needed to call it correctly is missing.

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?

Single parameter `code` with 100% schema description coverage (sh600667 or 600667), so the schema already does the work. The description adds no extra syntax, market-prefix, or validation meaning beyond it — baseline 3 for a fully documented single param.

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 resource and granularity — "单股 L2 大单资金分时（分钟级）" — and immediately defines the semantics of the only output concept (`net` = 大单净额，正=净买入). It also names what it is NOT (逐笔委托 / 十档盘口) and separates itself from `ashare_fund`, so an agent can place it without opening 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?

Gives concrete trigger phrasings ("大单在买还是卖/主力资金分时/哪一分钟砸盘") and an explicit split rule against `ashare_fund` (趋势 vs 快照). However it never differentiates among the six closely-named siblings (ashare_bigorder_flow, _history, _queue, _rank, _split), which is the main confusion risk for this tool.

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

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

No annotations, so the description carries the full burden and does: current-day-only with fallback to the most recent trading day on holidays/pre-open, a hard cap of ~200 rows with instructions to raise `money` when `total` > `returned`, and an institutional-tier gate that returns an upgrade notice for other plans. These are exactly the operational behaviors an agent needs before calling.

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-loaded with the resource, then use cases, then sibling routing, then caveats — a good structure. Slightly dense: the full `direction` enumeration and row-field list partially duplicate the output schema, so not every token is strictly new information, but nothing is genuinely wasted.

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?

For a 3-parameter read tool with an output schema and no annotations, the description covers everything that matters: scope (today only), truncation handling, access tier, and interpretation caliber. Return-shape explanation can be left to the output schema, and it is.

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 `code`, `limit` and `money` are already documented including the 0=30万 … 4=1000万 ladder. The description's only added value is the workflow hint that raising `money` is the remedy when `total` exceeds `returned`, which is useful but modest; baseline 3 applies when the schema does the heavy lifting.

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?

Names a specific resource and granularity: L2 large-order trade prints for the current day, every fill tagged active/passive × buy/sell. It also explicitly contrasts itself with the nearest sibling (`ashare_bigorder` gives per-minute net curves, this gives tick-level detail with a four-way split), so an agent can pick between them without opening either schema.

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?

Gives concrete user phrasings that should route here ('谁在主动买/有没有人在扫货/大单是主动还是被动成交') and names the alternative tool with the criterion that selects it. It also states what this is NOT (not tick-by-tick order queue, not level-10 order book), which prevents a common misselection.

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

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

With no annotations, the description carries the full burden and does well: it discloses that the data source always returns 100 trading days, that limit only truncates locally (saves bandwidth, not calls), that the metric is the big-order caliber and is not 主力净额/龙虎榜/逐笔, and that non-institutional tiers get an upsell message instead of data. It doesn't cover error behavior or response size beyond the fixed 100 rows, which keeps it just short of a 5.

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-loaded with what the tool returns, then when to use it, then the sibling split, then caveats — a sensible order with essentially no filler. The heavy ⚠️/⭐/⛔ marker formatting is dense but each sentence carries information.

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?

An output schema exists, yet the description still names the row fields (date/net) and their semantics, which is a bonus rather than a redundancy. Combined with the tier restriction and truncation caveat, an agent has everything needed to call this correctly and to explain the result.

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, but the description adds real meaning the schema doesn't: limit is a local truncation of the fixed 100-day payload and does not reduce the underlying call. The row field names and unit (元, positive = net buy) are also spelled out.

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 gives a precise verb and resource (L2 历史大单净额, daily, up to 100 trading days back) and states the unit (元) and ordering (倒序). It explicitly distinguishes itself from the sibling ashare_bigorder, so an agent can pick between them without opening either schema.

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?

It names the user phrasings that trigger it (吸筹/趋势/前几个月怎么走) and states the alternative explicitly: ashare_bigorder only covers today, while this tool provides the backward look for judging sustained accumulation vs a one-day spike. There are no exclusions an agent must infer.

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

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

With no annotations, the description does most of the work. It discloses that this is same-day only, that this is 委托 order flow rather than 成交 or 十档盘口, that this is institutional-edition-only, that a single call returns about 200 records at most, and crucially that meta cancel_ratio is scoped to 'returned_rows' rather than the full day. I deducted one point because it never spells out the read-only, non-mutating nature or any pagination/rate behavior.

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 front-loaded with the core concept in bold, then the caveats and the sibling distinction. It is information-dense and mostly earns its length, though the row-field and meta-field enumerations partly duplicate the output schema that already exists.

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?

For a 4-parameter, single-purpose data query, the definition includes everything an agent needs: what the data is, when to use it, its limits, its time scope, its edition restriction, and a statistical-scope caveat on meta. The output schema covers the return shape, and the prose still clarifies some of it.

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, but the description adds the enumerated tur and vol thresholds and the approximately 200-record cap for limit, which is more than the schema says. It does not explain how vol and tur combine or which one takes precedence, which keeps it from a 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 states a specific verb and resource, namely L2 large-order pending orders (挂单) for a stock, and explicitly contrasts it with the sibling ashare_bigorder_flow: 'queue = 挂单（可能撤），flow = 成交（真买了）'. An agent can tell the two apart without opening either schema.

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?

It directly maps user intents to the tool, such as '封单是真的吗', '有没有大单挂了又撤', and '假封单'. It states that queue and flow should be viewed together, which names the alternative and explains why. It also mentions this is same-day only and lists the permitted vol and tur values.

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

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

No annotations are provided, so the description carries the full burden and does disclose useful behavior: approximate universe size (~5568), data volume (~1 MB at limit 6000), amount units in yuan, negative main_sell values, the main_buy + main_sell == main_net identity, market_cap caveat, and institution-only entitlement. It still does not cover authentication mechanics or rate limits in detail, so 4 rather than 5.

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 purpose is front-loaded and most details earn their place: sort modes, use cases, identity check, drill-down path, limits, and caveats. It is still dense and partly repeats schema/output information, especially the sort list and row-field list, so it is not maximally concise.

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 complexity, the existing output schema, and the absence of annotations, the description is complete enough for correct invocation: it covers scope, sort behavior, pagination, output units, self-check identity, drill-down alternatives, and important field caveats. An agent has what it needs to call this tool and interpret the result.

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 100%, so the baseline is 3. The description repeats the sort values and limit maximum already present in the schema, and only adds minor context such as ~1 MB size and pagination behavior, so it does not substantially exceed the schema's 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?

States a specific verb and resource: L2 all-market main-force net ranking covering about 5568 stocks, with eight sort modes and pagination. An agent can immediately tell this is a broad ranking/list tool rather than a single-stock detail tool.

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?

Gives concrete user questions that select this tool (what main funds are buying, largest inflows, who is being sold, which sectors are being bought) and routes deeper inspection to ashare_bigorder and ashare_bigorder_split. It does not explicitly distinguish when to prefer this over related siblings such as ashare_bigorder_flow or ashare_bigorder_history, so it stops short of full 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.

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

With no annotations, the description carries the full burden and does so well: it discloses output field semantics, units (元), sign conventions (main_sell negative), weighted average price fields, historical vs real-time behavior, institutional-only access, and explicit scope exclusions (not order queue, not orderbook).

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 dense but front-loaded with the core purpose and usage trigger. The lengthy enumeration of row fields duplicates the output schema, so a small amount of redundancy keeps it from a 5, but the structure and emphasis markers make it scannable.

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 a complex financial data tool with an output schema and no annotations, the description is complete: it covers purpose, usage, alternatives, parameter behavior, output semantics, access limitations, and scope exclusions. Nothing an agent needs to call it correctly appears to be missing.

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 100%, so both parameters are already documented. The description re-emphasizes the `date` default behavior and code format, but adds little semantic detail beyond what the schema already provides.

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 states a specific verb (拆分/decompose) and resource (L2 主力四分解, minute-level main-buy/main-sell decomposition into active/passive components). It explicitly distinguishes itself from the sibling `ashare_bigorder_flow`, so an agent can tell them apart without opening 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?

Gives explicit user-question triggers ('主力主动买多少、被动买多少/是扫货还是被砸/买卖均价多少'), names the alternative `ashare_bigorder_flow` and the condition that selects it, explains date-param behavior (historical vs real-time), and warns what the tool is not (order queue / orderbook).

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

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

No annotations are provided, so the description carries the full burden and does so: it discloses the全市场 vs single-stock scope switch, the default-to-latest-trading-day behavior, and — critically — the non-obvious fallback that an empty result returns quote meta-info instead of an error, plus how to detect it (presence of TurnoverPrice/BuySalesDepartment).

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 purpose and field list, then usage triggers, then parameter warnings, then sibling differentiation. Every ⚠️ block covers a distinct failure mode; nothing is redundant filler.

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 an output schema present the description needn't enumerate normal return fields, and it still goes further by explaining the degenerate no-block-trade response. For a 2-param, zero-annotation tool this is 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 100% and both parameters already document their empty-value semantics ('留空=当日全市场', '留空=最近交易日'). The description restates the same semantics rather than adding format, validation, or example detail, so the baseline 3 applies.

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?

Opens with a specific verb+resource (大宗交易成交明细) and enumerates the returned fields (成交价/成交量/成交额/折溢价率/买卖方营业部). It explicitly distinguishes itself from the closest sibling: 'ashare_fund 的大宗只是概览一行；本工具是逐笔明细'.

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?

Gives concrete user-intent triggers ('有没有大宗交易/折价还是溢价成交/谁在接盘/机构席位'), states the when-not condition via the ashare_fund comparison, and explains both optional-parameter defaults. An agent knows exactly when to route here.

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

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

No annotations are provided, so the description carries the full burden. It discloses that the operation is read-only ('只读查询') and warns that market prices are not returned, which is a key behavioral trait. It also provides code format examples (sh vs sz) that reduce error risk. While it doesn't cover every possible behavior (e.g., rate limits), it adequately discloses the main safety and scope 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 three sentences, front-loaded with the returned fields, then usage guidance, then warnings and format. Every sentence earns its place; there is no repetition or padding.

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?

For a single-parameter, read-only query tool with an output schema, the description covers purpose, usage, exclusions, safety, and code format. Nothing essential is missing; the output schema handles return-value details.

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 schema already describes the single parameter 'code' with an example, and coverage is 100%. The description adds meaningful beyond that by explaining the code format distinction between Shanghai (sh) and Shenzhen (sz) and giving concrete examples, which helps the agent pass a valid value. This goes beyond the schema's bare minimum.

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 states a clear purpose: it provides full terms for convertible bonds, listing specific metrics (premium rate, conversion value, double-low value, etc.). It explicitly distinguishes itself from ashare_quote by noting that market prices are not covered, so an agent can instantly tell which tool to use.

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 conditions: 'use this when users ask about bond terms/strong redemption/double low/premium' and warns 'for bond market price, use ashare_quote'. This is textbook when-to-use and when-not-to-use guidance that names the exact alternative.

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

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

No annotations are provided, so the description carries the full burden and does so well: it discloses the empty-date weekend fallback, the need to pass statutory holidays explicitly, the meaning of is_fallback=true, and that the tool is restricted to the institutional edition. These are exactly the non-obvious operational behaviors an agent needs.

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 front-loaded with the core definition and keeps warnings in a compact, scannable form. However, the row-field enumeration is somewhat redundant because an output schema already exists, and the dense bold/emoji formatting is less clean than plain prose.

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 no annotations and an existing output schema, the description supplies the missing behavioral context: fallback logic, holiday handling, institutional restriction, sibling relationship, and intended user questions. Nothing critical for correct invocation is absent.

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 useful date semantics beyond the schema by explaining weekend fallback and statutory-holiday handling, though it does not further explain the limit parameter beyond what the schema already says.

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?

Starts with a precise definition: broken-board history for a given day's limit-up stocks whose limit was opened. It explicitly distinguishes the resource from ashare_limit_up by stating that limit-up is sealed while this tool is unsealed. The row fields further confirm exactly what the tool returns.

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?

Gives explicit trigger phrases ('今天有哪些票炸板/封板质量怎么样/哪些涨停被砸开') and names the complementary sibling ashare_limit_up with the comparison rationale. An agent knows both when to use this tool and how it relates to the alternative.

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

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

With no annotations, the description carries the burden and does well: it declares the tool read-only, discloses that the return structure differs by market (A-share event summary vs HK daily detail) with the exact column sets, and states the subscription tier required (Standard ¥29.9+). It omits behavior for empty ranges and any pagination or result-size limits.

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-loaded with the purpose and trigger questions before the structural warnings; every sentence carries content. Heavy use of emoji/warning markers adds visual noise without adding information, keeping it from a 5.

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?

Even though an output schema exists, the description proactively explains the market-dependent return shape that an agent would otherwise mis-parse, plus the access tier and sibling distinction. Nothing needed to call or interpret it correctly is missing.

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 100% (code, start, end all documented), so the schema already does the parameter work. The description adds no syntax or format guidance for the date range or the sh/hk code prefix convention beyond what the schema states, so baseline 3 applies.

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 and resource (company share buyback records) and explicitly distinguishes itself from the closest sibling, ashare_shareholder, as 'the company buying itself' vs 'who holds shares'. An agent can route correctly without opening either schema.

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?

Gives concrete user-question triggers ('is this company buying back / how much / at what price') and names the alternative tool with the distinction that separates them. Both when-to-use and when-not-to-use are present.

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

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

No annotations exist, so the description carries the full burden, and it does disclose non-obvious traits: segmented, order-preserving returns, segments absent when a category has zero events, `limit` being advisory only, and HK ticker support. Some of this restates the return shape already covered by the output schema, which keeps it from a full 5, but the quirk disclosures are genuinely value-adding.

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-loaded with the resource and usage triggers, then warnings, so the important routing information comes first. It is dense and the `limit` caveat is repeated (also present in the schema), and the exhaustive slug enumeration is longer than strictly needed, but nothing is superfluous enough to hurt.

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?

For a two-parameter, optional-argument tool with an output schema, this covers everything an agent needs: what it returns, how to safely read a segment, why segments can be missing, and that HK symbols work. No material gap remains.

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 both parameters are already documented; the description still adds meaning by stating the window is roughly one month long (not derivable from the schema) and by stressing that `limit` is only a suggested value with per-segment counts differing. It does not add format details for `date` beyond what the schema says.

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 concrete resource (company event schedule covering dividends, lockup releases, earnings, IPOs, meetings, rights issues) and the exact window (~1 month from a given date). It explicitly names what it is not ('not a macro data calendar') and points to the sibling `ashare_macro`, so an agent can separate it from the many other ashare_* tools.

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?

Gives concrete trigger phrasings ('which stocks unlock next week / who reports soon / which dividends this month') and an explicit exclusion with the correct alternative (`ashare_macro` for GDP/CPI/LPR). The precondition for reading a section (check `data.data` for the slug first) is also spelled out.

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

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

No annotations provided, so description carries burden. It discloses data currency (current period) and distinguishes from T-1. But it does not explain output structure or any limitations beyond data currency, which is partially mitigated by output schema existing.

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?

Concise, front-loaded with key purpose, includes warning and free tool note. Slightly dense with many details but useful; no fluff.

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?

For a zero-parameter tool with output schema, description covers usage context, data categories, and sibling distinction. Complete enough for correct invocation, though return format is left to output schema.

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?

Zero parameters, so schema is trivial. Description adds context on data scope and usage, but does not describe any parameters since none exist. High value in explaining what the output covers.

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?

Description states it provides market breadth data with enumerated contents (up/down counts, limit-up/down, distribution, turnover). Purpose clear, but does not explicitly name siblings to differentiate beyond mentioning ashare_market_overview.

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?

Explicitly tells when to use ('user asks today's up/down counts...') and when not to use (warning against ashare_market_overview for same data due to T-1 discrepancy). Also notes it's free/no key.

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

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

With no annotations, the description carries the full burden and does: paid tool requiring a Key (体验版及以上), free/anonymous unavailable; history limited to ~1 year; non-trading-day or future dates auto-fall-back to the nearest trading day with the returned row's `date` authoritative. These are exactly the operational traits an agent needs before invoking.

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-loaded with purpose and trigger questions, then bulleted ⚠️ caveats that each carry distinct information (batch routing, date rules, code formats, ETF scope, payment). Dense but every line earns its place; slightly repetitive on the ETF/面 code notes.

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?

An output schema exists, so return values need no explanation, and the description still covers the remaining gaps: auth/cost, universe exclusions, date fallback, and code format. An agent has everything needed to call it correctly and interpret the result.

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, but the description adds semantics beyond the schema: the date fallback behavior and the 'trust the returned date' rule, plus confirmation that both `sh600667` and bare `600667` forms work and ETF codes are valid. Marginal value above the schema, not below.

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?

Names the specific resource (筹码分布/持仓成本) and enumerates the returned metrics: 获利盘比例, 平均成本, 90%/70% 集中度, 收盘价, plus the exact user questions it answers. It also names the sibling ashare_chip_batch as the multi-stock alternative, so an agent can distinguish it without opening the schema.

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?

Explicit routing rule: multiple stocks → ashare_chip_batch (200 at a time, per-stock success flags); this tool queries one. It also states supported universe (沪深A股 + ETF) and excludes 港美股, and maps natural-language user questions to this tool.

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

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

No annotations are provided, so the description carries the full burden, and it does disclose a lot: paid tiers (Pro ¥99+), per-call caps of 200/300, billing by actually returned rows, ~1 year of history, A-share-only scope with ok:false for HK/US/sector codes, and non-trading-day fallback. It stops short of describing failure modes like rate limits or partial-timeout behavior, so it is strong but not exhaustive.

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?

Purpose and the sibling comparison are front-loaded, and every section carries distinct information (comparison, performance rationale, usage, return shape, scope, limits, pricing). It is nonetheless heavy with emoji warning markers and bold emphasis, which adds visual noise to an already long block.

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 annotations and an output schema present, the description still covers scope limits, tier caps, pricing, date fallback and the requested/returned/failed envelope. An agent has everything it needs to decide and invoke correctly.

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 both parameters are already documented, giving a baseline of 3. The description does add meaning the schema lacks — bare 6-digit codes are accepted, and date applies globally to all codes with automatic fallback to the last trading day.

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 opening line names a specific verb and resource (batch chip distribution) and enumerates the exact metrics returned (profit ratio, average cost, 90%/70% concentration) plus the per-stock success flag. It explicitly distinguishes itself from sibling ashare_chip by explaining the N×8N diagonal-matrix defect of the single-code endpoint.

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?

It gives concrete user phrasings that should trigger this tool ('are these stocks' chips concentrated / how much is trapped / average cost'), states the alternative (ashare_chip) and why it fails for multiple codes, and notes that single-code queries are still acceptable here. When-to-use, when-not-to-use and the fallback option are all present.

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

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

With no annotations provided, the description carries the full burden and does so well: it discloses a hard cap of 15 codes with the consequence that the data source silently drops the rest (20 codes → 6 returned), that each code reports its own 'ok', that fields differ by market (A-share has targetPrice, HK has none and uses *Forecast fields), that it is read-only, and that it requires a paid tier (¥99+).

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-loaded with the resource name and purpose, then triggers, then warnings — every sentence earns its place. The heavy bold/symbol formatting and mixed-language phrasing make it slightly harder to parse than plain prose, but there is no filler.

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?

An output schema exists, so return values need not be explained. Combined with the market-dependent field warning, the batch-size truncation behavior, and the subscription-tier requirement, an agent has everything needed to call it correctly and interpret partial results.

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% and the single param is documented there, so the baseline is 3. The description adds real value beyond the schema by explaining that each code is processed individually and what happens when the ≤15 limit is exceeded — a behavioral consequence the schema does not convey.

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 resource (卖方一致预期 / analyst consensus) and enumerates exactly what it returns: target price plus forward estimates (EPS, revenue, net profit, forecast PE/PB/PS, coverage count). This is clearly distinguishable from nearby siblings like ashare_rating (ratings) or ashare_finance (reported financials).

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?

Gives concrete trigger phrases for when to call it ('机构怎么看/目标价多少/明年利润预测/一致预期'). It does not name an alternative sibling or state when to prefer ashare_rating or ashare_finance instead, so the routing guidance is clear but not exhaustive.

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

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

No annotations are provided, so the description carries the full burden. It discloses read-only semantics ('只读查询') and the update cadence ('按研报发布更新'), which is genuinely useful behavioral context. It doesn't cover auth/error behavior, but for a read-only query tool the disclosed safety profile and refresh cadence are solid.

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?

Compact and front-loaded with purpose, followed by routing, mode semantics, and safety. Every sentence earns its place, though the heavy formatting (bold, emojis, slashes) makes it slightly dense to parse.

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 read-only query tool with an output schema present: purpose, when-to-use, alternative, mode behavior, and read-only nature are all covered. The only gap is the limit default inconsistency, which originates in the schema rather than the description.

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 baseline is 3. The description adds value by explaining mode's two values and the constraint that detail requires a symbol ('mode=list 列表 / mode=detail 详情（detail 需给 symbol）'). Note a schema-internal inconsistency: limit has default 20 but its own description says '默认 10' – confusing but a schema issue, not a description issue.

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 and resource ('脱水研报' – broker research report summaries) and ties it to concrete user intents ('研报/机构观点/券商怎么说'). Explicitly differentiates from the sibling ashare_events, which handles stock news/announcements, so an agent can select the correct tool without opening either schema.

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 explicit when-to-use conditions ('用户问...用这个') and names the exact alternative with its selection condition ('要个股新闻/公告请用 ashare_events'). This is textbook routing that leaves nothing to inference.

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

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

With no annotations, the description carries the burden and does well: it declares read-only behavior, discloses the Hong Kong quirk where `disclosureDate` is often empty and the date lives in `disclosureDesc`, and notes the subscription tier gate (¥29.9+). It stops short of describing error behavior or pagination, so not a 5.

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-loaded with the resource and return fields, then usage, then caveats. Dense but every sentence carries signal; the bold/emoji formatting is heavy but functional. Slightly busy for a one-parameter tool.

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?

Output schema exists, so return values needn't be explained. The description covers markets, the HK caveat, tier gating, and sibling differentiation. Only minor gaps (e.g., behavior for invalid or ambiguous codes) remain.

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 100% and the single `codes` param is fully documented in the schema (comma-separated sh/hk/us prefixes). The description adds no format or batching guidance beyond that, so baseline 3 applies.

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: it returns the scheduled earnings disclosure date (`disclosureDate`), the report period (`reportEndDate`), and explanatory text. It also explicitly distinguishes itself from `ashare_calendar`, which covers dividends/unlocks/meetings, so an agent can route correctly without opening either schema.

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?

Names the exact user phrasings that should trigger it ('什么时候出财报/几号披露/三季报什么时候发') and gives an explicit exclusion ('与 ashare_calendar 不是一回事'). It also states the three supported markets (A股/港股/美股), leaving little to infer.

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

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

With no annotations, the description carries the full behavioral burden and does well by stating it is a read-only query, updated according to announcements, supports Hong Kong stocks via a 5-digit code format, and lacks ETF dividend detail. It does not discuss permissions, rate limits, or detailed return behavior, but the output schema exists and the safety profile is covered.

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 front-loaded with purpose and usage, then alternative routing, safety/update behavior, Hong Kong support, and ETF caveat. It is dense but every sentence carries a distinct operational point; slightly more structure could improve readability but there is no filler.

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 that the tool has only two well-described parameters and an output schema, the description is complete enough for correct invocation. It covers the main ambiguity against ashare_events, states read-only/update behavior, and handles Hong Kong and ETF edge cases.

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 100%, so the schema already explains both parameters. The description adds useful meaning for the code parameter by clarifying Hong Kong stock support with the hk00700 format, but it does not add much about years beyond the schema's default-3 documentation, so baseline 3 is appropriate.

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 states a specific resource and scope: historical dividend/bonus-share/ex-rights records with per-share dividend, bonus shares, and ex-dividend dates. It also explicitly distinguishes this tool from the sibling ashare_events calendar tool, so an agent can select it correctly.

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?

It says exactly when to use this tool for dividend/g股息/送转 questions and names the alternative for a dividend-payment calendar: use ashare_events instead. It further gives ETF-specific exclusions and points to the relevant ETF overview path.

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

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

No annotations are provided, so the description carries the full burden and does so: read-only, no quota deduction on invalid codes, 422 on multi-code, historical-snapshot edge cases (future date → latest trading day, pre-listing → all zeros with ok:false), and return-shape differences when `date` is passed. This is behavior an agent cannot infer from any structured field.

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-loaded with purpose and the kind menu before the warnings, and every warning carries operational weight. It is dense and warning-heavy with emoji markers, which slightly reduces scanability, but there is little genuinely dead text.

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?

An output schema exists so return values need not be described, yet the description usefully explains the data/structured/tables split and that 详情/公司 are multi-table — exactly the gap the output schema alone leaves for multi-table responses. Complete for a 5-param, single-required tool.

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 already 100%, but the description still adds material meaning: it explains what each `kind` yields, that `kind=净值` requires both start+end, and that passing `date` changes both the shape and code format (market prefix vs bare 6-digit) for 持仓. It tells the agent how to read the result, not just what the field is.

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 resource (ETF 数据) and enumerates the exact subset dimension via `kind` (概览/详情/持仓/净值/公司/持有人/财务). It explicitly differentiates from the sibling ashare_screen, so an agent can route without opening either schema.

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?

Gives explicit triggers ('用户问 ETF 时用这个'), the alternative for cross-sectional ETF queries (ashare_screen with mode=ranking/label, list=true), and hard exclusions (single stock code → ok:false, comma codes → 422, must call per-code). Covers when-not as well as when.

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

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

无注释，描述承担行为披露责任。描述声明'只读查询'和'按披露节奏更新'，提供了安全性和更新频率信息。但未说明返回值格式或错误处理，由于输出模式存在，描述不需要解释返回格式，因此4分合理。

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?

描述简洁，包含关键信息，有明确警告和替代工具。虽然有多余细节，但结构良好，核心用途在前。整体高效，给4分。

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?

工具只有一个参数，模式覆盖率100%，输出模式存在，描述提供了范围（单只股票）、事件类型示例、使用场景、替代工具和更新频率。无重大缺失，完整性高。

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?

模式覆盖率为100%，参数code已在模式中描述为'股票代码：sh600667'，描述未添加额外参数信息。按校准规则，高覆盖率下基线为3分，描述未增加价值。

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?

描述明确说明工具做什么：提供单只股票的事件标签，列举了42类事件（大宗/龙虎榜/回购/分红/解禁等），并与兄弟工具（ashare_lhb、ashare_dividend）区分，明确这是单只股票的事件总览，而非全市场名单。动词和资源清晰，区分度高。

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?

描述明确给出了使用场景：当用户问某只股票近期大事/解禁/回购/定增时使用，并明确指出当需要查看全市场某一类事件名单时应该使用ashare_lhb或ashare_dividend。提供了明确的何时使用和替代工具，指南完整。

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

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

No annotations are provided, so the description carries the full behavioral burden, and it does substantial work: per-source authority weighting, per-source quota splitting rationale, 5-minute result caching, report has no snippet, announcement links are PDFs. However, it omits error/auth behavior and pagination, so it is strong but not exhaustive.

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 purpose, sibling routing, and output shape are front-loaded and each warning marker flags a distinct caveat. It is nonetheless long, with a full enumeration of output row fields that partially duplicates the existing output schema.

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?

For a multi-source, deduplicating search tool this is complete: it explains sourcing, dedup, ranking order, authority tiers, relevance scoring, evidence-reproduction fields, and caching. An agent has everything needed to call it and interpret the result correctly.

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 100%, so the baseline is 3. The description does add value the schema lacks – that scope=report research reports count against a separate quota and carry no snippet, and that limit is split evenly across sources up to 30 – but the core parameter meanings are already documented in the 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?

States a specific verb+resource: cross-source keyword retrieval of cninfo announcements plus eastmoney news, normalized into one deduplicated table. It goes further and explicitly distinguishes itself from siblings ashare_news (by-code single target) and ashare_flash (market-wide stream), so an agent can disambiguate without opening 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?

Names concrete user intents ('这公司最近发了什么公告/有什么新闻/这消息哪来的/能不能核实') that select this tool, and spells out the division of labor against two sibling tools. It also flags when to widen scope (scope=report) and notes the extra quota is free and not crowded out by news.

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

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

With no annotations, the description carries the full burden and does so: it discloses the tool is a paid feature requiring a Key at Standard tier (¥29.9) or above, states the failure mode that English enum values return empty results, and clarifies the static/manifest nature. Auth requirements and silent-failure semantics are both surfaced.

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-loaded purpose followed by routing, constraint, and pricing warnings separated by emoji markers, which aids scanning. Slightly repetitive since the Chinese enum values echo the schema, but no sentence is wasted.

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 static listing tool: purpose, trigger, alternative, enum constraints, and pricing/auth are all covered, and an output schema exists so return values need not be described.

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 already 100%, so baseline is 3; the description adds real value by warning that category/kind accept only Chinese enum values and that English input yields empty results, plus enumerating category and kind values beyond the schema's abbreviated lists. It stops short of a full accepted-value list, so it is not a 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?

States a specific resource (量化因子库) with concrete scope (88 factors, 50 screening entries, 22 preset combos) and clearly scopes it as a static manifest, explicitly contrasting with ashare_screen for actual stock picking. An agent can distinguish it from every sibling without opening a schema.

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?

Gives an explicit trigger ('有哪些因子/因子库/选股因子/因子分类') and an explicit alternative with its condition ('要用因子实际选股，用 ashare_screen'), covering both when-to-use and when-not-to-use.

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

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

With no annotations, the description carries the full disclosure burden and does: read-only, update cadence tied to disclosure dates with a note that missing periods are not a fault, HK support, and a warning not to hard-parse HK column names against A-share conventions. It also reveals the return shape (three tables in fixed index order, descending by period).

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-loaded with the core purpose, then grouped warnings; every warning carries distinct information (table order, sibling routing, refresh cadence, HK parsing). Dense with repeated ⚠️ markers and bold, which is slightly noisy, but there is little outright filler.

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?

Despite an output schema existing, the description adds the one thing the schema cannot convey cheaply: which index is which statement and the descending period ordering. Combined with the freshness caveat and HK caveat, an agent has everything needed to call and interpret the result.

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 baseline is 3; the description adds real meaning on top by characterizing num as '最近 N 期' and, more importantly, documenting the HK code format `hk00700` that the schema's example (`sh600667`) does not cover. It stops short of spelling out edge cases such as num=0 or the maximum value.

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 and resource set (利润表/资产负债表/现金流量表, 最近 N 期) and explicitly maps conversational intents (营收/净利润/毛利率/负债) to this tool. It is clearly distinguishable from valuation siblings by the note that PE/PB belong elsewhere.

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?

Gives explicit when-to-use triggers ('用户问…用这个') and explicit when-not-to-use with named alternatives (ashare_sector_valuation / ashare_quote 的估值字段). The exclusion is unambiguous, so an agent can route without guessing.

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

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

No annotations are provided, so the description carries the full burden and does: response shape per item ({code, ok, data} or error), requested/returned/failed counts, A-share-only scope with ok:false fallback for HK/US, rate-limit behavior, billing by actually-returned stocks with refunds on throttling, and the paid-tier requirement (Pro ¥99+). This is unusually complete disclosure for a mutation-free but quota-sensitive tool.

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-loaded with the core purpose and the sibling differentiation, then organized under ⚠️ headers for limits/usage/return/billing. It is dense and long, with some repetition (the 10/20-stock cap appears in both the limits block and the codes guidance), but given the tool's quota and billing complexity nearly every sentence earns its place.

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?

Even though an output schema exists (so return values needn't be explained), the description still tells the agent what comes back and how failures are represented, plus the tier gate, quota math, and market scope. Nothing needed to call this correctly is missing.

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, but the description adds real meaning beyond it: comma-separated codes with bare 6-digit support, periods defaulting to 4 with max 12 and descending newest-first ordering, and the coupling constraint that stock count × periods consumes quota. Only minor duplication with the schema keeps it from a 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?

States a specific verb and resource: batch financial statements (income/balance/cashflow) for multiple stocks, with per-stock success marking. It explicitly distinguishes itself from sibling ashare_finance, noting that /v1/finance returns a flat 3-table blob where you cannot tell which stock failed. An agent can pick correctly without opening either schema.

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?

Gives concrete trigger phrasing (users asking about revenue/net profit/ROE/debt ratio/operating cash flow for several stocks), names the alternative (ashare_finance) and the condition that selects it (multi-stock, needs per-stock ok/error). Adds hard limits (Pro 10 / unlimited-tier 20, stocks × periods ≤ 40), worked examples of where quotas break, and the batching strategy with interval guidance.

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

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

With no annotations provided, the description carries the full burden and does: it discloses reverse-chronological ordering, that pagination only walks backwards with no date filter, that index step equals the prior limit, the 200-item cap, and a 1-minute cache that dedupes repeated calls. These are exactly the operational traits an agent needs.

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 and its ordering, then routes to the sibling, then gives paging/limit/cache warnings. Dense with bold and emoji markers, and slightly longer than strictly necessary, but every sentence carries distinct operational content.

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?

For a two-param feed tool with an output schema, this is complete: it covers scope, triggers, sibling routing, pagination mechanics, limits, and caching. Nothing needed to call it correctly is missing.

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 baseline is 3, but the description goes beyond the schema by giving the pagination formula (step = last limit, e.g. limit=20&index=20 for page two) and reiterating the 200 cap, which the schema states only as a default/upper bound.

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 resource (7×24 财经快讯 / 全市场电报), ordering (按时间倒序), typical sources, and enumerates the row fields. It explicitly distinguishes itself from ashare_news by scope (whole-market vs per-stock), so an agent can pick it without opening 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?

Gives concrete user-intent triggers ('今天有什么大消息/最新财经新闻/刚才发生了什么/宏观突发事件') and an explicit division of labor with ashare_news — market/macro/breaking here, single-stock news there. Both when-to-use and when-not-to-use are covered.

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

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

No annotations are provided, so the description must carry the behavioral burden. It does well by enumerating exactly what data is returned (capital-flow windows and rankings, dragon-tiger reasons/branches, block trades, margin), though it does not state that the tool is read-only or side-effect free.

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 core capability, then adds the usage trigger and two clearly marked exclusions. Every sentence earns its place, and the warning markers make the routing constraints scannable.

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 exists, there is no need to explain return values. The description covers what data is included and where the tool sits relative to alternatives, which is complete for a single-stock, single-parameter query tool.

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?

There is one parameter with 100% schema coverage, and the schema already documents the code format (e.g. sh600667). The description adds no syntax or format detail beyond the schema, so the baseline of 3 is appropriate.

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: stock-level trading data including main capital flow, dragon-tiger list details, block trades, and margin trading. It also explicitly distinguishes itself from siblings ashare_lhb (market-wide lists) and ashare_fund_batch (multiple stocks), so an agent can route without opening a schema.

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?

Gives an explicit when-to-use trigger ('用户问某只股票的主力资金/机构动向'), plus two explicit exclusions with named alternatives: market-wide lists go to ashare_lhb, multi-stock scans go to ashare_fund_batch. Nothing is left to inference.

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

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

With no annotations, the description carries the full burden and does so thoroughly: paid tier requirement (¥99+), per-call caps (200 pro / 1000 institutional), billing by actual returned count (failures not charged), market coverage (A-shares full; HK only main net inflow; US returns ok:false), and a critical warning that ok:true on the array does not guarantee per-stock data. That last point is exactly the kind of behavior an agent cannot infer from schema or annotations.

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-loaded with purpose and the sibling distinction, then organized into labeled warnings (usage, return structure, caps, billing, coverage, paywall). It is dense but every section earns its place; the caps and comma-separated format are repeated from the schema, which is minor redundancy for a paid tool.

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?

Despite an output schema existing, the description adds crucial interpretive guidance: data is an array of code/ok/data-or-error entries with requested/returned/failed counts. Combined with the paywall, cap, and market-coverage disclosures, an agent has everything needed to call it correctly and interpret partial failures.

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, but the description adds format semantics beyond the schema: comma-separated lists, bare 6-digit codes (000099) are accepted in addition to prefixed codes (sz000099), and it reiterates the tier-based count limits. This meaningfully reduces malformed-input risk.

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 states a specific verb and resource in the opening line: batch fund flow for multiple stocks, covering main funds + LHB + block trades + margin trading, one record per stock. It explicitly names the sibling it differs from (ashare_fund returns one stock; this returns many), so an agent can select it without opening either schema.

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?

It gives concrete user-question triggers ('these stocks' fund flow', 'scan my pool's main funds', 'which stocks in an industry have inflows') and a direct exclusion rule versus ashare_fund. When to use and when not to use are both explicit.

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

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

With no annotations, the description carries the full burden and delivers key traits: it is a read-only query (只读查询), requires the paid 专业版（¥99）tier, and all figures are denominated in 元. It does not say whether the flow data is realtime or delayed, and gives no rate or coverage limits, which is the remaining gap.

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-loaded with the resource and metrics, then use case, then sibling disambiguation, then unit and access warnings. Every sentence carries distinct information with no filler, despite the bold markup.

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?

An output schema exists, so return-value explanation is unnecessary; the single required parameter is fully documented. For a one-param read-only query, the description covers purpose, alternatives, units, and access tier — everything needed to call it correctly.

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% and the single `code` parameter already documents the sh600519 / hk00700 format inline. The description's mention of 港股 support implicitly reinforces the code format but adds no new syntax or constraint beyond the schema, so the 3 baseline applies.

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 names a specific resource and verb (个股资金流向, 主力与散户的买入/卖出/净额 + 均价、收盘价) and scopes it to A-shares and Hong Kong stocks. It explicitly names the sibling `ashare_fund` and states the distinction, so an agent can separate the two without opening either schema.

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?

Gives an explicit use trigger ('用户问"主力在进还是出/资金流多少"时用') and an explicit exclusion, noting that `ashare_fund` covers 龙虎榜+大宗+两融 for A-shares only, and that Hong Kong stocks must use this tool. When and when-not are both covered.

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

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

No annotations are provided, so the description carries the full burden and does most of it: it discloses read-only behavior, a paid-tier requirement (专业版 ¥99+), and the important partial-response behavior when date is omitted and same-day data is unpublished. It stops short of describing return shape or rate limits, but the output schema covers returns.

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?

Extremely dense and front-loaded: data fields first, then use case, then two warnings, then scope exclusion and entitlement. Every sentence earns its place, though the telegraphic warning-marker style is slightly harder to scan than plain prose.

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?

For a 2-parameter read tool with an output schema, nothing essential is missing: scope limits, sibling routing, entitlement gate, date degradation, and read-only status are all disclosed. An agent has everything needed to call it correctly or redirect.

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 baseline is 3, but the description adds real semantic value the schema lacks: it explains why date matters (without it, only identifier fields return when same-day data is unpublished) and gives concrete code formats (hk00700 / usAAPL). This turns a documented parameter into an understood one.

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 the specific resource (卖空股数/金额/比率, with field names ShortShares/ShortAmount/ShortRatio) and its true scope: HK/US equities only. It explicitly distinguishes itself from siblings by declaring 'A 股没有卖空数据' and routing 融券 to ashare_margin_trade, which is critical given the misleading ashare_ prefix.

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?

Gives an explicit trigger ('用户问"被做空多少/卖空比率"时用') plus two exclusions: not for A-shares, and use ashare_margin_trade for 融券 instead. It also prescribes passing date to avoid a degraded result, which is a concrete usage rule rather than general advice.

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

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

With no annotations, the description carries the full burden and does well: it declares read-only behavior, quarterly (not daily) data freshness, HK-only coverage, and a subscription-tier gate. It does not mention historical depth/earliest available quarter or pagination, which are the remaining behavioral unknowns.

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-loaded with the resource and fields, then usage trigger, then the disambiguation warning — good ordering with little waste. Slightly over-signposted with bold and ⚠️ markers, and the comma-separated codes note duplicates the schema.

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?

An output schema exists, so return values need not be described, and the definition covers scope, cadence, access tier, and the nearest alternative. Missing only minor details such as how far back quarterly data goes or what an empty result means for a non-southbound code.

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% (both date and codes are documented in the schema), so the baseline is 3. The description's note that 'codes 可逗号多只' merely repeats the schema's '港股代码，逗号分隔' example and adds no new meaning, and the date parameter is not discussed at all in the description.

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 resource (港股通南下资金持仓) with its cadence (季度) and the exact fields returned (持股数/持股比例/持股市值). It also delimits scope (仅港股), so an agent can separate it from ashare_fund_flow and the other fund-related siblings without opening either schema.

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?

Gives an explicit triggering question pattern ('南下资金持有多少/港股通占比'), an explicit exclusion (quarterly holdings, not daily flow), and names the alternative tool ashare_fund_flow for the daily case. It also flags the Pro-tier (¥99+) access prerequisite, which is guidance an agent needs before promising a result.

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

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

No annotations are provided, so the description carries the full behavioral burden. It discloses two operationally relevant traits: the data is a current snapshot with no history (当前快照（无历史）) and the tool is free with no API key required. It does not mention rate limits or result-size caps, leaving some gaps.

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?

Dense but front-loaded: the core purpose and the negative case come first, then the per-type field caveats, then the snapshot/licensing notes. The warning emoji pile-up makes it visually noisy, but every clause conveys a distinct constraint rather than restating the name.

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?

An output schema exists, so return values need not be described, and the description instead covers the things the schema cannot: the snapshot-only limitation, the no-key access, and the field heterogeneity across the five types. Complete enough to call correctly; only rate limits and a clearer `limit` bound reference are absent.

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 would be 3, but the description goes further by explaining what each `type` value actually returns (code/name/zdf/zxj for stock, multi-pv heat values for wx, news_id/news_title/source for news, symbol for sector, title/tag for etf) and warns that the five field structures are incompatible. That is genuine semantic value beyond the enum list in the 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?

States a specific verb+resource (关注度排名 / attention ranking) and immediately disambiguates it from the superficially similar 'who is rising' tools with ⛔ 不是'谁在涨'. It also enumerates the five mutually exclusive result classes (stock/wx/news/sector/etf), so an agent can tell this apart from ashare_limit_up or ashare_abnormal without opening a schema.

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?

Gives concrete user-intent triggers ('什么股票热门/大家在看什么/热度榜/热门板块/热文'), which is strong when-to-use guidance, plus the negative case of price movers. It stops short of naming a sibling tool as the alternative or stating exclusions beyond the 'not who is rising' line, so it is clear context without full routing.

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

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

No annotations are provided, so the description carries the full burden and does so well: it discloses that no weights are returned, that it is a static profile cached for 1 hour, that it requires the ¥29.9+ paid tier, that only one index per call is accepted (comma-separated returns empty), and that output key names differ by market. These are exactly the behavioral traits an agent would otherwise get wrong.

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 core scope and the alternative-tool routing are front-loaded, which is good, but the repeated ⚠️ blocks are verbose and partially redundant (ashare_etf(kind='持仓') is recommended twice; weights are disclaimed twice). The density of warnings is defensible for the failure modes it prevents, but it could be tightened without losing information.

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?

For a single-parameter lookup with an output schema, this covers everything an agent needs: what it returns, what it does not return, how to get the missing piece, which inputs are valid, and the per-market field-name divergence that would otherwise break downstream parsing. Nothing material is missing.

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% with examples already in the schema, so baseline is 3; the description adds real constraint semantics on top — accepted code formats (sh000xxx / sz399xxx / hk*), specific HK index codes, and the single-code-only rule. Minor gap: it does not restate the default or say what happens on an unknown code.

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 concrete verb+resource (full constituent list of an index) and enumerates the supported indices (沪深300/上证50/中证500/科创50/恒生...). It also explicitly distinguishes itself from the nearest sibling, ashare_etf, on both the weight dimension and the ETF-basket dimension.

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?

Names the triggering user questions ('沪深300有哪些成分股/ETF底层持有什么'), states when to use the alternative (weights → ashare_etf(kind='持仓'), top20Ratio), and states exclusions (individual stocks/ETFs → ashare_etf; ETF PCG lists are a different tool). Exclusions and alternatives are both explicit.

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

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

With no annotations, the description carries the burden well: it discloses read-only behavior, pagination via limit/offset, mixed A-share and Hong Kong indices, and the Professional plan requirement. It could still say more about date filtering or failure/limit behavior, but the core behavioral context is present.

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 entry is compact and front-loaded: it gives the resource, use case, next step, pagination warning, market-mixing caveat, read-only status, and plan requirement without wasted text.

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 output schema exists and all parameters are documented in the schema, the description supplies everything an agent needs: purpose, when to call it, next sibling, pagination, mixed markets, read-only status, and access tier.

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 100%, so all three parameters are already documented in the schema. The description repeats limit and offset pagination but adds no new meaning beyond the schema, and does not elaborate on the date parameter.

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 states a specific resource and scope: a full index list of 1223 entries with code/name fields. It distinguishes this from the sibling `ashare_index_constituent` by directing the agent there after obtaining an index code.

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?

It explicitly says to use this when the user asks what indices exist or what an index code is, and names the follow-up tool for constituents. The pagination and mixed-market warnings further clarify operational use.

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

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

No annotations are provided, so the description carries the full burden, and it does substantial work: it discloses the size of the dataset (183 themes), the return content per mode (关联个股/节点/位置/关联度/业务描述), the hard parameter-combination constraint with the failure consequence ('给错组合拿不到数据'), and the naming constraint (Chinese full names only). It still omits any note on data freshness, result size limits, or latency, which keeps it short of a 5.

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 mode enumeration is front-loaded and the two ⚠️ warnings cover distinct issues (parameter pairing vs. topic naming), so there is little true redundancy. Heavy markdown bolding and emoji add visual noise, and the mode list partly restates the schema's own mode description, which is the only real drag.

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?

An output schema exists, so return-value documentation is not required, yet the description still sketches what comes back per mode. Combined with the mode selection rules, the Chinese-name constraint, and the list-first fallback, an agent has everything needed to call this three-mode tool correctly on the first attempt.

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 genuinely exceeds it by stating the two-way exclusivity rule (graph requires topic, stock requires code) and the invalid-combination outcome, which the schema's per-parameter 必填 notes do not express. The supplied example values for topic and code also disambiguate format beyond the schema's '如 sh600667'.

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 names a specific resource (A股产业链, 183 themes) and enumerates the three distinct modes with concrete call examples (`mode=list`, `mode=graph` + `topic=超级电容`, `mode=stock` + `code=sh600667`) along with what each returns. This lets an agent distinguish it from sibling tools like ashare_sector or ashare_profile without opening a schema.

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?

It gives an explicit trigger list ('用户问产业链/上下游/某公司处于链上什么位置/这个主题有哪些公司'用这个), states the mutual-exclusion rule selecting between graph and stock modes, and even prescribes a fallback (call `mode=list` first when unsure of the Chinese full topic name). When-to-use, when-not-to-use, and alternatives are all present.

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

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

With no annotations provided, the description carries the burden and does disclose the two most important traits: read-only (只读查询) and update cadence tied to the issuance calendar (按发行日历更新). It says nothing about how far ahead the calendar extends, latency, or data-source caveats, and an output schema handles return values.

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?

Four dense fragments: what it is, when to invoke, safety/refresh behavior, and scope. No sentence is padding, and the market-coverage warning is deliberately placed last for emphasis.

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?

For a zero-required-parameter read tool with a full output schema, an agent has what it needs: purpose, invocation trigger, read-only safety, and market scope. The only gap is that the description does not mention the 'days' lookahead window, leaving the temporal horizon of results unstated outside the schema.

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?

There is a single parameter, 'days', and schema description coverage is 100%, so the schema already defines it, including its 15-day default. The description never mentions the lookahead window, which would have been a useful addition, so it adds nothing beyond the schema. Baseline 3 applies.

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 the specific resource (新股日历) and enumerates the lifecycle phases it covers (发行/申购/中签/上市), plus an explicit three-market scope note (A股/港股/美股). The 'ashare_' prefix could mislead an agent into thinking it is A-share-only, but the description proactively corrects that. It is clear without needing sibling differentiation, since no sibling covers IPOs.

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?

"用户问'新股/打新/IPO'用这个" gives explicit routing by user intent, which is the primary selection signal in this tool set. It does not state when NOT to use it or name an alternative, but no plausible alternative exists among the siblings.

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

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

With no annotations, the description carries the full burden and does so richly: it fixes the adjustment convention (前复权 for daily+, no adjustment for minute; no fq param, don't re-adjust), discloses refresh cadence (5-min free/anonymous vs real-time paid), tier requirements (minute lines need standard ¥29.9), unsupported markets (北交所/期货/外汇), the 5-symbol anonymous cap, and that it's read-only reflecting close. This is far beyond typical behavioral disclosure.

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?

Purpose is front-loaded and each warning is substantive, but the definition is dense with stacked ⚠️ blocks and repeated tier/adjustment caveats that risk overload. Nearly every sentence earns its place, though some redundancy across the batch/full reiteration could be tightened.

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?

Output schema exists so return values needn't be described, and the description covers everything else an agent needs: adjustment rules, tier and market limits, refresh behavior, multi-symbol caveats, and sibling routing. Nothing material to correct invocation is missing.

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 parameters are already documented, but the description adds non-obvious semantics the schema omits: minute lines require both start+end with a ~1-month window, the adjustment is fixed with no fq parameter, and turnover is the % field name shared with quote/snapshot. The code-accepts-commas-but-mixes-results caveat is also added. A small gap keeps it from 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 states a specific resource (K线) with the exact periods supported (day/week/month/season/year + minute lines) and explicitly distinguishes itself from ashare_quote (current price), ashare_minute (intraday tick), and the batch/full siblings. An agent can route to the correct tool from the first sentence alone.

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?

It gives explicit when-to-use triggers ('走势/最近表现/历史K线/趋势'), when-not-to-use conditions, and names each alternative plus the condition that selects it (current price → ashare_quote, intraday → ashare_minute, minute OHLC candles → this tool's period=m1/m5, multi-symbol → ashare_quote_batch, raw/hfq → kline_batch/kline_full). The distinction between 分时 and 分钟K线 is called out directly.

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

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

No annotations exist, so the description carries the full burden and does: partial-failure semantics (per-item ok flag, requested/returned/failed counts), hard caps (200 stocks professional / 1000 institutional; 60,000 total rows = stocks × count), a concrete performance benchmark, per-returned-stock billing, and a paywall (Professional ¥99+ only). These are exactly the traits an agent must know before calling.

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 core statement is front-loaded and the ⚠️ sections impose usable structure on a dense block (scope → differentiation → benchmark → params → returns → caps → pricing). It is longer than ideal and slightly redundant (per-item result shape is restated in the returns and caps sections), but nearly every line carries decision-relevant information.

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?

For a 6-param batch tool with an output schema, the description still covers the operational envelope: scale limits, cost model, tier gating, failure tolerance, and field naming. Nothing an agent needs in order to call this correctly or to prefer a sibling is missing.

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 baseline is 3; the description still adds meaning the schema doesn't — bare 6-digit codes are accepted, count is per-stock (30 each) and interacts with the 60,000-row cap (e.g. 200 × 300 hits the ceiling), and the turnover field name is called out as a return-column gotcha. The only gap is minor: fq/period behavior is left to the 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 title line states a specific verb, resource, and scope: fetch K-lines for multiple stocks over one shared time window, per-stock success flagged. It then explicitly distinguishes itself from all three sibling K-line tools (ashare_kline = one stock, ashare_kline_full = one stock × full history, ashare_market_kline = one day × whole market), so an agent can route without opening any schema.

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?

Concrete triggering scenarios are given ('这几只的走势', '把我这个池子的 K 线拉下来', '一个行业最近 60 天表现'), plus an explicit exclusion rule: don't loop ashare_kline yourself because 200 calls ≈ 2.3 min with rate-limit backoff versus 3.39 s here. The alternatives table makes the when-not unambiguous.

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

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

With no annotations, the description carries the full burden and does: it discloses that this is a paid tool with a Standard (¥29.9) tier floor, that Trial is excluded, that there is a separate daily quota (200/500/2000 by tier) checkable via ashare_usage, and that unsupported symbols produce an explicit error. It also flags the reproducibility trap that qfq series are recomputed after ex-rights events and that backtests should use hfq/nofq — behavior no annotation or schema field would convey.

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 purpose and scope are front-loaded in the first clause, and the numbered ①②③ comparison is an efficient structure for sibling differentiation. It is dense with bold and warning glyphs and repeats 'ashare_kline' and '10 年' several times, which costs some tightness, but essentially every sentence carries decision-relevant information.

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?

For a 4-parameter tool with an output schema already present, the description covers what it must add: selection criteria, quota/permission gate, instrument exclusions, adjustment-mode caveats, and the fixed 7-column shape. Nothing an agent needs in order to call this correctly or avoid a failed call is missing.

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 still adds meaning by explaining why fq choice matters (qfq is non-reproducible for backtests), which the schema only lists as enum values without rationale. The implicit start default (2016-08-08) and the code whitelist are reinforced rather than newly introduced, so it sits above baseline but not at the top.

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+scope: full-history K-line, 10 years of daily bars from 2016-08-08, with an optional adjustment mode. It goes further and enumerates three explicit axes of difference from the sibling ashare_kline (row cap, fq parameter, instrument coverage), so an agent can pick correctly without opening either schema.

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?

It names the exact user phrasings that select this tool ('十年走势/长期回测/全历史数据/复权价/后复权/原始价') and states when NOT to use it: ETF, convertible bonds, indices, sectors, HK/US stocks, futures and FX will error and should be routed to ashare_kline. That is explicit when/when-not/alternative guidance, not inference.

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

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

With no annotations, the description carries the full burden and delivers real behavioral facts: hotmoney currently returns no data, 龙虎榜 is published only after close (~18:00), and an empty date resolves to the most recent trading day. It does not mention permissions, caching, or rate limits, but for a public read-only data endpoint those are minor omissions.

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 dense but front-loads the type taxonomy first, then usage triggers, then caveats, so an agent can stop reading once it has what it needs. It is longer than strictly necessary (the type-by-type return enumeration and three separate ⚠️ blocks), but no sentence is pure filler.

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?

For a two-parameter, zero-required lookup tool with an output schema already present, the description covers everything an agent needs: what each mode returns, which mode to avoid, publication timing, default date behavior, and the sibling to use for per-stock data. Return-value explanation is correctly delegated to the output schema.

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 100% so the baseline is 3, and the description goes beyond it by explaining what each enum value of `type` actually returns rather than just listing the values as the schema does. The `date` parameter semantics are left to the schema, which already covers them, so it does not reach 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 states the specific resource (market-level 龙虎榜 leaderboards) and enumerates all six type values with what each returns (净买/买卖额, 机构买入, 席位买入额, 胜率, etc.), so an agent knows exactly what this tool produces. It also explicitly distinguishes itself from the sibling ashare_fund, which handles per-stock 上榜明细.

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?

Gives explicit trigger phrases ("今天机构买了什么/龙虎榜/高胜率席位/活跃席位用这个"), a when-not-to-use rule (per-stock details go to ashare_fund), and a routing override for the broken type (hotmoney 暂无数据，建议改用 all/activeseat/winbuy). This is about as complete as usage guidance gets.

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

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

No annotations are provided, so the description carries the burden and does most of it: it discloses that the data is post-close, that `date` may fall back with `is_fallback=true` and `requested_date` vs `date` divergence, and that `net_buy` is a signed net figure that can be negative. It also flags the access requirement ('机构版专属'). It stops short of stating read-only/rate-limit characteristics, but the disclosure level is well above adequate for a data-read tool.

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?

Purpose and the sibling split are front-loaded and bolded; the warning block is high-value. The long enumeration of row fields is largely redundant with the output schema that already exists, which costs some 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?

For a three-parameter, no-required-param read tool with an output schema, everything an agent needs is present: what the rows represent, sign conventions, row count expectation (~51/day), date fallback semantics, and routing guidance. No meaningful gap remains.

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 still adds meaning on `date` by explaining the fallback contract (`requested_date` / `date` / `is_fallback`) beyond the schema's 'blank = latest trading day'. It does not elaborate on `sort` enumerations or `limit` ceiling, which remain schema-only.

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 resource and scope: all market-wide stocks with institutional seat participation on the dragon-tiger list for a given trading day, returned in one call. It explicitly contrasts itself with the sibling `ashare_lhb_seats` (single-stock brokerage drill-down vs. market-wide screening), so an agent can pick the right tool without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.