stock_hsgt_stock_statistics_em

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false, covering the safety profile. The description adds that it returns a pandas DataFrame and includes the source URL, which is useful context. It doesn't disclose any additional behavioral traits like pagination, rate limits, or data update frequency, but it doesn't contradict the 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?

The description is formatted as a structured docstring: endpoint title, URL, market notes, parameter specs, and return type. It is relatively compact and front-loaded with the main purpose. The market notes are somewhat redundant and could be trimmed, but overall each section 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?

For a read-only retrieval tool with no output schema, the description covers the return type and parameter choices adequately. However, it doesn't list the actual fields in the returned DataFrame, nor does it explain the relationship between the symbol parameter and the market codes mentioned. With many similar sibling tools, the lack of comparative guidance is a notable 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 description coverage is 0%, so the description carries the full burden. It provides types and examples for all three parameters: symbol with valid choices, start_date with format '20200713', and end_date similarly. The market=001/003 lines reference a parameter not in the schema, which could mislead, but the core parameter semantics are clearly explained.

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 clearly states the tool's function: retrieving daily individual stock statistics for Shanghai-Shenzhen-Hong Kong Stock Connect holdings. The source URL and market code hints (001/003) provide specific scope. However, it does not explicitly differentiate from sibling tools like stock_hsgt_hold_stock_em or stock_hsgt_individual_em, relying on the name to distinguish.

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 concrete usage details: symbol choices ('北向持股'/'南向持股'), date format examples, and return type. It implies the tool is for querying a specific data range, but it doesn't say when to use this tool versus alternatives among the many Stock Connect siblings. The market codes are mentioned but not mapped to any schema parameter, which creates ambiguity.

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