Compare two worksheets by key column to show rows only in each sheet and value changes. Returns summary stats and up to max_diff details for version comparison, change detection, reconciliation.
按关键列比对两个工作表的差异 —— 只回传差异摘要，不回传整表。
用途：版本对比、变更检测、对账。
返回：仅在表1 / 仅在表2 / 值有差异 三类统计， 以及最多 max_diff 条差异明细（超出会明确说明截断数量，以统计值为准）。
| Name | Required | Description | Default |
|---|---|---|---|
| sheet1 | Yes | ||
| sheet2 | Yes | ||
| max_diff | No | ||
| file_path | Yes | ||
| key_column | Yes | ||
| compare_columns | No |
Changes observed during successful MCP inspections.
v0.3.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does well by disclosing the output shape: three categories of statistics and up to max_diff detail rows, with explicit truncation behavior. It also signals that the tool is read-only in spirit by emphasizing that it returns only a summary rather than the full sheet.
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 compact and front-loaded with the core behavior, then gives use cases, then return details. Every sentence adds value and there is no redundant 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?
For a 6-parameter tool with no output schema and no annotations, the description is fairly complete about output and truncation behavior. It is missing semantics for compare_columns, which could matter for agents deciding how to restrict the comparison, and it does not describe edge cases like missing keys.
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 0%, so the description must compensate. It adds meaningful semantics for max_diff (truncation limit) and key_column (comparison key), and '两个工作表' implies sheet1/sheet2. However, compare_columns is not explained, and file_path is left entirely to its name.
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 compares two worksheets by key column and returns only a difference summary, not the full table. The stated use cases (version comparison, change detection, reconciliation) further clarify its intended purpose. It does not explicitly name a sibling alternative, but the behavior is specific enough to distinguish it from tools like join_sheets.
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 '用途' section explicitly lists when to use the tool: version comparison, change detection, and reconciliation. This gives the agent clear context for choosing it, though it does not mention when not to use it or name alternatives such as join_sheets.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.