Preview code changes in multiple formats like unified or side-by-side diff views, with options to filter files, adjust context lines, and ignore whitespace changes.
Enhanced change preview with multiple format options
| Name | Required | Description | Default |
|---|---|---|---|
| format | No | Preview format | |
| contextLines | No | Number of context lines | |
| ignoreWhitespace | No | Ignore whitespace changes | |
| filePattern | No | File pattern filter | |
| cwd | No | Working directory |
Changes observed during successful MCP inspections.
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description must disclose behavior. It only mentions format options but does not state that the tool is read-only, what operations are performed, or any side effects (e.g., file system impact). This is insufficient for a tool with 5 parameters.
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 short (a phrase), which is concise but lacks substantive content. It is front-loaded but does not provide enough information to justify its brevity.
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 5 parameters, no output schema, no annotations, and multiple sibling diff/preview tools (e.g., preview_changes, enhanced_git_diff), the description is incomplete. It fails to explain the output format, how it differs from siblings, or when to choose it.
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 descriptions cover all 5 parameters (100% coverage), so baseline is 3. The description adds 'multiple format options' which hints at the format enum but does not elaborate on parameter meanings beyond what the schema provides.
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 'Enhanced change preview with multiple format options' indicates the tool previews changes and offers format options, but it's vague about what exactly is 'enhanced' compared to sibling tools like preview_changes. It does not specify the resource (e.g., working directory diffs) or clearly distinguish from similar tools.
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 guidance is provided on when to use this tool over alternatives like preview_changes or enhanced_git_diff. There are no usage conditions, prerequisites, or cues for selection, leaving the agent to guess.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.