cnki_download_paper

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

The description discloses an important behavioral detail beyond the annotations: files are always saved within the workspace project directory. It also indicates the use of current legal permissions, which implies session-dependent behavior. The annotations only state readOnlyHint=false and openWorldHint=true, so this additional context adds meaningful value.

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 a single, compact sentence that conveys the core function and a key behavioral guarantee. Every word is useful and there is no redundancy or filler.

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?

While the description conveys the basic purpose and file location, it does not mention authentication prerequisites (e.g., needing cnki_login or a valid session), error scenarios, or behavior when the paper is not cached. The presence of an output schema reduces the need to explain return values, but given the sibling tools for session management, more contextual guidance would be helpful.

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 60%, with title, subdirectory, and preferred_format described. The tool description does not add extra explanation for the undocumented profile and overwrite parameters. However, it reinforces the workspace-location constraint related to subdirectory, providing some overlap. Overall, the description adds marginal value beyond the 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?

The description clearly states the tool's purpose: download a paper using current valid CNKI permissions. It names the specific action (download) and the resource (paper), and the mention of saving files in the workspace distinguishes it from read-only tools like cnki_read_online_html.

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?

No explicit guidance is provided on when to use this tool versus alternatives. It does not mention prerequisites like needing an active CNKI session, nor does it contrast with sibling tools such as cnki_search or cnki_get_metadata. The phrase 'using current legal CNKI permissions' implies a session requirement but does not state when this tool should be selected.

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