binance_futures_positions

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

With no annotations, the description carries the full burden of behavioral disclosure. It warns about liquidation risk, mark price vs. last price differences, leverage risk, and funding fees, and explains that the output includes real-time risk data and today's PnL. It also provides a detailed output example that reveals the exact structure and fields returned. Missing details like error handling are minor for a read-only query tool.

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 well-structured with clear headers (功能说明, 重要提醒, 适用场景, 输出示例) and front-loads the purpose. However, it is quite verbose, especially the sprawling output example with emojis and repeated warnings. While informative, it could be more concise without losing value.

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?

Despite lacking an output schema, the description provides a comprehensive output example that acts as an informal schema, covering all key position fields, risk metrics, and overall analysis. It also includes applicable scenarios and risk warnings, making the tool's behavior fully understandable. The one optional parameter is thoroughly covered by the schema, so nothing 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?

The input schema already thoroughly documents the 'symbol' parameter with examples and states that omitting it returns all positions. The description only restates '支持查询特定合约或所有持仓' without adding new semantic details. Since schema coverage is 100%, this meets the baseline but doesn't surpass it.

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 immediately states '合约持仓查询' (futures position query) and lists specific data returned (持仓数量, 入场价格, 标记价格, 未实现盈亏, 强平价格, 杠杆倍数), making the tool's purpose unmistakable. It clearly distinguishes itself from sibling tools like order placement or account balance queries.

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 provides a dedicated '适用场景' section listing specific use cases (monitoring positions, risk control, strategy verification, portfolio analysis), giving clear context for when to use the tool. It doesn't explicitly mention exclusions or alternatives, but the scenarios are sufficiently clear for an agent to choose this over other Binance tools.

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