bond_zh_hs_spot

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds the critical behavioral warning '大量抓取容易封IP' (heavy scraping can get IP banned), which is not captured by annotations. It also clarifies the real-time nature ('当前时刻') and pagination behavior, providing extra context about the tool's execution.

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 a clear title, source URL, parameter docs, and return type. It is not overly verbose, and every line serves a purpose, including the IP ban warning. The docstring formatting adds some clutter but remains readable and informative.

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?

The tool is relatively simple, and the description covers the core purpose, source, return type, and pagination. However, there is no output schema, so the description should detail the DataFrame columns or data structure, which it omits. It also lacks guidance on alternative tools or edge cases, making it only minimally complete for an agent to use it correctly in all scenarios.

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 only provides parameter names, types, and defaults, with zero description coverage. The description compensates by explicitly defining 'start_page' as 分页起始页 (pagination start page) and 'end_page' as 分页结束页 (pagination end page), adding semantic meaning beyond the schema. However, it does not mention page size or how to determine the page range, leaving some ambiguity.

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 this tool retrieves real-time market data for all Shanghai/Shenzhen bonds from Sina Finance, with a specific source URL and a return type of DataFrame. The phrase '所有沪深债券在当前时刻的实时行情数据' precisely distinguishes it from historical (bond_zh_hs_daily) and convertible bond (bond_zh_hs_cov_spot) siblings.

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 no explicit guidance on when to use this tool versus alternatives among the many bond-related siblings. It only includes a caution about heavy scraping risking IP bans, which is a usage warning but not a selection criterion. No mention of alternatives or exclusions.

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