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
| Name | Required | Description | Default |
|---|---|---|---|
| fleet_mpg_divisor | No | Agreed Fleet MPG Fuel Divisor (MPG). Contract standard heavy truck fuel economy. Default: 6.5. Min: 5. Max: 8. | |
| baseline_diesel_peg | No | Contract 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_miles | No | Shipment Distance (Miles) (miles). Billable highway route miles. Default: 780. Min: 20. Max: 3500. | |
| national_diesel_price | No | Current DOE Diesel Price ($/gal). Weekly EIA National Average Retail Diesel index. Default: 4.1. Min: 2. Max: 7. |