get_file_diff

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description adds the concrete mechanism (diffing the .bridge.bak backup against on-disk content) and a 'no files modified' side-effect statement. The 'Read-only' lines duplicate the annotation, so the value beyond structured fields is solid but partly redundant.

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?

Front-loaded with the one-line purpose, then organized into labeled sections (What it does / When to use / When NOT / Side effects / Parameters / Returns). Slightly redundant in repeating 'Read-only' in both the opening and the side-effects line, but every section earns its place.

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?

A single-parameter read tool whose description covers purpose, workflow positioning, path semantics, side effects, and return shape; an output schema also exists, so return values need not be detailed further. Nothing an agent needs to invoke it correctly is missing.

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 carries the full burden and does so: file_path is defined as relative to project root, with concrete example paths including a nested 'ui/theme/AppStrings.kt'. It also ties the parameter to entries returned by list_modified_files, which adds meaning the schema lacks.

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: returns before/after content plus a unified diff for a specific modified file, and explains how the diff is computed (.bridge.bak backup vs current on-disk content). This clearly separates it from sibling read tools like list_modified_files and from the approve/reject mutators.

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?

Explicitly gives when to use (inspect exact changes before approving or rejecting), when not to use (call list_modified_files first to obtain valid paths), and names the sibling tools approve_file_changes and reject_file_changes as the downstream actions. No inference required.

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