futures_dce_position_rank

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true, covering the safety profile and matching the read-only nature of a rank query — no contradiction. The description adds the source URL and a return type, but says nothing about pagination, date-range limits, or freshness beyond a single example date. Modest added value over structured fields.

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?

Short and front-loaded with the source title, but the raw URL and the Sphinx :type:/:rtype: boilerplate add noise without adding meaning for an agent. Content is minimal rather than tightly optimized.

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, all-optional tool with annotations present, the description covers both parameters and documents the return (:return pandas.DataFrame of position rank data for the given date), substituting for the absent output schema. It omits what defines a valid date range and what values vars_list accepts, leaving real gaps for correct invocation.

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 documentation burden: it defines date as the trading day with the concrete format example "20200511" and labels vars_list as a variety list. However, vars_list gets no format, allowed-value, or default information despite the schema carrying a large default list, so the compensation is only partial.

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?

States a specific verb+resource: DCE daily position rank for a specific contract ("大连商品交易所-每日持仓排名-具体合约"), with a source URL. The "具体合约" qualifier hints at scope but does not explicitly distinguish it from the sibling futures_dce_position_rank_other or the many other rank tools. Purpose is clear; sibling differentiation is not spelled out.

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?

No when-to-use, when-not-to-use, or alternative guidance is given. The docstring never mentions futures_dce_position_rank_other, get_dce_rank_table, or get_rank_table_czce, so the agent must infer routing from the name alone. Only the implicit "具体合约" scope hint exists.

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