Ann Content

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

With no annotations, the description carries the full burden, and it does disclose meaningful behavior: automatic pagination, HTML tag stripping, return of plain text plus PDF attachment links, an output contract that the body is not rewritten, and the data source with a verified-as-of date. It stops short of covering rate limits, auth requirements, or failure modes, so it is strong but not exhaustive.

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?

Front-loaded with the core action and input, followed by behavior, output contract, and data source in a scannable structure. The skill cross-reference and the data-source verification date are marginally useful but slightly add noise.

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?

An output schema exists, so return values need not be explained, yet the description usefully pre-declares the plain-text + PDF-link return and the no-rewrite contract. Combined with the input-source guidance, an agent has what it needs to invoke the tool correctly; only edge-case behavior is unaddressed.

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% for the single art_code parameter, so the description must compensate, and it does by explaining where the value originates (ann_list/ann tools) and that it is required. It adds no format/example detail beyond that, so it is good but not complete.

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?

Specific verb+resource: '公告正文抓取' (fetch announcement body text), distinguishing it from the sibling ann_list which supplies the input. The description also names the associated skill, so an agent can tell what operation this performs without opening the schema.

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?

It states the input dependency clearly ('输入 art_code（从 ann_list/ann 相关 tool 获取）'), which tells the agent to call ann_list first. However, it gives no explicit when-to-use vs when-not guidance against siblings like earnings_ann or ir_records, leaving the choice implied.

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