Skip to main content
Glama
omnioperand-mcp

omnioperand-mcp

omni_freight_fuel_surcharge

Calculates carrier fuel surcharge percentages and per-mile amounts from the national diesel price peg and contract baseline, returning trip totals and effective surcharge rates.

Instructions

Freight Fuel Surcharge (FSC) Sliding Scale Calculator. Calculate carrier fuel surcharge percentage and per-mile surcharge amounts based on the National Average Diesel Fuel Price peg. Discipline: LOGISTICS. Governing mathematical model / formula: FSC ($/mile) = max(0, Current Diesel - Baseline Fuel Peg) / Fleet Baseline MPG.

USAGE GUIDELINES:

  • WHEN TO USE: Invoke for deterministic calculation of fuel_surcharge_per_mile (Fuel Surcharge Per Mile), total_trip_fsc (Total Fuel Surcharge Owed), effective_fsc_pct (Equivalent Percentage Surcharge), diesel_spread (Diesel Fuel Spread vs Base) using national_diesel_price (Current DOE Diesel Price ($/gal)), baseline_diesel_peg (Contract Baseline Fuel Peg ($/gal)), fleet_mpg_divisor (Agreed Fleet MPG Fuel Divisor in MPG), shipment_trip_miles (Shipment Distance (Miles) in miles). Guarantees exact machine floating-point precision, eliminating LLM arithmetic mistakes and formula hallucinations.

  • WHEN NOT TO USE: Do not use for qualitative evaluations or unquantified reasoning. All input parameters must be valid numerical values.

DISAMBIGUATION & BOUNDARIES:

  • Use this dedicated specialist tool for 'Freight Fuel Surcharge (FSC) Sliding Scale Calculator' rather than generic dispatchers like omni_universal_query.

  • For multi-calculation chained jobs, use 'omni_batch_calculate'.

  • To inspect schema fields, see 'omni_describe_solver'.

BEHAVIOR & SAFETY:

  • Pure deterministic computation with machine floating-point precision.

  • Read-only, idempotent, and stateless. Zero side effects or persistent state mutations.

  • Input validation: All arguments are validated against physical and domain bounds. Out-of-bounds inputs return a safe diagnostic error status without throwing runtime exceptions.

RETURNS:

  • Structured JSON object containing:

    • status (string): "success" on valid execution or "error" if validation fails

    • calculator (string): "freight-fuel-surcharge"

    • category (string): "logistics"

    • name (string): "Freight Fuel Surcharge (FSC) Sliding Scale Calculator"

    • formula (string): Governing mathematical formula string

    • inputs (object): Echoed input parameter dictionary with applied defaults

    • metrics (object): Dictionary of computed outputs:

      • metrics.fuel_surcharge_per_mile (Fuel Surcharge Per Mile): Formatted display string (e.g. '$0.246 / mile')

      • metrics.total_trip_fsc (Total Fuel Surcharge Owed): Formatted display string (e.g. '$191.88')

      • metrics.effective_fsc_pct (Equivalent Percentage Surcharge): Formatted display string (e.g. '14.2% Above Linehaul')

      • metrics.diesel_spread (Diesel Fuel Spread vs Base): Formatted display string (e.g. '+$1.60 / gal')

    • execution_time_ms (number): Latency in milliseconds.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "omni_freight_fuel_surcharge"
  }
}

Input Schema

NameRequiredDescriptionDefault
fleet_mpg_divisorNoAgreed Fleet MPG Fuel Divisor (MPG). Contract standard heavy truck fuel economy. Default: 6.5. Min: 5. Max: 8.
baseline_diesel_pegNoContract Baseline Fuel Peg ($/gal). Contract base rate price peg (typically $2.50 or $1.25). Default: 2.5. Min: 1.5. Max: 3.5.
shipment_trip_milesNoShipment Distance (Miles) (miles). Billable highway route miles. Default: 780. Min: 20. Max: 3500.
national_diesel_priceNoCurrent DOE Diesel Price ($/gal). Weekly EIA National Average Retail Diesel index. Default: 4.1. Min: 2. Max: 7.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv0.1.2

TDQS

Score is being calculated.

Deploy Server

Other Tools