diff_minutes_against_saved

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false; the description adds value beyond them by revealing the overwrite mechanism (second save with the same note_id replaces the file) and exposing the return mode enum (CREATE / OVERWRITE / NO_CHANGE). This is consistent with the annotations - 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?

Purpose is front-loaded, followed by the overwrite-safety context, then a compact Args/Returns block. It is efficient, though the Args section partially duplicates the schema's parameters, a minor redundancy given the 100% coverage.

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 read-only diff tool with a full output schema (DiffResponse) and complete param schema, the description is nearly sufficient: it covers purpose, usage context, params, and the return mode. A minor gap is that edge cases (e.g., behavior when a note does not exist, implying CREATE) aren't spelled out, but the output schema largely covers the response shape.

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 Args section largely restates the schema (note_id, 초안 전문, diff_preview_lines 기본 40) without adding syntax, format, or dependency details. Some added value comes from documenting the return enum, but that concerns the response, not the parameters.

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+resource: 'shows the difference between an already saved minutes and a draft' (이미 저장된 회의록과 초안의 차이를 보여 줍니다), and frames the purpose as a safety check to prevent overwrite accidents. It is clearly distinct from the write/validation siblings, though it never names an alternative like preview_save_minutes, so sibling differentiation is implicit rather than explicit.

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?

Gives concrete context for when to use it: a second save with the same note_id overwrites the existing file, so check what will be lost first. This is an explicit use-case statement, but it offers no 'when not to use' guidance and no alternative routing, leaving comparison against preview_save_minutes to inference.

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