parity_gaps

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

With no annotations, the description carries the burden of behavioral disclosure. It states that the tool is a probe, reports coverage states, and explicitly says it is not the fix, implying non-mutating behavior. However, it does not clarify whether it requires a prior scan, how fresh the data is, or what 'cheap' means operationally.

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 concise, two sentences, with the core output stated first and the strategic purpose second. The phrasing 'cheap probe's target list' is somewhat cryptic but does not waste words. It earns high marks for brevity and front-loading.

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?

The description gives a rough idea of the return value—counts per state—but leaves key context undefined: what dimensions are, how the `goal` parameter factors in, and how this tool relates to parity_scan or gap_scan. With no output schema and no annotations, these omissions make the tool hard to invoke with confidence.

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 50%, with `cwd` documented but `goal` entirely undescribed. The description adds no parameter meaning and fails to clarify what `goal` represents in the context of coverage gaps. This is a notable gap for an agent trying to invoke the tool correctly.

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 identifies the tool's output as coverage by dimension with counts of unknown, missing, partial, or satisfied features. It also frames it as a cheap probe's target list, which conveys its role as a diagnostic. However, it lacks an explicit verb and does not differentiate it from sibling tools like parity_scan or gap_scan.

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 description implies usage context: it is a cheap probe that decides where to spend effort and is not itself the fix. This gives a clear sense of when to consult it, but it does not explicitly mention alternatives, prerequisites, or when not to use it. The guidance is embedded rather than explicit.

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