Industry Economics MCP: Tool Contracts

Industry Economics MCP: Tool Contracts

This document defines the API contracts for Industry Economics MCP tools. All tools consume raw data from Core Government Data MCP and produce profitability, cost structure, and cyclicality insights.

Common Input Types

See Market Structure MCP Contracts for NAICS, Geography, Year, and Year Range definitions.

Common Output Types

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

Tool Contracts

1. get_profitability_benchmarks

Get profitability benchmarks (margins) for a given industry and geography.

Signature:

get_profitability_benchmarks(
  naics: string,
  geography: string,
  year: integer
) -> SuccessResponse | ErrorResponse

Input Parameters:

Parameter Type Required Description
naics string Yes NAICS code (2-6 digits)
geography string Yes Geography code
year integer Yes Year (4-digit)

Success Response Data:

{
  "success": true,
  "data": {
    "gross_margin_pct": number,        // Gross margin percentage (0-100)
    "operating_margin_pct": number,    // Operating margin percentage (0-100)
    "net_margin_pct": number,          // Net margin percentage (0-100)
    "revenue_usd": number,              // Total revenue in USD
    "cost_of_goods_sold_usd": number,  // COGS in USD
    "operating_expenses_usd": number,  // Operating expenses in USD
    "net_income_usd": number,          // Net income in USD
    "naics": string,
    "geography": string,
    "year": integer
  },
  "provenance": { /* ProvenanceEnvelope */ }
}

Example:

{
  "success": true,
  "data": {
    "gross_margin_pct": 45.2,
    "operating_margin_pct": 12.8,
    "net_margin_pct": 8.5,
    "revenue_usd": 1250000000000,
    "cost_of_goods_sold_usd": 685000000000,
    "operating_expenses_usd": 790000000000,
    "net_income_usd": 106250000000,
    "naics": "54",
    "geography": "us:*",
    "year": 2023
  },
  "provenance": {
    "sources": [
      {
        "agency": "Bureau of Economic Analysis",
        "dataset": "GDP by Industry",
        "dataset_id": "GDP_IND_2023",
        "release_date": "2024-06-01",
        "variables": ["GDP", "PROFITS"]
      },
      {
        "agency": "IRS",
        "dataset": "SOI",
        "dataset_id": "SOI_2023",
        "release_date": "2024-09-15",
        "variables": ["REVENUE", "COGS", "OPEXP", "NET_INCOME"]
      }
    ],
    "transforms": [
      "Normalized NAICS code: '0054' → '54'",
      "Joined BEA GDP data with IRS SOI income data",
      "Calculated margins from revenue and cost components"
    ],
    "units": {
      "currency": "USD",
      "inflation_base_year": 2023,
      "geography": "us:*"
    },
    "methodology": "Profitability benchmarks calculated by joining BEA industry GDP data with IRS SOI corporate/partnership income data by sector, then computing gross, operating, and net margins."
  }
}

Error Codes:

  • data_not_available - Data not available for this NAICS/geography/year
  • invalid_naics - Invalid NAICS code
  • invalid_geography - Invalid geography code
  • invalid_year - Year outside dataset range
  • api_error - Upstream API failure

Non-Goals:

  • Does NOT compare profitability across industries (use multiple calls)
  • Does NOT forecast future profitability
  • Does NOT adjust for company-specific factors

2. get_cost_structure

Get cost structure breakdown (labor, materials, overhead) for a given industry and geography.

Signature:

get_cost_structure(
  naics: string,
  geography: string,
  year: integer
) -> SuccessResponse | ErrorResponse

Input Parameters:

Parameter Type Required Description
naics string Yes NAICS code (2-6 digits)
geography string Yes Geography code
year integer Yes Year (4-digit)

Success Response Data:

{
  "success": true,
  "data": {
    "cost_mix": {
      "labor_pct": number,        // Labor cost percentage (0-100)
      "materials_pct": number,    // Materials cost percentage (0-100)
      "overhead_pct": number,     // Overhead cost percentage (0-100)
      "other_pct": number         // Other costs percentage (0-100)
    },
    "total_costs_usd": number,    // Total costs in USD
    "labor_costs_usd": number,     // Labor costs in USD
    "materials_costs_usd": number, // Materials costs in USD
    "overhead_costs_usd": number, // Overhead costs in USD
    "naics": string,
    "geography": string,
    "year": integer
  },
  "provenance": { /* ProvenanceEnvelope */ }
}

Example:

{
  "success": true,
  "data": {
    "cost_mix": {
      "labor_pct": 45.2,
      "materials_pct": 28.5,
      "overhead_pct": 18.3,
      "other_pct": 8.0
    },
    "total_costs_usd": 1143750000000,
    "labor_costs_usd": 517000000000,
    "materials_costs_usd": 326000000000,
    "overhead_costs_usd": 209000000000,
    "naics": "54",
    "geography": "us:*",
    "year": 2023
  },
  "provenance": {
    "sources": [
      {
        "agency": "Bureau of Economic Analysis",
        "dataset": "Input-Output Tables",
        "dataset_id": "IO_2023",
        "release_date": "2024-12-01",
        "variables": ["LABOR", "MATERIALS", "OVERHEAD"]
      },
      {
        "agency": "Bureau of Labor Statistics",
        "dataset": "PPI",
        "dataset_id": "PPI_2023",
        "release_date": "2024-01-15",
        "variables": ["COST_INDICES"]
      }
    ],
    "transforms": [
      "Normalized NAICS code: '0054' → '54'",
      "Extracted cost components from BEA IO tables",
      "Adjusted for inflation using BLS PPI indices",
      "Calculated cost mix percentages"
    ],
    "units": {
      "currency": "USD",
      "inflation_base_year": 2023,
      "geography": "us:*"
    },
    "methodology": "Cost structure calculated from BEA Input-Output tables, which provide detailed breakdown of cost components (labor, materials, overhead) by industry. Costs adjusted for inflation using BLS Producer Price Index."
  }
}

Error Codes: Same as get_profitability_benchmarks

Non-Goals:

  • Does NOT provide company-specific cost breakdowns
  • Does NOT forecast cost changes

3. get_cyclicality_indicators

Get cyclicality indicators (volatility, correlation with GDP, recession sensitivity) for a given industry over a time range.

Signature:

get_cyclicality_indicators(
  naics: string,
  geography: 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)
geography string Yes Geography code
year_range object Yes { start_year: integer, end_year: integer }

Success Response Data:

{
  "success": true,
  "data": {
    "volatility": number,              // Revenue volatility (coefficient of variation)
    "gdp_correlation": number,         // Correlation with GDP growth (-1 to 1)
    "recession_sensitivity": number,    // Recession sensitivity score (0-100)
    "cyclicality_score": number,       // Overall cyclicality score (0-100, higher = more cyclical)
    "revenue_trend": string,           // "growing", "stable", "declining"
    "yearly_data": [                   // Year-by-year breakdown
      {
        "year": integer,
        "revenue_usd": number,
        "revenue_growth_pct": number,
        "gdp_growth_pct": number
      }
    ],
    "naics": string,
    "geography": string,
    "year_range": {
      "start_year": integer,
      "end_year": integer
    }
  },
  "provenance": { /* ProvenanceEnvelope */ }
}

Example:

{
  "success": true,
  "data": {
    "volatility": 0.15,
    "gdp_correlation": 0.72,
    "recession_sensitivity": 65.5,
    "cyclicality_score": 68.2,
    "revenue_trend": "growing",
    "yearly_data": [
      {
        "year": 2020,
        "revenue_usd": 1100000000000,
        "revenue_growth_pct": -5.2,
        "gdp_growth_pct": -3.4
      },
      {
        "year": 2021,
        "revenue_usd": 1150000000000,
        "revenue_growth_pct": 4.5,
        "gdp_growth_pct": 5.7
      },
      {
        "year": 2022,
        "revenue_usd": 1200000000000,
        "revenue_growth_pct": 4.3,
        "gdp_growth_pct": 2.1
      },
      {
        "year": 2023,
        "revenue_usd": 1250000000000,
        "revenue_growth_pct": 4.2,
        "gdp_growth_pct": 2.5
      }
    ],
    "naics": "54",
    "geography": "us:*",
    "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", "REVENUE"]
      },
      {
        "agency": "Federal Reserve Economic Data",
        "dataset": "FRED",
        "dataset_id": "FRED_GDP_2020_2023",
        "release_date": "2024-01-31",
        "variables": ["GDP_GROWTH"]
      }
    ],
    "transforms": [
      "Normalized NAICS code: '0054' → '54'",
      "Calculated revenue volatility (coefficient of variation)",
      "Calculated correlation with GDP growth",
      "Analyzed recession sensitivity from 2020 data",
      "Computed cyclicality score from multiple indicators"
    ],
    "units": {
      "currency": "USD",
      "inflation_base_year": 2023,
      "geography": "us:*"
    },
    "methodology": "Cyclicality indicators calculated by analyzing revenue volatility, correlation with GDP growth, and sensitivity to recession periods (e.g., 2020 COVID-19 recession) over the specified year range."
  }
}

Error Codes: Same as get_profitability_benchmarks, plus:

  • invalid_year_range - Invalid year range

Non-Goals:

  • Does NOT forecast future cyclicality
  • Does NOT predict recessions

Common Error Codes

Error Code Description HTTP Equivalent Retryable
data_not_available Data suppressed or not available 404 No
invalid_naics Invalid NAICS code 400 No
invalid_geography Invalid geography code 400 No
invalid_year Year outside dataset range 400 No
invalid_year_range Invalid year range 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