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

With no annotations, the description carries the full burden and discloses key behavior: read-only query, professional-tier subscription requirement, 20-item list cap with 422 on limit>20, offset pagination, historical total vs actual count quirks, and no time filtering. These are substantial operational details beyond what the schema alone provides.

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 two operating modes and then lists practical constraints. Most sentences earn their place, though the heavy use of bold warnings and emoji makes it slightly cluttered compared with a cleaner prose structure.

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 tool's complexity, an output schema exists so return values need not be explained. The description still covers modes, scope, usage triggers, list pagination limits, count quirks, complementarity, and subscription prerequisites, leaving no major operational gap.

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 adds meaningful semantics: id triggers detail mode while its absence triggers list mode, and limit>20 causes a 422. It reinforces pagination via offset and code usage across A-share/HK, though most per-parameter details remain 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 description gives a specific resource (卖方研报) and clearly distinguishes two modes: omitting id returns a list, while passing id returns full report Markdown. It also scopes coverage to A-shares and HK stocks, so the agent can identify the tool 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?

It explicitly says when to use the tool ('用户问有没有研报/机构怎么说/这篇讲了什么') and names the complementary alternative ashare_dehydrated for dehydrated summaries. It also states the important negative constraint that there is no time-range parameter.

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