> ## Documentation Index
> Fetch the complete documentation index at: https://self-5d39fc87.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

<CodeGroup>
  ```bash Local server theme={null}
  npx mcp-watchtower scan --server "uvx my-server"
  ```

  ```bash Remote endpoint theme={null}
  npx mcp-watchtower scan \
    --remote "https://api.example.com/mcp" \
    --semantic
  ```

  ```bash Remote endpoint with auth theme={null}
  npx mcp-watchtower scan \
    --remote "https://api.example.com/mcp" \
    --auth-token "$MCP_TOKEN" \
    --semantic
  ```

  ```bash Semantic-only manifest scan theme={null}
  npx mcp-watchtower scan --manifest ./tools.json --name my-server --semantic
  ```

  ```bash Stricter matching theme={null}
  npx mcp-watchtower scan --manifest ./tools.json --threshold 0.8
  ```

  ```bash Semantic-only opt-in theme={null}
  npx mcp-watchtower scan --server "node dist/server.js" --semantic
  ```

  ```bash JSON output theme={null}
  npx mcp-watchtower scan --server "node dist/server.js" --json
  ```
</CodeGroup>

## What happens during a semantic scan

<Steps>
  <Step title="Collect your tools">
    Watchtower resolves the tool list from `--server`, `--remote`, `--manifest`, or stdin exactly the same way it does for static analysis.
  </Step>

  <Step title="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`.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Emit semantic findings">
    Matches above the configured threshold become `ALREADY_IN_CORPUS`, `SEMANTIC_OVERLAP`, or `SEMANTIC_PARAMETER_CONFLICT` findings.
  </Step>
</Steps>

<Note>
  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.
</Note>

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

<CardGroup cols={2}>
  <Card title="Static analysis" icon="shield-check" href="/guides/static-analysis">
    Use `--syntactic` when you want only the deterministic static checks.
  </Card>

  <Card title="CLI reference" icon="terminal" href="/cli/scan">
    See the default full scan, `--semantic`, `--syntactic`, `--threshold`, JSON output, and exit code behavior in one place.
  </Card>

  <Card title="SemanticAnalyzer API" icon="radar" href="/api/semantic-analyzer">
    Use the semantic analyzer directly from TypeScript.
  </Card>
</CardGroup>