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

Annotations already declare read-only, idempotent, local, non-destructive behavior, but the description adds valuable context beyond them: it runs git reads only, uses no network, returns exit 0/1/2 plus a JSON report, and explains that exit 2 means nothing was decided and why.

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 front-loaded with the primary use case and the sibling alternative, then concisely covers exit semantics and read-only behavior. Every sentence carries operational value.

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 complex audit tool with an output schema, rich annotations, and full parameter documentation, the description supplies the remaining needed context: when to use it, when not to, exit-code meaning, and local-git/no-network behavior.

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 three parameters are already documented in the schema. The description does not add parameter-specific meaning for strict or published_file, so the baseline score of 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?

States a specific audit action over the whole tag history and frames the core question precisely: whether each version label names exactly one code state. It also distinguishes the tool from sibling would_tag for single-release checks.

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?

Explicitly says to use this for whole tag-history audits and routes single-release tagging checks to would_tag. It also calls out the edge case of one release only being undecided via exit 2.

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

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

Beyond the annotations, it discloses the full outcome contract: exit 0/1/2 semantics, that exit 1 means both declare one label but code differs, and that exit 2 means nothing was decided with a stated reason. It also confirms the read-only, local-only, no-network execution profile, which is richer than readOnlyHint alone.

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?

Front-loaded with the purpose, then the outcome contract in a compact sequence. The exit-code sentences are dense but each carries decision-relevant information; the sole visible duplication is the no-network clause already implied by openWorldHint=false.

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 3-required-param comparison tool with an output schema, this covers the gaps that matter: how to read exit codes, what exit 2 means operationally, and that execution is local and side-effect free. Nothing an agent needs to invoke and interpret the call is missing.

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 100%, so the baseline is 3; the description adds that both operands are user-named tags or commits and clarifies the directional semantics of the comparison output ('only in a, only in b'). It does not add format or resolution rules (e.g. ambiguous tag vs branch names) beyond the schema.

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 (compare two tags or commits) and enumerates exactly what the comparison yields: version labels, closures, and differing paths. 'Publication points play no part' implicitly separates it from the release/publication-oriented siblings like would_tag.

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?

'Use to compare any two tags or commits you name' gives a clear trigger plus the exit-code contract that tells the agent how to interpret outcomes. It does not explicitly name the sibling alternatives (check_versions, explain_label) or state when not to use it, which keeps it short of a 5.

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

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

Annotations cover the safety profile (readOnly, non-destructive, idempotent, closed-world), yet the description adds genuinely new behavior: exit codes 0/1/2, that exit 2 means nothing was decided, and reasons it can occur. It also restates the local-git-reads-only constraint, rounding out operational context beyond structured fields.

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?

Front-loaded with the trigger condition and core action; the exit-code sentence is dense but earns its place for a tool whose status codes are semantically meaningful. Slightly heavy, but 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?

Output schema exists so return values needn't be explained, and the description still covers the exit-code contract and failure modes. For a 2-param read-only tool, nothing an agent needs to call it correctly is missing.

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 100%, so both params are already documented (repo path with tags fetched, label as written in drift). The description reinforces label semantics via 'first tag that used it' but adds no syntax or format detail beyond the schema, so baseline 3 applies.

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 (list paths that differ for one label between tags) and explicitly differentiates from siblings: 'Use after check_versions reports drift' and 'For two references you choose, use compare.' An agent can place this tool precisely among its siblings without opening schemas.

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?

Explicit ordering guidance (use after check_versions reports drift) and a named alternative with the condition that selects it (compare for two arbitrary references). When-to-use is unambiguous.

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

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

Beyond annotations, it explains all three exit codes, stresses that exit 2 is not a pass, and gives examples of why exit 2 occurs. It also confirms read-only local git reads with no network, aligning with and enriching the annotation profile.

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 front-loaded with the primary instruction and then efficiently covers exit-code semantics and read-only behavior. Every sentence contributes operational meaning without unnecessary repetition.

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 single parameter, existing output schema, and rich annotations, the description supplies the missing behavioral context an agent needs: when to call it, how to interpret exits, and why exit 2 is not success. No critical pre-call information appears to be missing.

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?

There is only one parameter and schema description coverage is 100%, so the schema already explains that `repo` is a local git repository with tags fetched. The description reinforces the local-repository context but adds no additional syntax or constraints beyond the schema.

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 specific pre-tag check: whether the version declared by HEAD would reuse a label already present in tags. It is clear about the resource and operation, but it does not explicitly distinguish itself from siblings like check_versions or compare.

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?

It gives a clear usage context: "Use BEFORE creating a release tag" and explains that exit 1 means do not tag and bump the version first. It does not state when to choose a sibling tool instead, so it stops short of full alternative routing guidance.

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