get_qhkc_index

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the safety profile is covered. Against that lower bar the description adds real behavioral context: since there is no output schema, the sample DataFrame (date, price, volume, margin, profit, long_short_ratio) discloses the return shape, which an agent could not otherwise infer.

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 valid-name list are front-loaded before the longer sample block, and the sample data earns its place given there is no output schema. Minor redundancy in the Sphinx :type/:rtype directives, but no sentence is truly 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 2-parameter, optional-input read tool with annotations and no output schema, the description supplies the valid name domain and the return structure. It omits any indication of history span or result size (the sample spans years), which is the one remaining 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 must carry the load, and it does: it documents both params (:param url: 网址, :param name: 中文名称, :type str) and enumerates the valid semantic values for 'name'. The only weakness is the thin treatment of 'url' (just 'website'), which is why this 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?

The description states a specific verb and resource ('获得奇货可查的指数数据' - obtain qhkc index data) and enumerates the exact index names it can return ('奇货黑链', '奇货商品', etc.), which is concrete and useful. It does not explicitly distinguish itself from close siblings like get_qhkc_index_trend or get_qhkc_index_profit_loss, so it stops short of a 5.

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 never says when to use this tool versus the many sibling index/futures tools, nor does it name any alternative or exclusion. The list of valid index names implies the query scope but provides no selection guidance.

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