cnki_search

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

Even though annotations are None, the description discloses critical behavioral aspects: it uses a real browser, may trigger verification pages requiring manual intervention, can hit rate limits (returning '暂无数据' or timing out), and describes retry strategies. This is highly transparent about the tool's runtime behavior and failure modes.

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: a concise opening sentence states the purpose, followed by a numbered list of usage notes. The notes are lengthy but essential due to the browser-based nature and rate-limiting caveats. Information is front-loaded and organized logically, with no redundant fluff.

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?

Given the complexity (real browser, potential verification, rate limits, timeout retries), the description covers all necessary operational context. It explains how to construct queries, what parameters to use, how to handle errors, and when to involve the user (verification). There is no output schema, so return values are not required, but all other relevant aspects are addressed.

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?

All 9 parameters are described in the schema, with detailed explanations for 'query' including examples and supported modifier fields (e.g., 作者:, 关键词:). The descriptions clarify each filter (author, organization, fund, year) and the 'field' enum values. Schema coverage is 100%, and the description adds extra context for the query parameter, leaving no 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 it searches CNKI academic literature with natural language support and lists applicable use cases (topic, keyword, author, institution, year). However, it does not explicitly distinguish from sibling search tools like cnki_professional_search or cnki_search_with_abstracts, so the purpose is clear but not fully differentiated.

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 includes a detailed '使用须知' block with explicit guidance: avoid parallel calls, use year_from/year_to instead of manual YE BETWEEN expressions, handle rate limiting with retry, deal with verification pages, and cap max_results. This provides strong operational instructions and effectively tells when and how to use the tool.

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