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

With no annotations, the description still carries the behavioral burden well: it discloses the merge algorithm, the use of the diff3 base, the dual outcome (resolved file vs. exact conflicting key paths with both values), and the effect of prefer=ours|theirs on remaining conflicts. It does not say what happens for input without conflict markers or for malformed content, so it falls short of fully disclosing failure behavior.

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 purpose is front-loaded and the middle is dense but useful. However, the final sentence is cut off mid-thought ('to the remaining'), and the lockfile-type enumeration is repeated twice, which costs clarity in a description that is already long.

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 pure computation tool with three parameters and no output schema, the description explains both return shapes (resolved file or conflicting key paths with both values) and the policy option, which is what an agent mainly needs. It is only missing error and non-conflict input behavior to be fully 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 description coverage is 100%, so the schema already documents content, format, and prefer. The description reinforces the prefer policy ('applies one explicit policy to the remaining') but that sentence is truncated and adds little beyond the enum documentation; the format parameter is not discussed at all in the description.

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 — 'Resolve git conflict markers in package-lock.json or a YAML lockfile' — and then explains the mechanism (rebuilds both sides, merges key by key, diff3 base). An agent can tell this apart from generic diff or patch tools without opening the schema.

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 scope is made explicit: 'for agents rebasing or merging branches', and the input must already contain conflict markers. That is a clear usage context, but there is no statement of when not to use it and no named alternative for related tasks like JSON patch conflicts or pre-merge review.

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