> ## Documentation Index
> Fetch the complete documentation index at: https://www.worldmonitor.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP tools: Signals & verification

> World Monitor MCP tool reference for event classification, entity extraction, claim verification, social and anomaly signals: parameters, freshness, backing API endpoints and example calls.

Part of the [MCP Tools Reference](https://www.worldmonitor.app/docs/mcp-tools-reference.md), which indexes every tool. Connection, auth, plans and errors are in the [MCP Server overview](https://www.worldmonitor.app/docs/mcp-overview.md).

The `curl` examples assume `export WM_KEY="wm_…"`. With an OAuth token, replace `-H "X-WorldMonitor-Key: $WM_KEY"` with `-H "Authorization: Bearer $TOKEN"`.

### `classify_event`

Classify a supplied news headline or short text into a threat category and severity via the enum-validated WorldMonitor event classifier. The classifier is temperature-0, 24h-cached per title, and only ever returns values from the fixed category/level enums — never free-form LLM output. `classification` is `null` when no enum-valid result could be produced.

**Parameters (tool-specific):**

| Name | Type | Description |
| - | - | - |
| `text` | string (required) | Headline or short excerpt to classify, 1-500 characters. Longer input is rejected with an `error`, not truncated. |

* **API endpoint:** `GET /api/intelligence/v1/classify-event`
* **Access:** `subscription` — requires a Pro subscription. RPC tool: no `summary` argument (use `jmespath` to trim the response).
* **Kind:** bounded canonical-route proxy over an LLM classifier. This op was previously parity-excluded as `llm-passthrough`; the 24h per-title cache absorbs repeats and the classifier is capped at 50 output tokens.
* **Quota:** standard — every call consumes the MCP daily reservation for OAuth and dashboard-issued `wm_…` key contexts (50/UTC day by default). Only legacy operator keys explicitly allowlisted by the deployment skip that daily reservation; every authenticated context remains bounded by the 60 requests/minute limiter.

```bash curl theme={null}
curl -s https://worldmonitor.app/mcp \
  -H "X-WorldMonitor-Key: $WM_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc":"2.0","id":1,
    "method":"tools/call",
    "params":{"name":"classify_event","arguments":{"text":"Iran closes Strait of Hormuz to tanker traffic"}}
  }'
```

### `extract_entities`

Deterministic named-entity extraction shared with the dashboard: registry entities (companies, indices, commodities, crypto, sectors, countries — alias and keyword matched) plus pattern entities (CVE IDs, APT/FIN threat-group designators, tracked world leaders). No LLM is involved.

**Parameters (tool-specific):**

| Name | Type | Description |
| - | - | - |
| `text` | string | Optional text to extract from, max 2048 characters (longer input is rejected with an `error`). When omitted, the tool aggregates entities across the current headline digest instead. |
| `variant` | `string: full / tech` | In headlines mode, which digest to aggregate. Defaults to `full`; use `tech` for the Tech dashboard categories. Ignored in text mode. |
| `languages` | string\[] | Content languages to read (ISO 639-1), up to 8: `en`, `ar`, `bg`, `cs`, `da`, `de`, `el`, `es`, `fa`, `fr`, `hi`, `hr`, `hu`, `it`, `ja`, `ko`, `nl`, `no`, `pl`, `ro`, `ru`, `sv`, `tr`, `uk`, `vi`, `zh`. Defaults to `["en"]`. Each item's language is its outlet's content language. Titles stay untranslated. |
| `editions` | string\[] | Digest editions to read: `full`, `tech`, `finance`, `commodity`, `happy`, `energy`. Defaults to `["full"]`. `variant` is the same as one edition; passing both with different values is an `error`. |
| `category` | string (enum) | In headlines mode, restrict aggregation to one category of the selected editions (case-sensitive). `full`: `politics`, `us`, `europe`, `middleeast`, `tech`, `ai`, `finance`, `commodities`, `gov`, `africa`, `latam`, `asia`, `energy`, `thinktanks`, `crisis`, `layoffs`, `science`, `intel`. `tech`: `tech`, `ai`, `startups`, `vcblogs`, `regionalStartups`, `unicorns`, `accelerators`, `security`, `policy`, `github`, `funding`, `cloud`, `layoffs`, `finance`, `dev`, `ipo`, `producthunt`, `hardware`, `outages`, `thinktanks`, `podcasts`. `finance`: `markets`, `forex`, `bonds`, `commodities`, `crypto`, `centralbanks`, `economic`, `ipo`, `derivatives`, `fintech`, `fin-regulation`, `institutional`, `analysis`, `gccNews`, `nq-news`. `commodity`: `commodity-news`, `gold-silver`, `energy`, `mining-news`, `critical-minerals`, `base-metals`, `mining-companies`, `supply-chain`, `commodity-regulation`, `markets`, `finance`. `happy`: `positive`, `science`, `nature`, `inspiring`, `community`. `energy`: `live-news`, `energy`, `supply-chain`. Echoed as `category` in the result (`null` when omitted). An unknown value yields `headlineCount: 0` and a `note` listing categories present in the current digest. |
| `limit` | integer | Maximum entities per list (1-50). Defaults to 20. |

* **API endpoints:** `GET /api/news/v1/list-feed-digest` for one English edition, `GET /api/news/v1/list-news-pool` for anything wider (headlines mode only; text mode performs no fetch). A wider read echoes `languages` and `editions` and adds `poolCoverage` (see `get_news_clusters`). Registry names match as written, so untranslated non-English headlines match fewer entities.
* **Access:** `subscription` — requires a Pro subscription. RPC tool: no `summary` argument (use `jmespath` to trim the response).
* **Kind:** deterministic local compute over the shared extraction cores. In headlines mode, entities aggregate to `mentionCount`/`avgConfidence`; in text mode each match reports `matchType`, `matchedText`, and `confidence`.
* **Quota:** standard — every call consumes the MCP daily reservation.

```bash curl theme={null}
curl -s https://worldmonitor.app/mcp \
  -H "X-WorldMonitor-Key: $WM_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc":"2.0","id":1,
    "method":"tools/call",
    "params":{"name":"extract_entities","arguments":{"text":"CVE-2026-12345 exploited by APT28 against Microsoft cloud tenants"}}
  }'
```

### `verify_claim`

Evidence card for a claim or headline. Finds the clusters of fresh headlines that report the same event (one event often spans several clusters) and returns WorldMonitor's coverage verdict over them. It searches the English edition only: it takes no `languages` or `editions`, because matching a claim against another language needs translation first. With `variant: full`, the default, it searches every fresh headline in WorldMonitor's feed caches, up to 30 per feed, not only the headlines the dashboard digest serves; the 100 headlines that share the most of the claim's words are clustered. The `tech` variant searches its digest. A cluster matches when one of its headlines carries at least half of the claim's content words, and at least two of them; the 8 best-matching clusters are kept. The verdict is `assessCorroboration` over every matched headline, so syndicated feeds of one publisher count once.

The result reports `found`, `state` (the coverage verdict; `not-found` when the digest was searched and nothing reports the claim; `unknown` with `found: false` when the digest was empty or unavailable, so nothing was searched), `corroboration` (`single-publisher`, `tier4-only`, `corroborated`, `unknown`), the `publishers` roster with declared tiers, up to 10 matched `headlines` with fail-closed source provenance, `credibilityScore` of the best match, `firstSeen` / `lastUpdated`, and `figures`: numbers and dates in the claim checked against the matched headlines with the brief grounding rule. `figures.ungrounded` lists figures no matched headline states; it does not mean the figure is wrong. `found: false` means no match: with `state: not-found` the claim is not in WorldMonitor's current sources; with `state: unknown` nothing was searched. It never means the claim is false. Every response carries the same `caveat`: coverage, not accuracy.

`factChecks` cites ratings that fact-checkers have already published about a similar claim. WorldMonitor does not rate claims; it quotes theirs with attribution, the way it would quote a wire report. Each item gives the fact-checker (`publisher`, `site`), its own `rating` verbatim, the date it was published (`reviewedAt`), the `url`, and the `claimReviewed` it rated, introduced by `label`: a fact-check of a similar claim, never of this claim. The rules:

* Only verified signatories of the [IFCN Code of Principles](https://github.com/IFCN/verified-signatories), kept in `shared/fact-checkers.json` and reviewed like source tiers. The link's own domain decides, not the name the feed reports.
* Strong matches only: the claim and the rated claim must each carry at least 60% of the other's content words, and share at least three. A weaker match shows nothing.
* English fact-checks of any age, newest first. Ratings that disagree are all listed, with no tie-breaking.
* The same rules apply whoever made the claim: nothing in the matching names a person, party, topic or country.
* A rating never changes `state`, `corroboration` or anything else in the card.

`factChecks.state` is `ok` when the lookup ran (an empty `items` list then means none was found) and `unavailable` or `not-configured` when it did not. A failed lookup never fails the tool. Ratings come from the Google Fact Check Tools API.

**Parameters (tool-specific):**

| Name | Type | Description |
| - | - | - |
| `claim` | string | The claim or headline to check, up to 300 characters. Required. |
| `variant` | `string: full / tech` | Headline digest variant to search. Defaults to full. |

* **API endpoints:** `GET /api/news/v1/list-feed-digest`, `GET /api/news/v1/search-fact-checks`, `GET /api/news/v1/search-claim-headlines`
* **Access:** `subscription` — requires a Pro subscription.
* **Kind:** deterministic local compute over the fresh-headline window (the last 96 hours), not a historical index. No LLM.
* **Quota:** standard — every call consumes the MCP daily reservation.

```bash curl theme={null}
curl -s https://worldmonitor.app/mcp \
  -H "X-WorldMonitor-Key: $WM_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc":"2.0","id":1,
    "method":"tools/call",
    "params":{"name":"verify_claim","arguments":{"claim":"Trump strikes diesel deal with Putin"}}
  }'
```

### `get_keyword_spikes`

Trending keyword, CVE, and APT/FIN threat-group spikes versus baseline, using the same term-candidacy and spike-decision math as the dashboard's trending-keywords engine (minimum recent count, strict baseline multiplier, source-diversity gate). The story accumulator it reads holds the English `full` edition only, so it takes no `languages` or `editions`. Each spike includes `sourceNames` (curated publisher name, or the original feed label when unmapped) and up to three `sampleHeadlines` as `{title, source, link}` objects so an agent can attribute and follow the stories behind the count. `source` on a sample is every publisher that carried that collapsed title; `link` is the canonical `story:track:v1` URL and may not belong to a single named outlet. The tool queries the recent window and its pre-window baseline as separate cohorts, each capped at 800 stories, so a busy recent window cannot consume the baseline sample. `baseline_hours` reports the exact sampled pre-window duration, and `sample_truncated: true` means either cohort reached its cap. When no pre-window stories are available, the tool returns no spikes with an explicit `baseline unavailable` note and does not cache the result. Results are cached for 10 minutes per `(window_hours, min_count)` combination.

**Parameters (tool-specific):**

| Name | Type | Description |
| - | - | - |
| `window_hours` | integer | Recent window to test for spikes (1-12). Defaults to 2. |
| `min_count` | integer | Minimum recent-window story count for a term to spike (2-20). Defaults to 5. |
| `limit` | integer | Maximum spikes returned (1-25). Defaults to 10. |

* **API endpoint:** none — reads the story accumulator and story-track keys from Redis directly; no HTTP endpoint is proxied.
* **Access:** `subscription` — requires a Pro subscription. RPC tool: no `summary` argument (use `jmespath` to trim the response).
* **Kind:** deterministic local compute with a 10-minute Redis result cache. `note` is present when the accumulator is unavailable/empty or the story store was only partially readable — a partial read is never cached, so a transient Redis fault cannot serve wrong spikes for the rest of the TTL.
* **Quota:** standard — every call consumes the MCP daily reservation.

```bash curl theme={null}
curl -s https://worldmonitor.app/mcp \
  -H "X-WorldMonitor-Key: $WM_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc":"2.0","id":1,
    "method":"tools/call",
    "params":{"name":"get_keyword_spikes","arguments":{"window_hours":2,"limit":10}}
  }'
```

### `get_social_velocity`

The 30 posts from r/worldnews and r/geopolitics with the highest `velocityScore` (log of score × upvote ratio × a 6-hour recency decay), with score, upvote ratio, comment count and the permalink as `url`. The relay refreshes it about every 3 hours and the envelope flags it stale after 9 hours, the same budget as `/api/health`. Posts are unverified user submissions: the tool measures public attention, not events.

**Parameters (tool-specific):**

| Name | Type | Description |
| - | - | - |
| `subreddit` | string | Keep one subreddit: "worldnews" or "geopolitics". |
| `limit` | number | Cap the post list to at most this many items (default 30, pass 0 for no cap). |

* **API endpoints:** `GET /api/intelligence/v1/get-social-velocity`
* **Access:** `free-account` — callable by any signed-in account; free accounts spend the daily free allowance, Pro calls spend the daily quota. Accepts the universal `summary` argument.
* **Kind:** cache read — sub-second response from Redis bootstrap cache.
* **Freshness budget:** up to **9 h** before `stale: true` is flagged (the relay refreshes about every 3 h; same budget as `/api/health`).

```bash curl theme={null}
curl -s https://worldmonitor.app/mcp \
  -H "X-WorldMonitor-Key: $WM_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc":"2.0","id":1,
    "method":"tools/call",
    "params":{"name":"get_social_velocity","arguments":{}}
  }'
```

### `list_x_feed`

Curated public news-account posts from monitored X accounts. Returns permalink plus derived facts only — never tweet bodies. Use this to see which accounts posted recently, not to redistribute post text.

**Parameters:**

| Name | Type | Required | Description |
| - | - | -: | - |
| `limit` | number | no | Maximum posts to return (1-200, default 50) |
| `topic` | string | no | Optional topic filter such as breaking, conflict, geopolitics, cyber |
| `account` | string | no | Optional account handle without @ |

* **API endpoints:** `GET /api/intelligence/v1/list-x-feed`
* **Access:** `subscription` — requires a Pro subscription. RPC tool: no `summary` argument (use `jmespath` to trim the response).
* **Kind:** live RPC — proxies a fetch to the WorldMonitor API on each call. Edge-runtime timeout: **10.0s**.
* **Content policy:** post text is R4. MCP/embed partners receive facts + permalink only.

```bash curl theme={null}
curl -s https://worldmonitor.app/mcp \
  -H "X-WorldMonitor-Key: $WM_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc":"2.0","id":1,
    "method":"tools/call",
    "params":{"name":"list_x_feed","arguments":{"limit":20,"topic":"breaking"}}
  }'
```

### `get_temporal_anomalies`

Temporal anomaly watch: current event counts vs day-of-week and seasonal baselines, scored by z-score severity. News velocity, satellite fire detections, and other tracked streams are compared against 90-day Welford baselines keyed by weekday and month. Each anomaly carries the observed count, expected baseline count, z-score, multiplier, and a severity band (medium ≥ 1.5σ, high ≥ 2σ, critical ≥ 3σ). An empty anomaly list with fresh data means activity is within normal bounds — that is itself signal.

**Parameters (tool-specific):**

| Name | Type | Description |
| - | - | - |
| `type` | string | Filter to one tracked stream type (e.g. "news", "satellite\_fires"); see trackedTypes in the response for what is currently baselined. |
| `region` | string | Filter to one region label (case-insensitive exact match). |
| `min_severity` | string: medium / high / critical | Drop anomalies below this severity band. |
| `limit` | number | Cap the anomaly list to at most this many items (default 30, pass 0 for no cap). |

* **API endpoints:** none (MCP-only; the REST baseline endpoints are write-through and excluded from parity).
* **Access:** `free-account` — callable by any signed-in account; free accounts spend the daily free allowance, Pro calls spend the daily quota. Accepts the universal `summary` argument.
* **Kind:** cache-only read — sub-second response from Redis bootstrap cache. MCP calls do not invoke the producer or trigger a rebuild.
* **Freshness budget:** up to **45 min** before `stale: true` is flagged. Only traffic to the underlying producer route/RPC (`GET /api/infrastructure/v1/list-temporal-anomalies`) triggers an on-demand rebuild once the snapshot is older than 20 min. `cached_at` records that rebuild — not the time of the MCP call — so it advances only when the producer route rebuilds the snapshot. With no traffic to that route, the request-driven stamp can age past the budget.

```bash curl theme={null}
curl -s https://worldmonitor.app/mcp \
  -H "X-WorldMonitor-Key: $WM_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc":"2.0","id":1,
    "method":"tools/call",
    "params":{"name":"get_temporal_anomalies","arguments":{"min_severity":"high"}}
  }'
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.