FX Context

get_historical_analogs

get_historical_analogs

Read-onlyIdempotent

Find and return individual historical macroeconomic releases whose surprise profiles are most similar to a selected target event.

Use this CASE-RETRIEVAL tool when the user wants to identify, rank, inspect, or compare specific historical analog events.

It returns the matched events themselves, including event identity, similarity characteristics, surprise profile, and each event's observed post-release reaction.

Supported event types: US_CPI and US_NONFARM_PAYROLLS across EURUSD, GBPUSD, and USDJPY. US_PCE is recognized but not yet publicly available: the historical PCE calibration corpus currently has too few usable periods, and a request for US_PCE returns a structured INSUFFICIENT_HISTORICAL_CALIBRATION error (with usable/required event counts) instead of analog results until the corpus grows.

Similarity methodology is event-specific: US_CPI uses headline/core surprise distance; US_NONFARM_PAYROLLS uses target-relative robust scale normalization (nfp-historical-analog-v1); US_PCE (once activated) uses the same raw surprise -distance approach as US_CPI (pce-historical-analog-v1).

Target period: if referencePeriod is omitted, the target is the most recent event of the requested type. Surprises are never estimated, so if that event has no verified pre-release consensus (common right after a new NFP release) the tool fails with NO_VERIFIED_PRE_RELEASE_EXPECTATION. The error details include targetReferencePeriod, latestReleasedPeriod, latestPeriodWithVerifiedExpectation and a hint; to analyze that prior period, retry with referencePeriod=YYYY-MM. Tell the user the newest release could not be analyzed rather than presenting the prior period as the latest.

Every "cannot compute" error has the same shape: "CODE: reason [hint] details={json}", where the JSON always contains code, eventType and hint.

Do NOT use this tool when the user's primary question is about aggregate behavior across the analog sample; use get_historical_reaction_context instead.

The results are historical observations only and do not predict future price direction or provide trading recommendations.

Input Schema

TableJSON Schema

Name	Required	Description
`eventType`	Yes	Canonical target event type: US_CPI, US_NONFARM_PAYROLLS, or US_PCE.
`instrument`	No	Optional trading instrument: EURUSD, GBPUSD, or USDJPY. Defaults to EURUSD.
`maxAnalogs`	No	Optional maximum number of individual analogs to return (range 3 to 30, default 10).
`referencePeriod`	No	Optional reference period in YYYY-MM format (e.g. 2024-06 or 2026-08). If omitted, the most recent event is the target. Use it to analyze a prior period when the latest event has no verified pre-release expectation.

Output Schema

TableJSON Schema

Name	Required	Description	Default
`analogs`	Yes
`coverage`	Yes
`eventType`	Yes
`instrument`	Yes
`methodology`	Yes
`targetSurprise`	Yes
`referencePeriod`	Yes
`methodologyVersion`	Yes
`reactionStatistics`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 8, 2026

changedInput schema / properties / referencePeriod / description

Previous value: -"Optional reference period in YYYY-MM format (e.g. 2024-06 or 2026-08). If omitted, the latest available event is resolved as the target."New value: +"Optional reference period in YYYY-MM format (e.g. 2024-06 or 2026-08). If omitted, the most recent event is the target. Use it to analyze a prior period when the latest event has no verified pre-release expectation."

Changed1 schema field changedSep 23, 2026

changedInput schema / properties / eventType / description

Previous value: -"Canonical target event type: US_CPI or US_NONFARM_PAYROLLS."New value: +"Canonical target event type: US_CPI, US_NONFARM_PAYROLLS, or US_PCE."

Changed3 schema fields changedSep 20, 2026

removedOutput schema / $defs / CpiMetricSurprise

Removed value: -{
-  "properties": {
-    "calculationBasis": {
-      "enum": [
-        "REPORTED_ACTUAL_MINUS_EXPECTATION",
-        "DERIVED_ACTUAL_MINUS_EXPECTATION"
-      ],
-      "type": "string"
-    },
-    "capturedAt": {
-      "format": "date-time",
-      "type": "string"
-    },
-    "consensus": {
-      "type": "number"
-    },
-    "derivedActual": {
-      "type": "number"
-    },
-    "direction": {
-      "enum": [
-        "ABOVE_EXPECTATION",
-        "BELOW_EXPECTATION",
-        "IN_LINE"
-      ],
-      "type": "string"
-    },
-    "provider": {
-      "type": "string"
-    },
-    "reportedActual": {
-      "type": "number"
-    },
-    "surprise": {
-      "type": "number"
-    },
-    "unit": {
-      "type": "string"
-    }
-  },
-  "required": [
-    "consensus",
-    "direction",
-    "reportedActual",
-    "surprise",
-    "unit"
-  ],
-  "type": "object"
-}

removedOutput schema / properties / analogs / items / properties / surpriseProfile / properties

Removed value: -{
-  "coreMom": {
-    "$ref": "#/$defs/CpiMetricSurprise"
-  },
-  "coreYoy": {
-    "$ref": "#/$defs/CpiMetricSurprise"
-  },
-  "headlineMom": {
-    "$ref": "#/$defs/CpiMetricSurprise"
-  },
-  "headlineYoy": {
-    "$ref": "#/$defs/CpiMetricSurprise"
-  }
-}

removedOutput schema / properties / analogs / items / properties / surpriseProfile / type
```
Removed value: -"object"
```

Changed7 schema fields changedSep 20, 2026

changedInput schema / properties / eventType / description

Previous value: -"Canonical target event type. Currently only US_CPI is supported."New value: +"Canonical target event type: US_CPI or US_NONFARM_PAYROLLS."

changedInput schema / properties / referencePeriod / description

Previous value: -"Optional reference period in YYYY-MM format (e.g. 2024-06). If omitted, the latest available event is resolved as the target."New value: +"Optional reference period in YYYY-MM format (e.g. 2024-06 or 2026-08). If omitted, the latest available event is resolved as the target."

removedOutput schema / $defs / CpiSurpriseProfile

Removed value: -{
-  "properties": {
-    "coreMom": {
-      "$ref": "#/$defs/CpiMetricSurprise"
-    },
-    "coreYoy": {
-      "$ref": "#/$defs/CpiMetricSurprise"
-    },
-    "headlineMom": {
-      "$ref": "#/$defs/CpiMetricSurprise"
-    },
-    "headlineYoy": {
-      "$ref": "#/$defs/CpiMetricSurprise"
-    }
-  },
-  "type": "object"
-}

removedOutput schema / properties / analogs / items / properties / surpriseProfile / $ref
```
Removed value: -"#/$defs/CpiSurpriseProfile"
```

addedOutput schema / properties / analogs / items / properties / surpriseProfile / properties

Added value: +{
+  "coreMom": {
+    "$ref": "#/$defs/CpiMetricSurprise"
+  },
+  "coreYoy": {
+    "$ref": "#/$defs/CpiMetricSurprise"
+  },
+  "headlineMom": {
+    "$ref": "#/$defs/CpiMetricSurprise"
+  },
+  "headlineYoy": {
+    "$ref": "#/$defs/CpiMetricSurprise"
+  }
+}

addedOutput schema / properties / analogs / items / properties / surpriseProfile / type
```
Added value: +"object"
```
removedOutput schema / properties / targetSurprise / $ref
```
Removed value: -"#/$defs/CpiSurpriseProfile"
```

Changed1 schema field changedSep 19, 2026

changedInput schema / properties / instrument / description

Previous value: -"Optional trading instrument (EURUSD, GBPUSD, USDJPY). Defaults to EURUSD."New value: +"Optional trading instrument: EURUSD, GBPUSD, or USDJPY. Defaults to EURUSD."

Changed1 schema field changedSep 19, 2026

changedInput schema / properties / instrument / description

Previous value: -"Optional trading instrument. Defaults to EURUSD."New value: +"Optional trading instrument (EURUSD, GBPUSD, USDJPY). Defaults to EURUSD."

Changed1 schema field changedSep 19, 2026

changedInput schema / properties / maxAnalogs / description

Previous value: -"Optional maximum number of analogs to return (range 3 to 30, default 10)."New value: +"Optional maximum number of individual analogs to return (range 3 to 30, default 10)."

First observedSep 18, 2026

TDQS

Score is being calculated.

All FX Context tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?