FX Context

get_historical_reaction_context

get_historical_reaction_context

Read-onlyIdempotent

Summarize the aggregate post-event reaction pattern across historical macroeconomic events similar to a selected target release.

Use this AGGREGATE-PATTERN tool when the user wants to understand what the historical analog sample collectively showed rather than inspect individual analog events.

It summarizes historical outcomes using statistics and behavioral patterns across standardized post-event windows (M5, M15, H1, H4, H24) such as mean, median, quantiles, directional consistency, reaction-path classification (e.g. IMMEDIATE_CONTINUATION, INITIAL_REVERSAL, FADE, DELAYED_REACTION), persistence, and sample-size-based confidence.

Supported event types: US_CPI and US_NONFARM_PAYROLLS across EURUSD, GBPUSD, and USDJPY. ISM is not currently available here: US_ISM_MANUFACTURING and US_ISM_SERVICES have no verified pre-release consensus yet, so they return a structured INSUFFICIENT_HISTORICAL_CALIBRATION error rather than aggregate statistics.

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).

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 goal is to identify, rank, enumerate, or inspect specific historical analog events. For individual historical cases, use get_historical_analogs. When the user asks for both specific cases and collective pattern analysis, invoke both tools.

The results are deterministic empirical observations only and do not predict future prices or provide trading recommendations.

Input Schema

Name	Required	Description
`limit`	No	Optional maximum number of similar historical events to include in aggregate analysis (range 3 to 30, default 10).
`eventType`	Yes	Canonical target event type: US_CPI, US_NONFARM_PAYROLLS, US_ISM_MANUFACTURING, or US_ISM_SERVICES.
`instrument`	No	Optional trading instrument: EURUSD, GBPUSD, or USDJPY. Defaults to EURUSD.
`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
`referencePeriod`	Yes
`aggregatePattern`	Yes
`reactionStatistics`	Yes
`targetSurpriseProfile`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 10, 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, US_ISM_MANUFACTURING, or US_ISM_SERVICES."

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 used 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."

Changed5 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."

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 / $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"
```
removedOutput schema / properties / targetSurpriseProfile / $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 / limit / description

Previous value: -"Optional maximum number of analogs to analyze (range 3 to 30, default 10)."New value: +"Optional maximum number of similar historical events to include in aggregate analysis (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 already declare readOnly/idempotent/non-destructive, yet the description adds substantial non-obvious behavior: supported event types with the ISM unavailability caveat, event-specific similarity methodology, the referencePeriod default and the NO_VERIFIED_PRE_RELEASE_EXPECTATION failure mode, the uniform error shape, and the deterministic/non-predictive 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?

The purpose is front-loaded and each paragraph carries actionable content, but the description is long and the detailed error-shape explanation ('CODE: reason [hint] details={json}') is somewhat verbose. It is dense rather than padded, so waste is limited.

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?

An output schema exists, so return values need not be described. Between the annotations (safety profile) and the description (event coverage, methodology, defaults, error semantics, non-predictive scope), an agent has everything needed to select and invoke the tool correctly.

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 baseline is 3, but the description adds meaning beyond the schema: it explains the referencePeriod retry workflow for prior periods and confirms which eventType values are actually computable here (ISM errors out). It does not restate limit or instrument defaults beyond what the schema already documents.

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?

The description opens with a specific verb and resource: 'Summarize the aggregate post-event reaction pattern across historical macroeconomic events.' It explicitly frames itself as the AGGREGATE-PATTERN tool, distinguishing it cleanly from get_historical_analogs which handles individual cases.

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?

It states the triggering condition ('when the user wants to understand what the historical analog sample collectively showed rather than inspect individual analog events'), an explicit exclusion ('Do NOT use this tool when the user's primary goal is to identify, rank, enumerate, or inspect specific historical analog events'), names the alternative, and even prescribes invoking both when both needs exist.

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?