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: it discloses that code is de-facto mandatory despite the schema marking it optional (empty call returns only a message, no data), that batch returns rows without per-symbol status so the caller must reconcile missing codes itself, that data is T+1 disclosed so today is unavailable, and that NOT_DISCLOSED for ETFs means 'not in the margin list' rather than 'delayed' — preventing a retry loop.

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 then the when-to-use rule, and every ⚠️ warning carries non-obvious operational content. Slight deduction: the code/date warnings partially restate the schema's own parameter descriptions, so a sentence or two is redundant for an agent that reads 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?

For a 2-parameter read tool with an output schema, the description covers the remaining risk surface: mandatory-in-practice param, batch fan-out semantics, disclosure lag, and a false-negative case (ETF). Nothing an agent needs in order to call it correctly and interpret emptiness 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%, so baseline is 3; the description adds real semantics on top — that code is effectively required, the comma-batch syntax with a concrete example, and the T+1/已披露 caveat for date. It goes beyond the schema's terse field descriptions without fully specifying response field types, which the output schema already 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?

Opens with a specific verb+resource ('个股融资融券明细') and enumerates exactly the six fields returned (融资余额/融资买入/融资偿还/融券余额/融券卖出/融券偿还). It explicitly positions itself against the sibling ashare_fund ('ashare_fund 一次给四块概览；本工具只给两融明细、字段更全'), so an agent can discriminate 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 triggering user questions ('杠杆资金在加还是在撤/融资余额多少/两融数据'), names the alternative (ashare_fund) with the condition that selects this tool over it, and adds a hard exclusion (ETF 不在两融名单, don't retry sh510300). When-to-use, when-not-to-use, and alternative routing are all present.

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