H1: Tool Description Ambiguity #

Checks empty and underspecified short descriptions, selected vague opening verbs, duplicate tool names, high word overlap, and relational nondistinction. Findings keep pattern_id: H1; code provides the more specific stable identifier.

One-sided H1.6 containment and non-identical H1.5 overlap are suppressed when both tools declare different input names, types, or choices in nonempty property schemas: those inputs provide a selection distinction. Descriptions that are nearly identical (95% or greater word overlap) still receive H1.5. H3 does not demand duplicate descriptions for scalar parameters explained by an enum, const, format, a named boolean switch, or the tool description. Ambiguous parameters such as an unconstrained role or line/column coordinates still need semantics. These are bounded heuristics, not proof of semantic completeness.

Server manifests with server, tools, and root instructions retain their instruction text for evidence-bearing checks, but do not inherit host-agent requirements for a retry budget, output format, version, or priority ordering. Percent-delimited localization references are not counted as inspected tool prose; not_inspected names unresolved tool and schema descriptions. No sibling files or remote localization resources are fetched. Skill source catalogs with repo and skillPath are explicitly skipped; their bodies are not present.

For a Markdown file with name/description front matter (a skill or sub-agent definition) the description is the selection-time text, so H1.1 (no description, HIGH) and H1.2 (under 20 characters, MEDIUM) apply to it, located at frontmatter.description with its line. H1.8 looks for trigger vocabulary ("use when", "if the user", "before", a description written as the situation); it is a finite vocabulary, which is why a long description is only LOW. H1.9's directory comparison runs only for a file named SKILL.md.

H1.3's vague verbs are handle, process, manage, do, perform, deal, work, and it reports only a description under 60 characters: a vague opener followed by the specifics has said what the tool does. get, set, run, execute, use and make were removed: on real MCP manifests every hit on them was a precise description ("Get the current time in a timezone"). One-sided H1.6 (domination) additionally requires that the two tools share a domain term, not only a generic verb class, and open with the same action.

H1.5 uses Jaccard word similarity with stopword removal. Differently named tools whose descriptions each carry a term the other lacks are a parallel family ("List code scanning alerts" / "List secret scanning alerts", add / remove) and are not reported below 95% overlap; nor is a pair in which a description states the selection rule ("Prefer this tool over X"). H1.6 compares analyzed terms from tool names and descriptions under a finite synonym lexicon. It can reach some pairs missed by word overlap: "Look up an order" and "Search for orders in the system" have Jaccard 0.00 under H1.5 but no differentia under H1.6's term model. Mutual nondistinction means neither member distinguishes itself; directional domination identifies the less-specific member when one contributes no terms beyond the other. Explicit named boundaries and distinguishing tool names can exempt a pair; declared aliases are not automatically exempted.

The comparison scope is one parsed input. Directory scans do not aggregate tools across files or infer a shared selection namespace. H1.6 is MEDIUM and cannot alone trip --fail-on fail; use --fail-on review to gate MEDIUM findings. Its lexicon is finite: pairs outside it, such as kill/terminate or approve/authorize, are not detected. External labeled-corpus precision and recall have not been measured. The absence of a finding is not semantic or runtime validation.

Alias recognition is also phrase-bound. Compatibility alias for X, Deprecated. Use X, and Superseded by X are recognized. Paraphrases such as "does the same thing as X, kept for backward compatibility" or "older entry point, prefer X in new code" are not equivalent coverage promises. See Tool Differentia and research lineage for provenance.