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.

ISM is not currently available here: US_ISM_MANUFACTURING and US_ISM_SERVICES have no verified pre-release consensus yet, so they return INSUFFICIENT_HISTORICAL_CALIBRATION rather than analogs. For ISM, use get_event_context for actuals and get_market_reaction for price moves.

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.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "eventType": "<eventType>"
    },
    "name": "get_historical_analogs"
  }
}

Input Schema

Name	Required	Description
`eventType`	Yes	Canonical target event type: US_CPI, US_NONFARM_PAYROLLS, US_PCE, US_ISM_MANUFACTURING, or US_ISM_SERVICES.
`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

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.

Changed3 schema fields changedOct 10, 2026

changedInput schema / properties / eventType / description

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

addedOutput schema / properties / methodology / properties / minimumCalibrationEvents
```
Added value: +{
+  "format": "int32",
+  "type": "integer"
+}
```
addedOutput schema / properties / methodology / properties / minimumCalibrationEventsBeforeTarget
```
Added value: +{
+  "format": "int32",
+  "type": "integer"
+}
```

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

A4.8/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only cover the safety profile (readOnly, idempotent, closed-world); the description goes far beyond by disclosing the per-event-type similarity methodology, the unavailability of US_PCE and ISM with the specific INSUFFICIENT_HISTORICAL_CALIBRATION error, the NO_VERIFIED_PRE_RELEASE_EXPECTATION failure mode, the uniform error shape, and a no-prediction disclaimer.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded purpose sentence followed by usage, then capability boundaries, then error semantics. Dense and mostly waste-free, though the error-handling and methodology paragraphs could be tightened and the return-value sentence partially duplicates what the output schema already conveys.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given a 4-parameter tool with an output schema, the description covers everything an agent needs: supported event/instrument matrix, per-type methodology, target-period defaulting, every known error code and its structure, and explicit anti-prediction framing. Nothing consequential is left to inference.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: default-target behavior when referencePeriod is omitted, the failure mode that makes an override necessary, and the retry-with-YYYY-MM recovery path. It does not add anything for maxAnalogs or instrument beyond the schema, keeping it short of a 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Find and return individual historical macroeconomic releases whose surprise profiles are most similar to a selected target event') and explicitly labels itself a 'CASE-RETRIEVAL tool' that returns matched events rather than aggregates. This cleanly separates it from the sibling get_historical_reaction_context, which it names directly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit when-to-use ('when the user wants to identify, rank, inspect, or compare specific historical analog events') and when-not-to-use ('Do NOT use this tool when the user's primary question is about aggregate behavior...use get_historical_reaction_context instead'), plus routing guidance for ISM events to get_event_context and get_market_reaction.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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?