strip_conflict_markers

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

With no annotations provided, the description carries the full burden. It discloses key behaviors: removes all markers, keeps both sides of every conflict, reports line numbers and conflict count, and writes atomically. This is substantial, though it could mention edge cases like what happens when no markers are present or malformed markers exist.

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 three sentences with no fluff. It front-loads the core action, then provides behavioral details (keep both sides, report, atomic write). Every sentence adds value and is well-structured for scanning.

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 the tool's simplicity (3 params, no output schema, no nested objects), the description is mostly complete: it explains the operation, side effects, and report output. It's missing when-to-use guidance and potential error conditions (e.g., no markers found), but overall it's sufficient for an agent to invoke correctly.

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% — all three parameters (path, encoding, project_root) are described in the schema. The description adds no extra parameter semantics beyond referring to 'a file,' so a baseline score of 3 is appropriate since the schema does the heavy lifting.

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 starts with a specific verb+resource: 'Remove all Git merge conflict markers' from a file, which clearly states the tool's function. It distinguishes itself from sibling editing tools (edit_file_range, insert_at, etc.) by targeting a specific cleanup task rather than general file editing.

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?

While the description doesn't explicitly name alternatives, the context is clear: use this tool when a file contains Git merge conflict markers and you want to remove them in one operation. It implies when to use over general editing tools, but lacks explicit exclusions like 'do not use if you need to manually resolve conflicts.'

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