Semantic analysis workflow

How to use semantic analysis, interpret overlap findings, and understand the Smithery-backed corpus at a high level.

Semantic analysis compares your tool descriptions against existing MCP tools in the current corpus and also performs the deeper within-server parameter matching pass. Today that corpus is built from Smithery data.

Run it in your workspace

Run a normal scan to get both static and semantic analysis, or add --semantic when you want the semantic layer by itself:

Local server

npx mcp-watchtower scan --server "uvx my-server"

npx mcp-watchtower scan \
  --remote "https://api.example.com/mcp" \
  --semantic

npx mcp-watchtower scan \
  --remote "https://api.example.com/mcp" \
  --auth-token "$MCP_TOKEN" \
  --semantic

npx mcp-watchtower scan --manifest ./tools.json --name my-server --semantic

npx mcp-watchtower scan --manifest ./tools.json --threshold 0.8

npx mcp-watchtower scan --server "node dist/server.js" --semantic

npx mcp-watchtower scan --server "node dist/server.js" --json

What happens during a semantic scan

1. Collect your tools

   Watchtower resolves the tool list from --server, --remote, --manifest, or stdin exactly the same way it does for static analysis.

2. Refresh the local index if a newer one exists

   Before scanning, Watchtower checks the published corpus manifest. If a newer version is available, it downloads semantic.hnsw and semantic-meta.json to ~/.mcp-watchtower/index.

3. Embed and retrieve matches

   For each tool with a non-empty description, Watchtower embeds the description, searches the local HNSW index, and retrieves the closest corpus neighbors.

4. Compare parameter meaning within your server

   Watchtower also embeds parameter context (parameter name + parameter description + tool context) to catch niche parameter aliases that the static checker cannot prove from deterministic normalization alone.

5. Emit semantic findings

   Matches above the configured threshold become ALREADY_IN_CORPUS, SEMANTIC_OVERLAP, or SEMANTIC_PARAMETER_CONFLICT findings.

If the remote manifest is unavailable or the download fails, Watchtower keeps scanning with the bundled index that ships inside the package. Semantic scans are never blocked by an index refresh failure.

Semantic findings are added to the report, but they do not change the exit code. Exit code 1 still means a critical static finding was detected.

Semantic finding types

Finding code	Severity	Meaning	Typical action
ALREADY_IN_CORPUS	info	Your tool appears to already exist in the corpus with the same name and a very similar description.	Confirm whether that corpus entry is yours or intentionally shared.
SEMANTIC_OVERLAP	warning	Your tool is semantically close to a tool from another server.	Make the description more specific so LLMs can distinguish the tools.
SEMANTIC_PARAMETER_CONFLICT	warning	Two parameters in the same server look semantically equivalent even though they use different names.	Standardize the parameter name or tighten the parameter descriptions so the intent is unambiguous.

Current corpus source

Today the semantic corpus comes from Smithery only.

At a high level, Watchtower builds the corpus by collecting tool metadata from popular Smithery servers, normalizing that data, and turning the tool descriptions into a local search index. That means semantic analysis is only as broad as the current Smithery-backed corpus. Additional registries can be added later without changing how you run the scan.

Useful semantic-analysis flags

Flag	Use it when
--semantic	You want only the semantic layer without the deterministic static checks
--threshold <number>	You want stricter or looser similarity matching
--json	You want semantic findings in machine-readable output
no flag	You want the default full scan with both syntactic and semantic analysis

Related pages

Static analysis

Use --syntactic when you want only the deterministic static checks.

CLI reference

See the default full scan, --semantic, --syntactic, --threshold, JSON output, and exit code behavior in one place.

SemanticAnalyzer API

Use the semantic analyzer directly from TypeScript.