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

Annotations only declare it is a non-read-only, non-destructive, open-world tool; the description goes further by stating the merge policy (keep both sides' work, never delete), the verification gate before resolving, and the return payload with an open-count. What is missing is failure/recovery behavior — e.g., what happens if the merge fails tests, or whether claiming locks the collision from other agents.

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?

Four sentences, front-loaded with the trigger condition, then merge policy, then the resolve step, then the return. Every sentence carries operational content; the only soft spot is the parenthetical handle (reconciliations_pending) and the closing return sentence, which read slightly compressed.

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 two-parameter tool with no output schema, the description supplies the return contents and open count, the merge invariant, and the workflow ordering. The remaining gap is edge-case completeness: how to un-claim, what a failed test means for the held reconciliation, and whether repeated claims are idempotent.

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 already 100%, with repo_id's default-session behavior documented in the schema itself. The description adds real meaning only for resolve — that ids should be supplied after the merge is verified — which is a modest supplement over a well-documented two-parameter schema, so baseline 3 is appropriate.

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 concrete verb and resource — claim open collisions between two agents' work and later resolve them by id — and disambiguates a name (pending_reconciliations) that would otherwise read as a pure list operation. It is clear that this both mutates state and returns the claimed set, though the two-mode (claim/resolve) shape takes two sentences to emerge.

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 trigger is explicit: call when a response reports reconciliations_pending. The second invocation is gated on a concrete condition (merge merged and tests pass), which is real sequencing guidance. It does not compare against siblings like claim, defer_intent, or inbox_ack, so an agent gets a clear entry point but no exclusion rule.

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