wps_word_open

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It excels by detailing a critical behavioral trait: that opening an already-open file causes a native modal that blocks all WPS commands until dismissed, which no annotation could capture. It also transparently explains sandbox restrictions and the error handling (explicit error, not silent failure), providing comprehensive non-obvious behavior.

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 moderately concise (about 3 sentences in Chinese) and front-loads the core purpose. It earns its sentences: each adds distinct value (purpose, blocking warning, sandbox workaround). It could be marginally tighter by combining the sandbox and workaround into one sentence, but the current structure is well-organized and readable for its length.

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 simple tool (1 required param, no output schema, no enums, no nested objects), the description covers all necessary context: the action, critical caveats (blocking dialog, sandbox restrictions), and alternative paths to unblock users. For a file-opening tool, it is remarkably complete in warning about environmental constraints that could cause failures, leaving no obvious gaps for an agent to make incorrect assumptions.

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?

The input schema has 100% coverage with one parameter 'path' described as '文件绝对路径' (absolute file path). The description adds value beyond the schema by explaining the sandbox restrictions that affect which paths are usable, giving crucial context for the parameter's semantics that the schema alone cannot provide. While the parameter is straightforward, the description's path-related usage guidance elevates the score above baseline 3.

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 uses the verb '打开' (open) and specifies the resource as '本地或云同步的 WPS 文字文档' (local or cloud-synced WPS Word documents). It distinguishes itself from siblings like wps_word_new, wps_word_save, and other tools by focusing exclusively on the open action for WPS Word files.

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 explicit guidance on when to use this tool and critical prerequisites: it warns against opening a file already open in WPS due to a blocking native dialog, advises pre-checking with wps_status or known context, and explains the sandbox access restrictions with actionable workarounds (use files under ~/Downloads or pre-open via shell/finder). This gives clear when-to-use and when-not-to-use instructions.

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