preview_diagnostic_fix

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

Annotations already declare the safe read-only profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false, idempotentHint=false). The description adds genuinely new context: it is in-memory, never touches the filesystem, validates paths against canonical project-root containment, and yields a transactionId. That is meaningful behavioral detail beyond the annotations.

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?

Two dense sentences, front-loaded with the core behavior (in-memory preview, no filesystem writes) before the secondary detail (path validation, transactionId). No 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?

An output schema exists, so return values need not be spelled out, and the annotations plus description jointly cover the safety profile and the key behavior. The two real gaps are the undocumented patches parameter and the missing routing guidance for when to preview versus apply.

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% and the single 'patches' array parameter is completely undocumented — neither the schema nor the description explains the required file/originalContent/patchedContent triple or the optional description field. The brief mention of 'paths' only loosely hints at the patch structure, leaving the agent to infer the input contract.

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?

States a specific verb and resource: 'Creates an in-memory preview of proposed diagnostic fixes.' The phrase 'without touching the filesystem' implicitly separates it from apply_diagnostic_fix, but no sibling is named explicitly, so differentiation is inferential rather than stated.

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?

Usage is implied — this is clearly the dry-run step before apply_diagnostic_fix — but the description never says when to use it versus applying directly, nor does it name the alternative or any prerequisites. An agent must infer the preview-then-apply workflow from the name alone.

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