Macro Conditions MCP: Tool Contracts

Macro Conditions MCP: Tool Contracts

This document defines the API contracts for Macro Conditions MCP tools. All tools consume raw data from Core Government Data MCP and produce macroeconomic regime indicators and pressures.

Common Input Types

See Market Structure MCP Contracts for Year Range definitions.

Common Output Types

See Market Structure MCP Contracts for Provenance Envelope, Success Response, and Error Response definitions.

Tool Contracts

1. get_regime_indicators

Get macroeconomic regime indicators (expansion/recession/tightening/easing) for a given time range.

Signature:

get_regime_indicators(
  year_range: { start_year: integer, end_year: integer }
) -> SuccessResponse | ErrorResponse

Input Parameters:

Parameter Type Required Description
year_range object Yes { start_year: integer, end_year: integer }

Success Response Data:

{
  "success": true,
  "data": {
    "current_regime": string,           // "expansion", "recession", "tightening", "easing"
    "regime_confidence": number,        // Confidence score (0-100)
    "gdp_growth_pct": number,          // Current GDP growth rate
    "inflation_rate_pct": number,      // Current inflation rate (CPI)
    "unemployment_rate_pct": number,   // Current unemployment rate
    "fed_funds_rate_pct": number,      // Current federal funds rate
    "regime_history": [                // Historical regime changes
      {
        "year": integer,
        "quarter": integer,
        "regime": string,
        "indicators": {
          "gdp_growth_pct": number,
          "inflation_rate_pct": number,
          "unemployment_rate_pct": number
        }
      }
    ],
    "year_range": {
      "start_year": integer,
      "end_year": integer
    }
  },
  "provenance": { /* ProvenanceEnvelope */ }
}

Example:

{
  "success": true,
  "data": {
    "current_regime": "expansion",
    "regime_confidence": 85.5,
    "gdp_growth_pct": 2.5,
    "inflation_rate_pct": 3.2,
    "unemployment_rate_pct": 3.7,
    "fed_funds_rate_pct": 5.25,
    "regime_history": [
      {
        "year": 2020,
        "quarter": 2,
        "regime": "recession",
        "indicators": {
          "gdp_growth_pct": -9.1,
          "inflation_rate_pct": 0.6,
          "unemployment_rate_pct": 13.0
        }
      },
      {
        "year": 2021,
        "quarter": 1,
        "regime": "expansion",
        "indicators": {
          "gdp_growth_pct": 6.3,
          "inflation_rate_pct": 2.6,
          "unemployment_rate_pct": 6.0
        }
      }
    ],
    "year_range": {
      "start_year": 2020,
      "end_year": 2023
    }
  },
  "provenance": {
    "sources": [
      {
        "agency": "Federal Reserve Economic Data",
        "dataset": "FRED",
        "dataset_id": "FRED_GDP_2020_2023",
        "release_date": "2024-01-31",
        "variables": ["GDP", "GDPC1", "CPIAUCSL", "UNRATE", "FEDFUNDS"]
      }
    ],
    "transforms": [
      "Calculated GDP growth rates",
      "Calculated inflation rates from CPI",
      "Classified regime based on GDP growth, unemployment, and Fed policy",
      "Identified regime transitions"
    ],
    "units": {
      "currency": "USD",
      "inflation_base_year": 2023,
      "geography": "us:*"
    },
    "methodology": "Regime indicators calculated by analyzing GDP growth, unemployment, inflation, and Federal Reserve policy. Regime classification: expansion (positive GDP growth, low unemployment), recession (negative GDP growth, high unemployment), tightening (rising rates), easing (falling rates)."
  }
}

Error Codes:

  • data_not_available - Data not available for year range
  • invalid_year_range - Invalid year range
  • api_error - Upstream API failure

Non-Goals:

  • Does NOT predict future regimes
  • Does NOT provide industry-specific regime effects (use get_industry_macro_effects)

2. get_industry_macro_effects

Get industry-specific macroeconomic effects (how macro conditions affect a given industry) over a time range.

Signature:

get_industry_macro_effects(
  naics: string,
  year_range: { start_year: integer, end_year: integer }
) -> SuccessResponse | ErrorResponse

Input Parameters:

Parameter Type Required Description
naics string Yes NAICS code (2-6 digits)
year_range object Yes { start_year: integer, end_year: integer }

Success Response Data:

{
  "success": true,
  "data": {
    "macro_sensitivity": number,        // Sensitivity to macro conditions (0-100)
    "recession_impact": number,        // Expected impact during recession (-100 to 100)
    "expansion_benefit": number,       // Expected benefit during expansion (0-100)
    "inflation_sensitivity": number,   // Sensitivity to inflation (0-100)
    "rate_sensitivity": number,        // Sensitivity to interest rates (0-100)
    "yearly_effects": [                // Year-by-year breakdown
      {
        "year": integer,
        "regime": string,
        "industry_growth_pct": number,
        "gdp_growth_pct": number,
        "impact_multiplier": number    // Industry growth / GDP growth
      }
    ],
    "naics": string,
    "year_range": {
      "start_year": integer,
      "end_year": integer
    }
  },
  "provenance": { /* ProvenanceEnvelope */ }
}

Example:

{
  "success": true,
  "data": {
    "macro_sensitivity": 72.5,
    "recession_impact": -15.3,
    "expansion_benefit": 8.2,
    "inflation_sensitivity": 45.0,
    "rate_sensitivity": 35.5,
    "yearly_effects": [
      {
        "year": 2020,
        "regime": "recession",
        "industry_growth_pct": -8.5,
        "gdp_growth_pct": -3.4,
        "impact_multiplier": 2.5
      },
      {
        "year": 2021,
        "regime": "expansion",
        "industry_growth_pct": 6.2,
        "gdp_growth_pct": 5.7,
        "impact_multiplier": 1.09
      }
    ],
    "naics": "54",
    "year_range": {
      "start_year": 2020,
      "end_year": 2023
    }
  },
  "provenance": {
    "sources": [
      {
        "agency": "Bureau of Economic Analysis",
        "dataset": "GDP by Industry",
        "dataset_id": "GDP_IND_2020_2023",
        "release_date": "2024-06-01",
        "variables": ["GDP_BY_INDUSTRY"]
      },
      {
        "agency": "Federal Reserve Economic Data",
        "dataset": "FRED",
        "dataset_id": "FRED_GDP_2020_2023",
        "release_date": "2024-01-31",
        "variables": ["GDP"]
      }
    ],
    "transforms": [
      "Normalized NAICS code: '0054' → '54'",
      "Calculated industry growth rates from BEA GDP by Industry",
      "Calculated GDP growth rates from FRED",
      "Computed impact multipliers (industry growth / GDP growth)",
      "Analyzed sensitivity to recession and expansion periods"
    ],
    "units": {
      "currency": "USD",
      "inflation_base_year": 2023,
      "geography": "us:*"
    },
    "methodology": "Industry macro effects calculated by comparing industry GDP growth to overall GDP growth, analyzing performance during recession and expansion periods, and computing sensitivity metrics."
  }
}

Error Codes: Same as get_regime_indicators, plus:

  • invalid_naics - Invalid NAICS code

Non-Goals:

  • Does NOT predict future industry effects
  • Does NOT provide company-specific effects

3. get_cost_pressures

Get cost pressure indicators (inflation, rates, margin risk) for a given time range.

Signature:

get_cost_pressures(
  year_range: { start_year: integer, end_year: integer }
) -> SuccessResponse | ErrorResponse

Input Parameters:

Parameter Type Required Description
year_range object Yes { start_year: integer, end_year: integer }

Success Response Data:

{
  "success": true,
  "data": {
    "current_inflation_pct": number,      // Current inflation rate
    "inflation_trend": string,            // "rising", "stable", "falling"
    "current_fed_rate_pct": number,      // Current federal funds rate
    "rate_trend": string,                 // "rising", "stable", "falling"
    "margin_pressure_score": number,      // Margin pressure score (0-100, higher = more pressure)
    "cost_indices": {                     // Cost component indices
      "labor_cost_index": number,         // Labor cost index (base year = 100)
      "materials_cost_index": number,     // Materials cost index
      "energy_cost_index": number         // Energy cost index
    },
    "yearly_pressures": [                 // Year-by-year breakdown
      {
        "year": integer,
        "inflation_pct": number,
        "fed_rate_pct": number,
        "margin_pressure_score": number
      }
    ],
    "year_range": {
      "start_year": integer,
      "end_year": integer
    }
  },
  "provenance": { /* ProvenanceEnvelope */ }
}

Example:

{
  "success": true,
  "data": {
    "current_inflation_pct": 3.2,
    "inflation_trend": "falling",
    "current_fed_rate_pct": 5.25,
    "rate_trend": "stable",
    "margin_pressure_score": 65.5,
    "cost_indices": {
      "labor_cost_index": 112.5,
      "materials_cost_index": 108.3,
      "energy_cost_index": 95.2
    },
    "yearly_pressures": [
      {
        "year": 2021,
        "inflation_pct": 4.7,
        "fed_rate_pct": 0.25,
        "margin_pressure_score": 45.0
      },
      {
        "year": 2022,
        "inflation_pct": 8.0,
        "fed_rate_pct": 4.25,
        "margin_pressure_score": 85.0
      },
      {
        "year": 2023,
        "inflation_pct": 3.2,
        "fed_rate_pct": 5.25,
        "margin_pressure_score": 65.5
      }
    ],
    "year_range": {
      "start_year": 2021,
      "end_year": 2023
    }
  },
  "provenance": {
    "sources": [
      {
        "agency": "Federal Reserve Economic Data",
        "dataset": "FRED",
        "dataset_id": "FRED_INFLATION_2021_2023",
        "release_date": "2024-01-31",
        "variables": ["CPIAUCSL", "FEDFUNDS"]
      },
      {
        "agency": "Bureau of Labor Statistics",
        "dataset": "PPI",
        "dataset_id": "PPI_2021_2023",
        "release_date": "2024-01-15",
        "variables": ["LABOR_COST", "MATERIALS_COST", "ENERGY_COST"]
      }
    ],
    "transforms": [
      "Calculated inflation rates from CPI",
      "Extracted federal funds rates",
      "Computed cost indices from PPI data",
      "Calculated margin pressure score from inflation and rate trends"
    ],
    "units": {
      "currency": "USD",
      "inflation_base_year": 2023,
      "geography": "us:*"
    },
    "methodology": "Cost pressures calculated by analyzing inflation trends, Federal Reserve policy (federal funds rate), and cost component indices (labor, materials, energy) from BLS Producer Price Index. Margin pressure score combines inflation and rate trends."
  }
}

Error Codes: Same as get_regime_indicators

Non-Goals:

  • Does NOT predict future cost pressures
  • Does NOT provide industry-specific cost pressures (use Industry Economics MCP)

Common Error Codes

Error Code Description HTTP Equivalent Retryable
data_not_available Data not available for year range 404 No
invalid_year_range Invalid year range 400 No
invalid_naics Invalid NAICS code 400 No
api_error Upstream API failure 502 Yes
computation_error Analysis computation failed 500 No

Versioning

  • Current Version: v1.0.0
  • Breaking Changes: New major version (e.g., v2.0.0)
  • New Features: New minor version (e.g., v1.1.0)
  • Bug Fixes: New patch version (e.g., v1.0.1)

References