knowl_conflicts

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

Annotations already establish readOnlyHint=true and openWorldHint=false; the description builds on this by explaining the system behavior behind the tool: the write path 'deliberately keeps [polarity pairs] side by side rather than letting either retire the other', and it discloses a limitation (REVERSAL reports are excluded). It does not conflict with the annotations and adds meaningful behavioral context beyond them.

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 main purpose is front-loaded in the first sentence, and each of the four sentences earns its place: purpose, when-to-use, when-not-to-use, and resolution path. The first sentence is somewhat dense with a nested parenthetical, but overall there is no filler.

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 zero-parameter, read-only list tool with no output schema, the description covers purpose, the two conflict kinds, usage triggers, an exclusion, and the resolution tool. The only notable gap is the lack of any hint about the output shape (e.g., what fields each listed conflict carries), which would be the description's responsibility given there is no output schema.

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?

The tool has zero parameters (schema coverage is trivially 100%), so the 0-params baseline of 4 applies. The description correctly focuses on behavioral scope rather than inventing parameters; there is nothing in the empty schema for the description to clarify.

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 opens with a specific verb and resource: 'List contradictions among active items', and enumerates the two kinds of results (declared exclusive conflict keys and detected polarity pairs), explaining what a polarity pair is. This clearly differentiates it from siblings like knowl_query or knowl_drift, which could otherwise plausibly overlap.

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?

Two concrete trigger conditions are given explicitly: 'when a write reports an overlapping item left active, or when memory gives contradictory answers.' It also names an explicit when-not case ('A write that reports a possible REVERSAL is telling you something this command does not list -- act on it there') and identifies the alternative for resolution ('Resolve with knowl_update, never by storing a third item').

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