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

With annotations already declaring readOnlyHint, idempotentHint, and destructiveHint=false, the description adds meaningful context beyond them: 'sorted server-side' (the agent need not sort locally), the exact row fields returned (code, name, price, change %, volume, turnover, turnover rate, quote time), and 'Source: Sina Market_Center.getHQNodeData (keyless)' which preempts auth questions. No rate-limit or staleness info, but the keyless source note and row contract add genuine value.

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 purpose and scope, followed by routing examples, return format, and source. Each section earns its place, though the example query list is slightly redundant — 'top 30 A-shares by turnover today' and 'which A-shares traded the most today' express nearly identical intent. Minor over-specification, but no wasted or filler sentences.

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 tool with 4 optional, fully-documented parameters and no output schema, the description covers the essentials: scope, server-side sorting, row-level return fields, natural-language triggers, and the data source. The row field enumeration compensates for the missing output schema, and defaults/enums live in the schema. Only minor details like quote-time freshness or pagination behavior 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 description coverage is 100%, with every parameter (sort, board, limit, order) already documented including defaults and enum meanings. The description reinforces the sort dimensions (amount/changepercent/volume) through natural-language examples, but adds no meaning the schema doesn't already convey. Baseline 3 is appropriate since the schema carries the explanatory load.

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 uses a specific verb+resource construction: 'Market-wide ranking of Chinese A-share stocks by turnover' and immediately narrows scope with 'the whole board (not specific codes)'. It offers Chinese and English phrasings of the query intent (成交额前30名, 'top 30 A-shares by turnover today'), which clearly differentiates it from siblings like ashares_quote or ashares_daily_history. The distinction from specific-code tools is explicit, making this unambiguous.

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 provides explicit when-to-use signals through example queries ('Answers "A股成交额前30名"... "which A-shares traded the most today"') and an exclusion clause ('not specific codes'). However, it never names an alternative sibling tool (e.g., 'use ashares_quote for single-stock lookups'), so the when-not guidance stops short of routing the agent to a concrete fallback.

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