Skip to main content
Glama
Sign In
FreightUtils MCP Server

FreightUtils MCP Server

by SoapyRED
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

emissions_calculator

Read-onlyIdempotent

Calculate freight greenhouse-gas emissions (kgCO2e) per ISO 14083 from mass, distance and a published emission factor. Provide mass, distance_km and mode to estimate a shipment leg's CO2e.

Instructions

Estimate freight transport greenhouse-gas emissions (kgCO2e) for a shipment leg, per ISO 14083:2023 / GLEC Framework v3.2: emissions = mass x distance x a published emission-intensity factor (kgCO2e/tonne-km).

Provide mass + distance_km + mode (road | rail | sea | air | inland_waterway); optionally choose sub_mode, region/authority (uk = DEFRA, us = EPA, fr = ADEME) and basis (wtw default, or ttw). IMPORTANT: pass ACTUAL GROSS MASS, not chargeable/volumetric weight (a common air-freight mistake — see mass_basis in the result). Distance must be provided — this tool does NOT route, geocode, or compute distances.

Behavior: deterministic given the same factor edition; the fleet-average factor already includes average empty running (see empty_running) — do NOT add your own empty-return leg; sea and air are low-representativeness generic defaults (real emissions vary materially by vessel/aircraft, load factor and routing — see representativeness and the result summary). An unknown mode/sub_mode/region returns available:false with the covered options, never a fabricated factor. Rate-limited: a limit error carries reset_at, the UTC time the allowance resets.

Returns: well-to-wheel AND tank-to-wheel emissions where the factor has both, the exact factor used (value, authority, edition), the tonne-km activity and a per-result _source citing BOTH the ISO method and the specific published factor, all under result, plus confidence, _source and citation (the FreightUtils v1 response envelope).

Limitations: best-effort reference estimate from published factors (DEFRA / EPA / ADEME) — NOT a verified or audited carbon report.

Related: distinct from cbm_calculator / ldm_calculator / chargeable_weight_calculator (those size or bill a shipment; this one estimates its CO2e).

Input Schema

NameRequiredDescriptionDefault
massYesShipment mass, expressed in mass_unit. Example: 1000.
modeYesTransport mode.
basisNoEmissions basis: wtw = well-to-wheel incl. upstream (default), ttw = tank-to-wheel / operation only. When the factor publishes only the other basis the answer uses it and says so (basis_note, BASIS_SUBSTITUTED).
regionNoFactor source/region: uk = DEFRA, us = EPA, fr = ADEME. Default is per-mode.
sub_modeNoOptional sub-mode / vehicle class (e.g. "articulated", "container ship", "long-haul"). Omit for the representative default.
mass_unitNoUnit for mass. Default: kg.
distance_kmYesTransport distance in kilometres — you provide it; the tool does not route.

Output Schema

NameRequiredDescriptionDefault
okYes
_metaNo
as_ofNo
resultYes
statusNo
_sourceYes
editionNo
citationYes
validityNo
warningsNo
confidenceYes
missing_inputsNo
blocking_errorsNo
envelope_versionYes
normalized_inputNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changedv2.27.0
    • addedOutput schema / properties / _meta / properties / check_id
      Added value: +{
+  "type": "string"
+}
    • addedOutput schema / properties / _meta / properties / edition_basis
      Added value: +{
+  "type": "string"
+}
    • addedOutput schema / properties / _meta / properties / receipt
      Added value: +{
+  "additionalProperties": {},
+  "properties": {
+    "created_at": {
+      "type": "string"
+    },
+    "dataset_version": {
+      "additionalProperties": {
+        "type": "string"
+      },
+      "propertyNames": {
+        "type": "string"
+      },
+      "type": "object"
+    },
+    "engine_version": {
+      "type": "string"
+    },
+    "inputs": {},
+    "reason": {
+      "const": "key_required",
+      "type": "string"
+    },
+    "receipt_hash": {
+      "type": "string"
+    },
+    "result": {
+      "additionalProperties": {},
+      "propertyNames": {
+        "type": "string"
+      },
+      "type": "object"
+    },
+    "schema_version": {
+      "type": "string"
+    },
+    "stored": {
+      "const": false,
+      "type": "boolean"
+    },
+    "tool": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "stored",
+    "reason",
+    "schema_version",
+    "receipt_hash",
+    "created_at",
+    "tool",
+    "inputs",
+    "dataset_version",
+    "engine_version",
+    "result"
+  ],
+  "type": "object"
+}
    • addedOutput schema / properties / _meta / properties / receipt_url
      Added value: +{
+  "type": "string"
+}
  2. Changed10 schema fields changedv2.24.0
    • addedOutput schema / properties / _meta
      Added value: +{
+  "additionalProperties": {},
+  "properties": {
+    "identify": {
+      "type": "string"
+    }
+  },
+  "type": "object"
+}
    • addedOutput schema / properties / as_of
      Added value: +{
+  "type": "string"
+}
    • addedOutput schema / properties / blocking_errors / items / properties / recovery / properties / params / propertyNames
      Added value: +{
+  "type": "string"
+}
    • addedOutput schema / properties / edition
      Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": false,
+      "properties": {
+        "applies_from": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "may_apply_until": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "name": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "name",
+        "applies_from",
+        "may_apply_until"
+      ],
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ]
+}
    • changedOutput schema / properties / envelope_version / enum
      Previous value: -[
-  "1",
-  "1.1"
-]New value: +[
+  "1",
+  "1.1",
+  "1.2"
+]
    • addedOutput schema / properties / missing_inputs
      Added value: +{
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}
    • addedOutput schema / properties / normalized_input / propertyNames
      Added value: +{
+  "type": "string"
+}
    • changedOutput schema / properties / result / anyOf
      Previous value: -[
-  {
-    "additionalProperties": true,
-    "properties": {
-      "_source": {
-        "anyOf": [
-          {
-            "additionalProperties": {},
-            "type": "object"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "available": {
-        "type": [
-          "boolean",
-          "null"
-        ]
-      },
-      "available_for": {
-        "anyOf": [
-          {
-            "additionalProperties": {},
-            "type": "object"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "confidence": {
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "disclaimer": {
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "emissions": {
-        "anyOf": [
-          {
-            "additionalProperties": true,
-            "properties": {
-              "basis_used": {
-                "type": [
-                  "string",
-                  "null"
-                ]
-              },
-              "primary_kgco2e": {
-                "type": [
-                  "number",
-                  "null"
-                ]
-              },
-              "ttw_kgco2e": {
-                "type": [
-                  "number",
-                  "null"
-                ]
-              },
-              "wtw_kgco2e": {
-                "type": [
-                  "number",
-                  "null"
-                ]
-              }
-            },
-            "type": "object"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "empty_running": {
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "factor": {
-        "anyOf": [
-          {
-            "additionalProperties": true,
-            "properties": {
-              "authority": {
-                "type": [
-                  "string",
-                  "null"
-                ]
-              },
-              "edition": {
-                "type": [
-                  "string",
-                  "null"
-                ]
-              },
-              "id": {
-                "type": [
-                  "string",
-                  "null"
-                ]
-              },
-              "mode": {
-                "type": [
-                  "string",
-                  "null"
-                ]
-              },
-              "region": {
-                "type": [
-                  "string",
-                  "null"
-                ]
-              },
-              "sub_mode": {
-                "type": [
-                  "string",
-                  "null"
-                ]
-              },
-              "ttw": {
-                "type": [
-                  "number",
-                  "null"
-                ]
-              },
-              "unit": {
-                "type": [
-                  "string",
-                  "null"
-                ]
-              },
-              "wtw": {
-                "type": [
-                  "number",
-                  "null"
-                ]
-              }
-            },
-            "type": "object"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "inputs": {
-        "anyOf": [
-          {
-            "additionalProperties": {},
-            "type": "object"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "mass_basis": {
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "message": {
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "methodology": {
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "representativeness": {
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "summary": {
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "tonne_km": {
-        "type": [
-          "number",
-          "null"
-        ]
-      }
-    },
-    "type": "object"
-  },
-  {
-    "additionalProperties": {},
-    "type": "object"
-  }
-]New value: +[
+  {
+    "additionalProperties": {},
+    "properties": {
+      "_source": {
+        "anyOf": [
+          {
+            "additionalProperties": {},
+            "propertyNames": {
+              "type": "string"
+            },
+            "type": "object"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "available": {
+        "type": [
+          "boolean",
+          "null"
+        ]
+      },
+      "available_for": {
+        "anyOf": [
+          {
+            "additionalProperties": {},
+            "propertyNames": {
+              "type": "string"
+            },
+            "type": "object"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "confidence": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "disclaimer": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "emissions": {
+        "anyOf": [
+          {
+            "additionalProperties": {},
+            "properties": {
+              "basis_used": {
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "primary_kgco2e": {
+                "type": [
+                  "number",
+                  "null"
+                ]
+              },
+              "ttw_kgco2e": {
+                "type": [
+                  "number",
+                  "null"
+                ]
+              },
+              "wtw_kgco2e": {
+                "type": [
+                  "number",
+                  "null"
+                ]
+              }
+            },
+            "type": "object"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "empty_running": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "factor": {
+        "anyOf": [
+          {
+            "additionalProperties": {},
+            "properties": {
+              "authority": {
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "edition": {
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "id": {
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "mode": {
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "region": {
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "sub_mode": {
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "ttw": {
+                "type": [
+                  "number",
+                  "null"
+                ]
+              },
+              "unit": {
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "wtw": {
+                "type": [
+                  "number",
+                  "null"
+                ]
+              }
+            },
+            "type": "object"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "inputs": {
+        "anyOf": [
+          {
+            "additionalProperties": {},
+            "propertyNames": {
+              "type": "string"
+            },
+            "type": "object"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "mass_basis": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "message": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "methodology": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "representativeness": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "summary": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "tonne_km": {
+        "type": [
+          "number",
+          "null"
+        ]
+      }
+    },
+    "type": "object"
+  },
+  {
+    "additionalProperties": {},
+    "propertyNames": {
+      "type": "string"
+    },
+    "type": "object"
+  }
+]
    • addedOutput schema / properties / status
      Added value: +{
+  "enum": [
+    "ok",
+    "partial",
+    "not_found",
+    "unsupported",
+    "ambiguous"
+  ],
+  "type": "string"
+}
    • addedOutput schema / properties / warnings / items / properties / details / propertyNames
      Added value: +{
+  "type": "string"
+}
  3. Changed1 schema field changedv2.22.3
    • changedInput schema / properties / basis / description
      Previous value: -"Emissions basis: wtw = well-to-wheel incl. upstream (default), ttw = tank-to-wheel / operation only."New value: +"Emissions basis: wtw = well-to-wheel incl. upstream (default), ttw = tank-to-wheel / operation only. When the factor publishes only the other basis the answer uses it and says so (basis_note, BASIS_SUBSTITUTED)."
  4. Changed5 schema fields changedv2.17.2
    • addedOutput schema / properties / _source / properties / authority_current_edition
      Added value: +{
+  "type": "string"
+}
    • addedOutput schema / properties / _source / properties / checked_at
      Added value: +{
+  "type": "string"
+}
    • addedOutput schema / properties / _source / properties / dataset_edition
      Added value: +{
+  "type": "string"
+}
    • removedOutput schema / properties / envelope_version / const
      Removed value: -"1"
    • addedOutput schema / properties / envelope_version / enum
      Added value: +[
+  "1",
+  "1.1"
+]
  5. Changed40 schema fields changedv2.11.0
    • changedInput schema / properties / basis / description
      Previous value: -"Emissions basis: wtw = well-to-wheel incl. upstream (default), ttw = tank-to-wheel / operation only"New value: +"Emissions basis: wtw = well-to-wheel incl. upstream (default), ttw = tank-to-wheel / operation only."
    • changedInput schema / properties / distance_km / description
      Previous value: -"Transport distance in kilometres — you provide it; the tool does not route"New value: +"Transport distance in kilometres — you provide it; the tool does not route."
    • changedInput schema / properties / mass / description
      Previous value: -"Shipment mass, expressed in mass_unit. Example: 1000"New value: +"Shipment mass, expressed in mass_unit. Example: 1000."
    • changedInput schema / properties / mass_unit / description
      Previous value: -"Unit for mass (default: kg)"New value: +"Unit for mass. Default: kg."
    • changedInput schema / properties / mode / description
      Previous value: -"Transport mode"New value: +"Transport mode."
    • addedOutput schema / properties / _source / properties / checked
      Added value: +{
+  "type": "string"
+}
    • removedOutput schema / properties / _source / properties / computed_by
      Removed value: -{
-  "type": "string"
-}
    • removedOutput schema / properties / _source / properties / factor
      Removed value: -{
-  "additionalProperties": false,
-  "properties": {
-    "authority": {
-      "type": "string"
-    },
-    "basis": {
-      "type": "string"
-    },
-    "edition": {
-      "type": "string"
-    },
-    "last_verified": {
-      "type": "string"
-    },
-    "licence": {
-      "type": "string"
-    },
-    "source_url": {
-      "type": "string"
-    },
-    "unit": {
-      "type": "string"
-    },
-    "value": {
-      "type": "number"
-    }
-  },
-  "required": [
-    "authority",
-    "edition",
-    "value",
-    "unit",
-    "basis",
-    "last_verified",
-    "source_url",
-    "licence"
-  ],
-  "type": "object"
-}
    • addedOutput schema / properties / _source / properties / name
      Added value: +{
+  "type": "string"
+}
    • addedOutput schema / properties / _source / properties / provenance_status
      Added value: +{
+  "enum": [
+    "verified",
+    "pending-verification",
+    "computed",
+    "live"
+  ],
+  "type": "string"
+}
    • removedOutput schema / properties / _source / properties / reference
      Removed value: -{
-  "type": "string"
-}
    • removedOutput schema / properties / _source / properties / standard
      Removed value: -{
-  "type": "string"
-}
    • removedOutput schema / properties / _source / properties / type
      Removed value: -{
-  "type": "string"
-}
    • changedOutput schema / properties / _source / required
      Previous value: -[
-  "type",
-  "standard",
-  "reference",
-  "source_url",
-  "computed_by",
-  "factor"
-]New value: +[
+  "name",
+  "checked",
+  "provenance_status"
+]
    • removedOutput schema / properties / available
      Removed value: -{
-  "type": "boolean"
-}
    • removedOutput schema / properties / available_for
      Removed value: -{
-  "additionalProperties": false,
-  "properties": {
-    "modes": {
-      "items": {
-        "type": "string"
-      },
-      "type": "array"
-    },
-    "regions_for_mode": {
-      "items": {
-        "type": "string"
-      },
-      "type": "array"
-    },
-    "sub_modes": {
-      "items": {
-        "additionalProperties": false,
-        "properties": {
-          "id": {
-            "type": "string"
-          },
-          "region": {
-            "type": "string"
-          },
-          "sub_mode": {
-            "type": "string"
-          }
-        },
-        "required": [
-          "region",
-          "id",
-          "sub_mode"
-        ],
-        "type": "object"
-      },
-      "type": "array"
-    }
-  },
-  "required": [
-    "modes",
-    "regions_for_mode",
-    "sub_modes"
-  ],
-  "type": "object"
-}
    • addedOutput schema / properties / blocking_errors
      Added value: +{
+  "items": {
+    "additionalProperties": false,
+    "properties": {
+      "code": {
+        "type": "string"
+      },
+      "message": {
+        "type": "string"
+      },
+      "recovery": {
+        "additionalProperties": false,
+        "properties": {
+          "action": {
+            "type": "string"
+          },
+          "params": {
+            "additionalProperties": {},
+            "type": "object"
+          },
+          "tool": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "action"
+        ],
+        "type": "object"
+      }
+    },
+    "required": [
+      "code",
+      "message",
+      "recovery"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}
    • addedOutput schema / properties / citation
      Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "qualifier": {
+      "type": "string"
+    },
+    "text": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "text"
+  ],
+  "type": "object"
+}
    • addedOutput schema / properties / confidence / additionalProperties
      Added value: +false
    • addedOutput schema / properties / confidence / properties
      Added value: +{
+  "basis": {
+    "enum": [
+      "deterministic",
+      "provenance",
+      "match_quality",
+      "freshness"
+    ],
+    "type": "string"
+  },
+  "level": {
+    "enum": [
+      "high",
+      "medium",
+      "low"
+    ],
+    "type": "string"
+  },
+  "score": {
+    "maximum": 1,
+    "minimum": 0,
+    "type": "number"
+  }
+}
    • addedOutput schema / properties / confidence / required
      Added value: +[
+  "level",
+  "basis"
+]
    • changedOutput schema / properties / confidence / type
      Previous value: -"string"New value: +"object"
    • removedOutput schema / properties / disclaimer
      Removed value: -{
-  "type": "string"
-}
    • removedOutput schema / properties / emissions
      Removed value: -{
-  "additionalProperties": false,
-  "properties": {
-    "basis_used": {
-      "type": "string"
-    },
-    "primary_kgco2e": {
-      "type": "number"
-    },
-    "ttw_kgco2e": {
-      "type": [
-        "number",
-        "null"
-      ]
-    },
-    "wtw_kgco2e": {
-      "type": [
-        "number",
-        "null"
-      ]
-    }
-  },
-  "required": [
-    "wtw_kgco2e",
-    "ttw_kgco2e",
-    "primary_kgco2e",
-    "basis_used"
-  ],
-  "type": "object"
-}
    • removedOutput schema / properties / empty_running
      Removed value: -{
-  "type": "string"
-}
    • addedOutput schema / properties / envelope_version
      Added value: +{
+  "const": "1",
+  "type": "string"
+}
    • removedOutput schema / properties / factor
      Removed value: -{
-  "additionalProperties": false,
-  "properties": {
-    "authority": {
-      "type": "string"
-    },
-    "edition": {
-      "type": "string"
-    },
-    "id": {
-      "type": "string"
-    },
-    "mode": {
-      "type": "string"
-    },
-    "region": {
-      "type": "string"
-    },
-    "sub_mode": {
-      "type": "string"
-    },
-    "ttw": {
-      "type": [
-        "number",
-        "null"
-      ]
-    },
-    "unit": {
-      "type": "string"
-    },
-    "wtw": {
-      "type": [
-        "number",
-        "null"
-      ]
-    }
-  },
-  "required": [
-    "id",
-    "mode",
-    "sub_mode",
-    "authority",
-    "edition",
-    "region",
-    "unit",
-    "wtw",
-    "ttw"
-  ],
-  "type": "object"
-}
    • removedOutput schema / properties / inputs
      Removed value: -{
-  "additionalProperties": false,
-  "properties": {
-    "basis": {
-      "type": "string"
-    },
-    "distance_km": {
-      "type": "number"
-    },
-    "mass": {
-      "type": "number"
-    },
-    "mass_tonnes": {
-      "type": "number"
-    },
-    "mass_unit": {
-      "type": "string"
-    },
-    "mode": {
-      "type": "string"
-    },
-    "region": {
-      "type": "string"
-    },
-    "sub_mode": {
-      "type": "string"
-    }
-  },
-  "required": [
-    "mass",
-    "mass_unit",
-    "mass_tonnes",
-    "distance_km",
-    "mode",
-    "sub_mode",
-    "region",
-    "basis"
-  ],
-  "type": "object"
-}
    • removedOutput schema / properties / mass_basis
      Removed value: -{
-  "type": "string"
-}
    • removedOutput schema / properties / message
      Removed value: -{
-  "type": "string"
-}
    • removedOutput schema / properties / methodology
      Removed value: -{
-  "type": "string"
-}
    • addedOutput schema / properties / normalized_input
      Added value: +{
+  "additionalProperties": {},
+  "type": "object"
+}
    • addedOutput schema / properties / ok
      Added value: +{
+  "type": "boolean"
+}
    • removedOutput schema / properties / representativeness
      Removed value: -{
-  "type": "string"
-}
    • addedOutput schema / properties / result
      Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": true,
+      "properties": {
+        "_source": {
+          "anyOf": [
+            {
+              "additionalProperties": {},
+              "type": "object"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "available": {
+          "type": [
+            "boolean",
+            "null"
+          ]
+        },
+        "available_for": {
+          "anyOf": [
+            {
+              "additionalProperties": {},
+              "type": "object"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "confidence": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "disclaimer": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "emissions": {
+          "anyOf": [
+            {
+              "additionalProperties": true,
+              "properties": {
+                "basis_used": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                },
+                "primary_kgco2e": {
+                  "type": [
+                    "number",
+                    "null"
+                  ]
+                },
+                "ttw_kgco2e": {
+                  "type": [
+                    "number",
+                    "null"
+                  ]
+                },
+                "wtw_kgco2e": {
+                  "type": [
+                    "number",
+                    "null"
+                  ]
+                }
+              },
+              "type": "object"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "empty_running": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "factor": {
+          "anyOf": [
+            {
+              "additionalProperties": true,
+              "properties": {
+                "authority": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                },
+                "edition": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                },
+                "id": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                },
+                "mode": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                },
+                "region": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                },
+                "sub_mode": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                },
+                "ttw": {
+                  "type": [
+                    "number",
+                    "null"
+                  ]
+                },
+                "unit": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                },
+                "wtw": {
+                  "type": [
+                    "number",
+                    "null"
+                  ]
+                }
+              },
+              "type": "object"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "inputs": {
+          "anyOf": [
+            {
+              "additionalProperties": {},
+              "type": "object"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "mass_basis": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "message": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "methodology": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "representativeness": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "summary": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "tonne_km": {
+          "type": [
+            "number",
+            "null"
+          ]
+        }
+      },
+      "type": "object"
+    },
+    {
+      "additionalProperties": {},
+      "type": "object"
+    }
+  ]
+}
    • removedOutput schema / properties / summary
      Removed value: -{
-  "type": "string"
-}
    • removedOutput schema / properties / tonne_km
      Removed value: -{
-  "type": "number"
-}
    • addedOutput schema / properties / validity
      Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "as_of": {
+      "type": "string"
+    },
+    "effective_from": {
+      "type": "string"
+    },
+    "effective_to": {
+      "type": [
+        "string",
+        "null"
+      ]
+    }
+  },
+  "required": [
+    "as_of"
+  ],
+  "type": "object"
+}
    • addedOutput schema / properties / warnings
      Added value: +{
+  "items": {
+    "additionalProperties": false,
+    "properties": {
+      "code": {
+        "type": "string"
+      },
+      "details": {
+        "additionalProperties": {},
+        "type": "object"
+      },
+      "message": {
+        "type": "string"
+      }
+    },
+    "required": [
+      "code",
+      "message"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}
    • changedOutput schema / required
      Previous value: -[
-  "available",
-  "methodology",
-  "disclaimer"
-]New value: +[
+  "envelope_version",
+  "ok",
+  "result",
+  "confidence",
+  "_source",
+  "citation"
+]
  6. Changed7 schema fields changedv2.10.1
    • addedOutput schema / properties / _source / properties / factor / properties / last_verified
      Added value: +{
+  "type": "string"
+}
    • changedOutput schema / properties / _source / properties / factor / required
      Previous value: -[
-  "authority",
-  "edition",
-  "value",
-  "unit",
-  "basis",
-  "source_url",
-  "licence"
-]New value: +[
+  "authority",
+  "edition",
+  "value",
+  "unit",
+  "basis",
+  "last_verified",
+  "source_url",
+  "licence"
+]
    • addedOutput schema / properties / confidence
      Added value: +{
+  "type": "string"
+}
    • addedOutput schema / properties / empty_running
      Added value: +{
+  "type": "string"
+}
    • addedOutput schema / properties / mass_basis
      Added value: +{
+  "type": "string"
+}
    • addedOutput schema / properties / representativeness
      Added value: +{
+  "type": "string"
+}
    • addedOutput schema / properties / summary
      Added value: +{
+  "type": "string"
+}
  7. Addedv2.10.0

TDQS

A4.8/5.0
Behavior5/5

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

Annotations cover safety (readOnlyHint, idempotentHint, destructiveHint=false), and the description adds substantial context beyond them: determinism given a factor edition, empty-running already baked into the fleet-average factor, low representativeness of sea/air defaults, graceful failure ('returns available:false with the covered options, never a fabricated factor'), rate limiting with reset_at, and an explicit scope disclaimer ('NOT a verified or audited carbon report').

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?

Front-loaded with the formula and required inputs, then behavior, returns, limitations and siblings in a predictable order; every section is scannable. It is on the long side for a single tool, but nearly all sentences carry operational information rather than restating the schema.

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?

The tool is computationally simple but has real domain traps, and the description covers all of them: distance not computed, mass basis, no manual empty leg, factor substitution behavior, rate limiting, and result envelope contents. With an output schema and rich annotations present, nothing an agent needs to invoke it correctly is missing.

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?

Schema coverage is 100%, so the baseline would be 3, but the description adds genuinely new semantics: 'pass ACTUAL GROSS MASS, not chargeable/volumetric weight' with a pointer to mass_basis in the result, the region-to-authority mapping (uk=DEFRA, us=EPA, fr=ADEME), and basis defaulting to wtw. Only mass_unit and the sub_mode enumeration detail are left entirely to the schema.

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

Purpose5/5

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

Opens with a specific verb and resource: 'Estimate freight transport greenhouse-gas emissions (kgCO2e) for a shipment leg', and names the method standard. The closing 'Related' line explicitly distinguishes it from cbm_calculator / ldm_calculator / chargeable_weight_calculator, so an agent can route without opening other schemas.

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

Usage Guidelines5/5

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

States required inputs, names the alternative tools and the condition separating them ('those size or bill a shipment; this one estimates its CO2e'), and gives explicit exclusions: 'this tool does NOT route, geocode, or compute distances' and 'do NOT add your own empty-return leg'. The common air-freight mistake is called out pre-emptively.

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

Deploy Server

Other Tools