Skip to main content
Glama
Sign In

Sootcase freight CO2e

by io.github.majidkabir
OverviewDiscussionsAdmin

Calculate a shipment's emissions

calculate_shipment
Read-onlyIdempotent

Calculates one shipment's greenhouse gas emissions (kg CO2e: well-to-wheel, tank-to-wheel, well-to-tank) following the GLEC Framework v3.3 and ISO 14083. Routes each leg's distance from its coordinates or codes. Returns the result per leg (distance and how it was found, method, data type, emission factor and its source, distance adjustment, notes on legs Sootcase added) and a step-by-step calculation sheet with the arithmetic and the GLEC page and ISO 14083 clause behind each step.

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": {
      "legs": "<legs>"
    },
    "name": "calculate_shipment"
  }
}

Input Schema

NameRequiredDescriptionDefault
idNoYour reference for the shipment
teuNoContainers in TEU, instead of weight_kg; with teu_net_tonnes, or alone for GLEC's average of 10 t per TEU
hubsNoHub 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.
legsYesThe legs in order, from where the shipper hands the goods over to where the consignee receives them.
weight_kgNoCargo weight in kg (or give teu instead)
cargo_typeNoOptional, 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).
add_road_legsNoAdd 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.
container_loadNoWith teu, instead of teu_net_tonnes: average (10 t), light (6 t) or heavy (14.5 t) per TEU, from the GLEC Framework
teu_net_tonnesNoWith teu: net cargo tonnes per TEU (container tare is not added)

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • addedInput schema / properties / legs / items / properties / cargo_type
      Added value: +{
+  "description": "Optional: this leg's GLEC cargo category, instead of the shipment's (same values as the shipment's cargo_type)",
+  "type": "string"
+}
  2. Changed4 schema fields changed
    • changedInput schema / properties / legs / items / properties / fuel / properties / factor / properties / ttw_kg_per_unit / description
      Previous value: -"Tank-to-wheel kg CO2e per unit (part of WTW)"New value: +"Tank-to-wheel kg CO2e per unit (part of WTW; 0 only for electricity). Required: ask the user if missing"
    • changedInput schema / properties / legs / items / properties / fuel / properties / factor / required
      Previous value: -[
-  "unit",
-  "wtw_kg_per_unit",
-  "source"
-]New value: +[
+  "unit",
+  "wtw_kg_per_unit",
+  "ttw_kg_per_unit",
+  "source"
+]
    • changedInput schema / properties / legs / items / properties / own_factor / properties / ttw_g_per_tkm / description
      Previous value: -"Tank-to-wheel g CO2e per tonne-km (part of WTW)"New value: +"Tank-to-wheel g CO2e per tonne-km (part of WTW; 0 only when no fuel is burnt in the vehicle, e.g. electric). Required: ask the user if missing"
    • changedInput schema / properties / legs / items / properties / own_factor / required
      Previous value: -[
-  "wtw_g_per_tkm",
-  "source"
-]New value: +[
+  "wtw_g_per_tkm",
+  "ttw_g_per_tkm",
+  "source"
+]
  3. Changed3 schema fields changed
    • addedInput schema / 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 / 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 / legs / items / required
      Previous value: -[
-  "mode",
-  "vehicle_type"
-]New value: +[
+  "mode"
+]
  4. Changed1 schema field changed
    • addedInput schema / 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"
+}
  5. Changed2 schema fields changed
    • changedInput schema / 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 / hubs / items / properties / containers
      Added value: +{
+  "description": "Containers handled, for intermodal terminals",
+  "type": "number"
+}
  6. Changed1 schema field changed
    • changedInput schema / 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."
  7. Changed1 schema field changed
    • addedInput schema / 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"
+}
  8. Changed2 schema fields changed
    • changedInput schema / properties / container_load / description
      Previous value: -"With teu: a container load profile defined by the dataset, instead of teu_net_tonnes"New value: +"With teu, instead of teu_net_tonnes: average (10 t), light (6 t) or heavy (14.5 t) per TEU, from the GLEC Framework"
    • changedInput schema / properties / teu / description
      Previous value: -"Containers in TEU, instead of weight_kg; needs teu_net_tonnes"New value: +"Containers in TEU, instead of weight_kg; with teu_net_tonnes, or alone for GLEC's average of 10 t per TEU"
  9. First observed

TDQS

A3.5/5.0
Behavior4/5

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

Annotations already cover the safety profile (readOnly, idempotent, closed-world), and the description meaningfully adds behavior: it discloses that distances are routed per leg from coordinates/codes, that a DAF is applied, that 'Sootcase-added' legs are flagged, and exactly what the per-leg output and calculation sheet contain. It does not mention the default-on add_road_legs gap-filling (only present in the schema), which keeps it short of a 5.

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?

Three sentences, front-loaded with purpose, then routing behavior, then return shape — every sentence earns its place. The parenthetical units and the long list of returned fields make the final sentence dense, slightly hurting scanability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 9-parameter tool with a nested legs array and no output schema, the description does the heavy lifting on return values (per-leg results plus a step-by-step sheet with standards citations) and on methodology. What remains missing is selection guidance against sibling calculation and reporting tools.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% with deeply documented nested properties, so the schema already carries parameter meaning and the baseline is 3. The description adds only marginal semantics — that distance routing uses coordinates or codes and that a DAF depends on distance basis — without explaining the interplay of fuel vs own_factor vs defaults.

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?

States a specific verb and resource ('Calculates one shipment's greenhouse gas emissions') with the quantities and standards involved (kg CO2e, WTW/TTW/WTT, GLEC v3.3, ISO 14083). The word 'one' implicitly distinguishes it from the plural sibling calculate_shipments, but no sibling is named, so the differentiation is weaker than a 5 requires.

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

Usage Guidelines2/5

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

The description gives no explicit when-to-use guidance: it never says when to prefer this over calculate_shipments, compare_scenario, or emissions_report. Prerequisite tooling (find_places, list_vehicle_types) is only referenced inside the schema, not in the description, so an agent must infer routing from parameter descriptions.

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 toolsInspect
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