wps_word_replace

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

No annotations are provided, so the description must disclose behavioral traits. It successfully communicates a key behavior: when replace_all is false, only the first match is replaced. This adds critical context like a dependency on the replace_all parameter for mode control. However, it does not specify side effects (e.g., whether the replacement triggers track changes, whether selection is affected, or if formatting is preserved), leaving room for improvement. Despite that, the description provides meaningful insight beyond the schema.

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 extremely concise with two sentences and no superfluous text. The first sentence states the core purpose, and the second provides a critical behavioral note. Every word earns its place, making it highly efficient for an AI agent to parse quickly.

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 tool has 3 simple parameters, no output schema, and a straightforward function (find-and-replace in a WPS Word document), the description provides enough context: it explains the basic operation and the key parameter behavior. It does not explain what happens with no matches or whether formatting is preserved, but with low complexity, the coverage is sufficient. The explicit single-vs-all behavior compensates for missing output schema details.

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 100%, so the baseline is 3. The description adds value by clarifying that replace_all=false limits to first match, which is not fully explained in the schema's description ('是否全部替换，默认 true'). This nuance helps the agent understand the parameter's impact on tool behavior, justifying an above-baseline score. However, the find_text and replace_text parameters' format or case-sensitivity are not elaborated, preventing a top score.

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 title 'wps_word_replace' and description '查找替换' clearly indicate the tool performs find-and-replace in a WPS Word document. The description explicitly distinguishes between single and all replacements with 'replace_all=false 只替换第一处' (replace_all=false only replaces the first occurrence), which differentiates it from a simple 'replace all' behavior. This unambiguous verb+resource pair with behavioral nuance earns a top score.

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 implies usage for find-and-replace tasks, and the sibling tools list includes many other WPS Word operations (e.g., wps_word_insert_text, wps_word_read). However, no explicit guidance is provided on when to use this tool versus alternatives like wps_word_get_selection for manual replacement or wps_word_insert_text for simple text entry. The description lacks 'when-not-to-use' or contextual exclusions, earning a median score.

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