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

Annotation Contradiction: the description presents the tool as a pure read/search operation ('Full-text keyword search', 'read that page'), while annotations declare destructiveHint=true. The description never clarifies whether the search can modify or delete data, so the agent receives conflicting safety signals.

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 longer than average, but it is densely structured with an explicit strategy and critical rules. Every section prevents a specific invocation error, and the core purpose is front-loaded before the tactical guidance.

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 all invocation-critical behavior: when to use it, prerequisites, language rules, code formats, and required parameters. The main gap is the lack of an output schema and only indirect mention of the return shape ('returned page number'), leaving fragment contents and matching results somewhat underspecified.

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?

Even though the schema covers all parameters, the description adds decisive constraints: 1-5 keywords only, no full sentences, language alignment (Simplified Chinese for CN-A, English for HK), reportType formats like '2025a4'/'2026h2', stock code digit rules, and reportType required for cross-company searches. This materially improves 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 action and resource — 'Full-text keyword search across financial reports' — and then sharpens the boundary by referencing sibling tools. It clearly distinguishes this tool from getFinancialReportPages and searchCompanyInfo, so an agent can tell it apart 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?

The strategy section is an explicit decision tree: use this tool for specific facts or locating sections, skip it for TOC or known page numbers, and call searchCompanyInfo first when the company is unknown. It names the alternatives and the exact conditions that route to them.

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