stock_notice_report

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true and destructiveHint=false, so the safety/network profile is covered. The description adds the upstream URL and that the return is a pandas.DataFrame, which is useful context for a scraping-backed tool, but it says nothing about pagination, rate limits, or whether the date default is meaningful.

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 content is front-loaded with the source title and URL, but the Sphinx :param/:type/:return/:rtype scaffolding adds boilerplate lines that repeat type information already implied by the schema. It is neither bloated nor tight.

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?

No output schema exists, and the description does disclose the return type (pandas.DataFrame) and the data source, which is the main thing needed. But for a source-scraping, date-and-category-filtered query tool it omits date format expectations, result scope, and any alternative-tool routing, leaving real gaps.

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 parameter meaning. It does enumerate the eight accepted symbol values ({"全部", "重大事项", "财务报告", ...}), which is genuinely additive since the schema declares no enum. The date parameter is only glossed as 制定日期 ("formulation date"), which is ambiguous about format and whether it is the announcement or report date, so the coverage is 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?

The description identifies the resource as Eastmoney's A-share (沪深京) announcement listing and links the source page, so an agent can tell it fetches company notices. However, it never states a verb (fetch/list/query), reads as a scraped page title, and does not distinguish itself from siblings like stock_individual_notice_report. Purpose is inferable but not crisply stated.

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?

There is no when-to-use guidance, no mention of the sibling stock_individual_notice_report, and no note that results are a dated snapshot filtered by announcement category. The agent is left to infer usage entirely from the name and params.

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