Sootcase freight CO2e

What-if: shipments now vs with changes

compare_scenario

Read-onlyIdempotent

Calculates the shipments as they are and with changes, with the same method (GLEC v3.3, ISO 14083), and returns both totals (TTW, WTT, WTW), the difference, per change how many shipments and legs it affected and the sources of its values, and per shipment notes. Changes: road_to_rail (defaults: road legs over 300 km, 30% of the cargo, from the EU Transport White Paper 2011; rail part over 100 km in a straight line, from Directive 92/106/EEC; road to and from the nearest rail terminal, each terminal handling at GLEC v3.3's intermodal terminal value), electrify (needs the user's kwh_per_tkm, a grid country and the source), fuel_switch (hvo, b100, biomethane, biomethane_lng, cng, lng for diesel trucks), load. Results are scenarios, not reported emissions: say so to the user.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "shipments": "<shipments>",
      "plan": "<plan>"
    },
    "name": "compare_scenario"
  }
}

Input Schema

Name	Required	Description
`plan`	Yes
`shipments`	Yes	The shipments. Without an API key the public service takes up to 100 per call; with one, up to 10,000.
`add_road_legs`	No	Add road legs where the legs don't join up (gaps over 5 km), and to a port or terminal when a sea, rail or river leg starts or ends off its network (default true). Added legs are marked in the result.

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedOct 30, 2026

addedInput schema / properties / shipments / items / properties / legs / items / properties / fuel / properties / factor

Added value: +{
+  "additionalProperties": false,
+  "description": "The fuel supplier's own emission factor, instead of the dataset's (fuel is then just its name).",
+  "properties": {
+    "biogenic_co2_kg_per_unit": {
+      "description": "Biogenic CO2 per unit, reported apart (optional)",
+      "type": "number"
+    },
+    "source": {
+      "description": "Who gives the factor, and for what",
+      "type": "string"
+    },
+    "ttw_kg_per_unit": {
+      "description": "Tank-to-wheel kg CO2e per unit (part of WTW)",
+      "type": "number"
+    },
+    "unit": {
+      "description": "Unit of amount, e.g. l, kg, kWh",
+      "type": "string"
+    },
+    "wtw_kg_per_unit": {
+      "description": "Well-to-wheel kg CO2e per unit",
+      "type": "number"
+    }
+  },
+  "required": [
+    "unit",
+    "wtw_kg_per_unit",
+    "source"
+  ],
+  "type": "object"
+}

addedInput schema / properties / shipments / items / properties / legs / items / properties / own_factor

Added value: +{
+  "additionalProperties": false,
+  "description": "The carrier's or the user's own intensity for this leg (primary data), instead of a default value. Only with a figure the user gave; never estimate one.",
+  "properties": {
+    "distance_basis": {
+      "description": "Distance type the intensity is per tonne-km of; leave out if it matches the leg's",
+      "enum": [
+        "sfd",
+        "gcd",
+        "actual"
+      ],
+      "type": "string"
+    },
+    "source": {
+      "description": "Who measured it, and for what (e.g. the carrier's report and year)",
+      "type": "string"
+    },
+    "ttw_g_per_tkm": {
+      "description": "Tank-to-wheel g CO2e per tonne-km (part of WTW)",
+      "type": "number"
+    },
+    "wtw_g_per_tkm": {
+      "description": "Well-to-wheel g CO2e per tonne-km",
+      "type": "number"
+    }
+  },
+  "required": [
+    "wtw_g_per_tkm",
+    "source"
+  ],
+  "type": "object"
+}

changedInput schema / properties / shipments / items / properties / legs / items / required
```
Previous value: -[
-  "mode",
-  "vehicle_type"
-]New value: +[
+  "mode"
+]
```

Changed1 schema field changedOct 29, 2026

addedInput schema / properties / shipments / items / properties / cargo_type

Added value: +{
+  "description": "Optional, GLEC v3.3 cargo or load category: container, temperature_controlled, light, heavy, or for European rail cars, chemicals, coal_steel, building_materials, manufactured_products, cereals, truck_trailer_on_train, trailer_on_train. Picks GLEC's value for it where GLEC has one for the leg's vehicle; otherwise the vehicle's own value (the leg's note says which).",
+  "type": "string"
+}

Changed2 schema fields changedOct 29, 2026

changedInput schema / properties / shipments / items / properties / hubs / description

Previous value: -"Hub stops: hub_type transshipment, storage_transshipment, warehouse or liquid_bulk_terminal (add _mixed for ambient and temperature-controlled sites); GLEC v3.3 Table 3 values per tonne."New value: +"Hub stops: hub_type transshipment, storage_transshipment, warehouse or liquid_bulk_terminal (add _mixed for ambient and temperature-controlled sites), per tonne; intermodal_terminal or intermodal_terminal_temperature_controlled, per container (give containers). GLEC v3.3 Table 3."

addedInput schema / properties / shipments / items / properties / hubs / items / properties / containers

Added value: +{
+  "description": "Containers handled, for intermodal terminals",
+  "type": "number"
+}

Changed1 schema field changedOct 29, 2026

changedInput schema / properties / shipments / items / properties / hubs / description

Previous value: -"Hub stops (transhipment, storage); needs a dataset with hub factors."New value: +"Hub stops: hub_type transshipment, storage_transshipment, warehouse or liquid_bulk_terminal (add _mixed for ambient and temperature-controlled sites); GLEC v3.3 Table 3 values per tonne."

Changed1 schema field changedOct 28, 2026

addedInput schema / properties / shipments / items / properties / legs / items / properties / repositioning_km

Added value: +{
+  "description": "Trucks: km driven empty for this trip (to the pickup or back), shared over the truck's load like empty running. Without a load, the shipment is taken as the whole load.",
+  "type": "number"
+}

Changed1 schema field changedOct 24, 2026

addedInput schema / properties / plan / properties / changes / items / properties / terminal

Added value: +{
+  "description": "road_to_rail: nearest rail terminal reachable by road (default, Directive 92/106/EEC) or the best trip among the nearest",
+  "enum": [
+    "nearest",
+    "best_trip"
+  ],
+  "type": "string"
+}

AddedOct 24, 2026

TDQS

A4.1/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description adds substantial behavior beyond the read-only and idempotent annotations: it explains the calculation method, the returned totals (TTW, WTT, WTW), the difference, per-change affected shipments and legs, value sources, and per-shipment notes. It also warns that outputs are scenarios, not reported emissions, which is important behavioral context for the agent.

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 description is front-loaded with the tool's purpose and return shape, and most of its dense detail is justified by the complexity of the scenario changes. It is still a long run-on paragraph, especially around road_to_rail defaults, so structure could be improved.

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?

Given the tool's complexity, the rich nested input schema, and the absence of an output schema, the description is complete enough to call the tool correctly. It explains the calculation basis, result shape, scenario caveat, and supported change types.

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?

The schema already documents many nested fields at roughly 67% coverage, but the description adds meaningful semantics for the change types, including defaults and provenance for road_to_rail, required user inputs for electrify, permitted fuel_switch fuels, and the load change. It does not document every nested shipment field, but it compensates well for the most decision-relevant scenario parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: it calculates shipments as they are and with scenario changes, then returns both totals and the difference. It is clearly a comparison/what-if tool, but it does not explicitly differentiate itself from sibling tools such as calculate_shipments or emissions_report.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied by the what-if framing and the list of supported changes, and the description adds an important caveat that results are scenarios rather than reported emissions. However, it does not explicitly say when to use this tool instead of calculate_shipments, calculate_shipment, or emissions_report.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All Sootcase freight CO2e 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?