diff_report_against_saved

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, covering the safety profile. The description adds value beyond this by disclosing the overwrite semantics of a second save (currently a write operation yet non-destructive to this call) and the diff.write_mode return range (CREATE/OVERWRITE/NO_CHANGE). With annotations covering safety, this is solid supplementary context with no contradiction.

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 efficiently front-loaded with the purpose, followed by the overwrite warning and a compact Args/Returns block. The structure is clean and scannable, though the Args section is somewhat redundant with the schema. Minor waste, but nothing excessive.

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 a full input schema, an output schema describing DiffResponse, and annotations covering the safety profile, the description covers the purpose, the when-to-use scenario, and the key behavioral caveat (overwrite risk). Nothing critical an agent needs to call it correctly is missing; it could name alternatives, but overall it is complete.

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 coverage is 100% — all three parameters (report_id, report_markdown, diff_preview_lines) are described in the schema, including the default of 40 for diff_preview_lines. The description's Args section largely restates this, adding negligible meaning beyond the schema. Baseline 3 is appropriate given the schema carries the load.

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 states a specific verb+resource: it shows the diff between an already-saved report and a draft ('이미 저장된 보고서와 초안의 차이를 보여 줍니다'). This clearly distinguishes it from save/validate siblings (save_approved_report, validate_report_draft) by its comparative, non-writing role. It stops short of naming a sibling explicitly, but the purpose is unambiguous.

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 gives clear when-to-use context: a second save with the same report_id overwrites the existing file, so this tool exists to check what will be lost before that happens ('무엇이 사라지는지 먼저 확인해 사고를 막는 용도'). This strongly implies use before overwriting, though it does not explicitly name alternatives or exclusion conditions.

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