agentladle/financial-reports

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

The annotations declare destructiveHint=true and readOnlyHint=false, which directly contradict the description's portrayal of a read-only full-text search that returns content snippets. Per the rubric, any contradiction with annotations forces a score of 1. This is a serious inconsistency that must be fixed.

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 long but very well organized with critical_rules, parameters_guide, examples, and usage tips. Every major block contributes operational value, though a few rules (e.g., synonym expansion) could be tightened. Overall, the structure makes the length acceptable for a tool with 7 parameters and complex constraints.

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 description thoroughly covers data scope, matching behavior, parameter combinations, and sibling-tool handoff, which is strong for a complex search tool. However, since there is no output schema, it only vaguely states that the tool returns 'content snippets' and does not enumerate result fields, error conditions, or rate limitations. This leaves minor gaps in completeness.

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?

Although schema coverage is 100%, the description adds substantial meaning beyond the schema: it explains keyword count and financial-term conversion, stockCode's global vs company scope, reportType format ('2023a4'), matchMode semantics (ANY/ALL/MOST) with use-case rationale, and pageMin/pageMax as report-section filters. The examples map natural-language questions to concrete parameter values, greatly improving correct invocation.

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 opens with a specific verb+resource+goal: '基于关键词的财务报告全文检索工具，用于发现报告中与特定主题相关的内容片段' (a full-text keyword search tool for financial reports to locate topical content snippets). This clearly distinguishes it from sibling tools that handle pages, chapters, or company info, and the closing reference to GetFinancialReportPagesTool and GetReportChaptersTool further clarifies its boundaries.

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 extensive when-to-use/when-not-to-use guidance: critical_rules mandate keyword extraction instead of natural-language input, require reportType for full-market searches, exclude US/HK and quarterly reports, and examples demonstrate specific-company vs cross-company cases. It also explicitly recommends ANY mode for initial searches and suggests sibling tools for full chapters or pages.

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

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

The description presents a read-only operation ('获取...完整内容'), while the annotations set destructiveHint=true and readOnlyHint=false. This is a direct contradiction; the description adds no disclosure of any destructive side effects, which would be expected given the annotation. Despite detailed returning format and limits, the fundamental safety profile is inconsistent.

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 long but well-organized with clear section headers (critical_rules, function_description, parameters_guide, return_format, examples). The front-loaded purpose statement and structured guidance make it navigable. It could be trimmed, but each section contributes useful information, so it earns a 4 rather than a 3.

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 description is thorough for a retrieval tool: it covers data scope, page limits, parameter semantics, return format, and a full output example. It lacks explicit error handling or edge-case behavior (e.g., page out of range), but with no output schema required, the provided information is sufficiently complete for most use cases.

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 coverage is 100%, but the description goes far beyond schema labels. It explains the structure of reportType (e.g., '2025a4' = year + 'a4'), gives concrete stockCode examples with company names, clarifies startPage is 1-based, and documents pageCount's max and default (5). The examples further illustrate parameter combinations, making invocation unambiguous.

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 opens with a clear verb-object pairing: '获取财务报告中各页的完整内容' (fetch complete content of report pages), and immediately specifies the filtering criteria (stock code and report type). This distinguishes it from sibling tools like financialKeywordSearch or getReportChapters, which target different retrieval needs.

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 gives clear context for use: page-range retrieval of annual report content for A-share listings. It explicitly states what is not supported ('暂不支持美股、港股及季报、半年报'), providing a when-not boundary. However, it does not name alternative sibling tools or explicitly compare to them, so it stops short of a full 5.

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

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

The annotations declare destructiveHint=true, but the description clearly describes a read-only query operation that returns page numbers. This is a direct contradiction. The description does not disclose any potential side effects, rate limits, or other behavioral traits beyond the contradiction.

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 sections (critical rules, function description, parameters guide, examples) and is front-loaded with the main purpose. It is somewhat verbose but each section adds value. There is minor repetition of the statement types between function_description and category description.

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 description covers data scope, supported report types, parameters, and provides two examples illustrating both full and single-statement queries. No output schema exists, but examples show the output format. However, it does not address error cases or invalid inputs, and the destructiveHint contradiction creates uncertainty.

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 coverage is 100%, but the description's parameters_guide adds significant value: explicitly marks stockCode and reportType as required, explains reportType format (4-digit year + type code), and clarifies that category is optional with supported values. The examples demonstrate realistic inputs and outputs, improving parameter understanding.

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 the tool queries the starting page numbers of four consolidated financial statements in annual reports. The verb '查询' and resource '四张合并财务报表的起始页码' are specific and distinguish it from sibling tools like getFinancialReportPages or financialKeywordSearch.

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 critical rules with explicit data scope limitations (China A-share annual reports only, excludes US/HK stocks and quarterly/semi-annual reports). It also explains supported report types and the optional category parameter. However, it does not explicitly name alternative sibling tools for other use cases.

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

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

描述声称执行读取操作（获取章节目录），但注解声明 readOnlyHint=false 且 destructiveHint=true，直接矛盾。描述没有披露任何可能的破坏性行为或解释为何注解如此设置，导致行为透明度极低。

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?

描述组织良好，分为简介、关键规则、参数指南和示例，每一部分都有明确价值，无冗余信息。示例具体且有助于理解，整体长度适中，信息密度高。

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?

鉴于工具只有两个参数且无输出schema，描述已覆盖数据范围限制、参数格式和示例输出，内容足够完整。没有明显的关键信息缺失，能支持用户正确调用该工具。

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覆盖率达100%，但描述额外提供了参数格式细节（如reportType由4位年份和类型代码组成）和具体示例（stockCode="000026", reportType="2025a4"），超越了schema中简单的参数说明，帮助理解实际使用方式。

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?

描述明确说明工具的功能是获取财务报告的完整章节目录，动词和资源明确。它详细说明了数据范围（中国A股年报），与兄弟工具如 getFinancialReportPages 区分开来。

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?

描述中的 critical_rules 部分明确指出了数据范围的限制（仅A股年报，不支持美股、港股、季报和半年报），这提供了何时不应使用该工具的清晰指导。同时提供了示例，展示了如何正确使用参数。

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

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

注释声明 destructiveHint=true，而描述内容为“查询”操作，隐含只读，与注释直接矛盾；描述未解释为何标注为破坏性，也未提供任何警告或副作用说明，违反一致性要求。

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?

描述用结构化的 critical_rules、function_description、parameters_guide、return_format、examples 组织，信息密度高且示例直观，但部分内容与 schema 重复，稍显冗余。

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?

描述覆盖了功能、参数、返回格式、示例和数据范围限制，对于简单查询工具而言较完整；但未涉及错误处理或分页等边界，且未回应注释中的破坏性冲突，故扣一分。

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 已完整描述两个参数（query、size），描述额外补充了匹配规则（代码精确、名称模糊）和示例，增强了语义，但未显著超越 schema 基线，故给4分。

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?

描述明确指出按公司名称或股票代码查询上市公司基本信息（简称、代码、上市日期），动词“查询”+资源“上市公司基本信息”具体明确，并与兄弟工具（如获取财报页面）有效区分。

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?

描述包含关键规则说明数据范围仅限A股，隐含了“非美股港股不使用”的限制，并说明按名称模糊匹配、按代码精确匹配的用法，但没有明确提及兄弟工具替代场景，因此略有不足。

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