FreightUtils MCP Server

Consignment Calculator

consignment_calculator

Read-onlyIdempotent

Calculate per-line and grand totals for a multi-item mixed consignment: CBM, loading metres (LDM), volumetric weight, and the mode-specific chargeable figure (air chargeable weight, sea revenue tonnes, road LDM), plus objective advisory flags.

Provide mode (sea | air | road, default road) and either lines[] (canonical — per line: quantity, dims {l,w,h,unit}, weight {value,unit}, optional description / hs_code / un_number / stackable) or the legacy flat items[] (dimensions in cm, weight in kg). Air uses an IATA volumetric divisor (default 6000, settable via options.air_volumetric_divisor); options.container_number / options.awb_number add a check-digit sanity flag.

Behavior: deterministic; flags are advisory only — implausible density, mode/option mismatch, dangerous-goods presence by UN number against ADR 2025, and container/AWB check-digit validity — and never state that a shipment is permitted or compliant. Invalid lines error naming the offending field. Canonical schema: https://www.freightutils.com/schema/consignment.v1.json. Rate-limited: a limit error carries reset_at, the UTC time the allowance resets.

Returns: schema_version, mode, per_line[] (cbm, gross_weight_kg, density, volumetric_weight_kg, ldm, revenue_tonnes, chargeable_weight_kg), totals (incl. billing_basis) and flags[] under result, plus confidence, _source and citation (the FreightUtils v1 response envelope).

Editions: edition ("2025" | "2027") and as_of (YYYY-MM-DD) choose the ADR edition — edition wins, else the date picks it (ADR 2025 before 2027-01-01, ADR 2027 from then; ADR 2025 may still be applied until 2027-06-30). An answer on a named edition carries adr_edition; neither sent, the answer is ADR 2025 until 2027-01-01.

Limitations: best-effort deterministic calculation and reference data — not regulatory, customs or dangerous-goods compliance advice; classification, documentation and carrier acceptance remain your responsibility.

Related: cbm_calculator / chargeable_weight_calculator / ldm_calculator (single-figure versions), shipment_summary (adds vehicle/container suggestion and duty estimates), adr_lookup (what a flagged UN number is).

Input Schema

Name	Required	Description
`mode`	No	Transport mode: sea \| air \| road (default road). Selects the chargeable-weight basis.
`as_of`	No	YYYY-MM-DD the answer is for (default today, UTC); picks the ADR edition when edition is omitted, and is echoed in the answer and its check receipt.
`items`	No	Deprecated flat alias — dimensions in cm, weight in kg. Prefer "lines". Provide lines OR items.
`lines`	No	Canonical consignment lines (preferred). Each: { quantity, dims:{l,w,h,unit}, weight:{value,unit}, optional description / hs_code / un_number / stackable }.
`edition`	No	ADR edition: "2025" or "2027". Wins over as_of. Omit it and as_of picks the edition by the legal timeline: before 2027-01-01 ADR 2025; from 2027-01-01 ADR 2027 (ADR 2025 may still be applied until 2027-06-30 under 1.6.1.1 — edition "2025" answers on it until then); from 2027-07-01 ADR 2027 only. An ADR 2027 answer for a date before 2027-01-01 carries an EDITION_NOT_YET_APPLICABLE warning.
`options`	No	Optional: { air_volumetric_divisor, container_number, awb_number }.
`consignment`	No	Alternative to the other arguments: the consignment object (https://www.freightutils.com/schema/consignment-object.v1.json) — lines[] (description, un_number, packing_group, variant_index, quantity {value, unit, basis}, packages {count, type, gross_kg, un_mark}, hs_code, value {amount, currency}, dims, stackable, icao_limited_quantity, inner_packaging), journey {origin, destination, date, tunnels_on_route, mode}, vehicle, crew, options. Send it alone; an input the tool needs and the object lacks comes back in missing_inputs.

Output Schema

Name	Required	Description	Default
`ok`	Yes
`_meta`	No
`as_of`	No
`result`	Yes
`status`	No
`_source`	Yes
`edition`	No
`citation`	Yes
`validity`	No
`warnings`	No
`confidence`	Yes
`missing_inputs`	No
`blocking_errors`	No
`envelope_version`	Yes
`normalized_input`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedNov 6, 2026

addedOutput schema / properties / _meta / properties / upstream

Added value: +{
+  "additionalProperties": {},
+  "properties": {
+    "datasets": {
+      "additionalProperties": {
+        "additionalProperties": {},
+        "properties": {
+          "kind": {
+            "anyOf": [
+              {
+                "enum": [
+                  "watched",
+                  "checksum-only",
+                  "manual"
+                ],
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "last_success": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "reason": {
+            "type": "string"
+          },
+          "stale": {
+            "type": "boolean"
+          },
+          "state": {
+            "enum": [
+              "in_step",
+              "changed_upstream",
+              "schema_drift",
+              "unreachable",
+              "window_missed",
+              "unknown"
+            ],
+            "type": "string"
+          },
+          "window_days": {
+            "type": [
+              "number",
+              "null"
+            ]
+          }
+        },
+        "required": [
+          "state",
+          "kind",
+          "last_success",
+          "window_days",
+          "stale"
+        ],
+        "type": "object"
+      },
+      "propertyNames": {
+        "type": "string"
+      },
+      "type": "object"
+    },
+    "stale": {
+      "type": "boolean"
+    },
+    "state": {
+      "enum": [
+        "in_step",
+        "changed_upstream",
+        "schema_drift",
+        "unreachable",
+        "window_missed",
+        "unknown"
+      ],
+      "type": "string"
+    },
+    "state_read_at": {
+      "type": [
+        "string",
+        "null"
+      ]
+    }
+  },
+  "required": [
+    "state",
+    "stale",
+    "state_read_at",
+    "datasets"
+  ],
+  "type": "object"
+}

Changed1 schema field changedNov 6, 2026

addedOutput schema / properties / _meta / properties / ids

Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "pattern": {
+      "type": "string"
+    },
+    "scheme": {
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    }
+  },
+  "required": [
+    "scheme",
+    "pattern"
+  ],
+  "type": "object"
+}

Changed2 schema fields changedNov 5, 2026

changedInput schema / properties / consignment / description

Previous value: -"Alternative to the other arguments: the consignment object (https://www.freightutils.com/schema/consignment-object.v1.json) — lines[] (description, un_number, packing_group, variant_index, quantity {value, unit, basis}, packages {count, type, gross_kg}, hs_code, value {amount, currency}, dims, stackable, icao_limited_quantity, inner_packaging), journey {origin, destination, date, tunnels_on_route, mode}, vehicle, crew, options. Send it alone; an input the tool needs and the object lacks comes back in missing_inputs."New value: +"Alternative to the other arguments: the consignment object (https://www.freightutils.com/schema/consignment-object.v1.json) — lines[] (description, un_number, packing_group, variant_index, quantity {value, unit, basis}, packages {count, type, gross_kg, un_mark}, hs_code, value {amount, currency}, dims, stackable, icao_limited_quantity, inner_packaging), journey {origin, destination, date, tunnels_on_route, mode}, vehicle, crew, options. Send it alone; an input the tool needs and the object lacks comes back in missing_inputs."

addedInput schema / properties / consignment / properties / lines / items / properties / packages / properties / un_mark
```
Added value: +{
+  "maxLength": 80,
+  "minLength": 1,
+  "type": "string"
+}
```

Changed7 schema fields changedNov 5, 2026

changedInput schema / properties / consignment / description

Previous value: -"Alternative to the other arguments: the consignment object (https://www.freightutils.com/schema/consignment-object.v1.json) — lines[] (description, un_number, packing_group, variant_index, quantity {value, unit, basis}, packages {count, type, gross_kg}, hs_code, value {amount, currency}, dims, stackable, icao_limited_quantity, inner_packaging), journey {origin, destination, date, tunnels_on_route, mode}, vehicle, options. Send it alone; an input the tool needs and the object lacks comes back in missing_inputs."New value: +"Alternative to the other arguments: the consignment object (https://www.freightutils.com/schema/consignment-object.v1.json) — lines[] (description, un_number, packing_group, variant_index, quantity {value, unit, basis}, packages {count, type, gross_kg}, hs_code, value {amount, currency}, dims, stackable, icao_limited_quantity, inner_packaging), journey {origin, destination, date, tunnels_on_route, mode}, vehicle, crew, options. Send it alone; an input the tool needs and the object lacks comes back in missing_inputs."

addedInput schema / properties / consignment / properties / crew

Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "adr_training_certificate": {
+      "type": "boolean"
+    },
+    "awareness_training_1_3": {
+      "type": "boolean"
+    },
+    "photo_identification": {
+      "type": "boolean"
+    },
+    "specialisations": {
+      "items": {
+        "enum": [
+          "class_1",
+          "class_7",
+          "tanks"
+        ],
+        "type": "string"
+      },
+      "maxItems": 3,
+      "type": "array"
+    }
+  },
+  "type": "object"
+}

addedInput schema / properties / consignment / properties / vehicle / properties / equipment_8_1_5

Added value: +{
+  "items": {
+    "enum": [
+      "wheel_chock",
+      "warning_signs",
+      "eye_rinsing_liquid",
+      "warning_vest",
+      "portable_lighting",
+      "protective_gloves",
+      "eye_protection",
+      "emergency_escape_mask",
+      "shovel",
+      "drain_seal",
+      "collecting_container"
+    ],
+    "type": "string"
+  },
+  "maxItems": 11,
+  "type": "array"
+}

addedInput schema / properties / consignment / properties / vehicle / properties / fire_extinguishers_kg

Added value: +{
+  "items": {
+    "exclusiveMinimum": 0,
+    "maximum": 100,
+    "type": "number"
+  },
+  "maxItems": 20,
+  "type": "array"
+}

addedInput schema / properties / consignment / properties / vehicle / properties / instructions_in_writing
```
Added value: +{
+  "type": "boolean"
+}
```
addedInput schema / properties / consignment / properties / vehicle / properties / orange_plates_displayed
```
Added value: +{
+  "type": "boolean"
+}
```
addedInput schema / properties / consignment / properties / vehicle / properties / placards_displayed
```
Added value: +{
+  "type": "boolean"
+}
```

Changed1 schema field changedNov 5, 2026
- addedInput schema / properties / consignment / properties / vehicle / properties / foodstuffs_carried
```
Added value: +{
+  "type": "boolean"
+}
```

Changed6 schema fields changedNov 5, 2026

changedInput schema / properties / consignment / description

Previous value: -"Alternative to the other arguments: the consignment object (https://www.freightutils.com/schema/consignment-object.v1.json) — lines[] (description, un_number, packing_group, variant_index, quantity {value, unit, basis}, packages {count, type, gross_kg}, hs_code, value {amount, currency}, dims, stackable), journey {origin, destination, date, tunnels_on_route, mode}, vehicle, options. Send it alone; an input the tool needs and the object lacks comes back in missing_inputs."New value: +"Alternative to the other arguments: the consignment object (https://www.freightutils.com/schema/consignment-object.v1.json) — lines[] (description, un_number, packing_group, variant_index, quantity {value, unit, basis}, packages {count, type, gross_kg}, hs_code, value {amount, currency}, dims, stackable, icao_limited_quantity, inner_packaging), journey {origin, destination, date, tunnels_on_route, mode}, vehicle, options. Send it alone; an input the tool needs and the object lacks comes back in missing_inputs."

addedInput schema / properties / consignment / properties / lines / items / properties / icao_limited_quantity
```
Added value: +{
+  "type": "boolean"
+}
```

addedInput schema / properties / consignment / properties / lines / items / properties / inner_packaging

Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "per_outer": {
+      "maximum": 100000,
+      "minimum": 1,
+      "type": "integer"
+    },
+    "quantity": {
+      "exclusiveMinimum": 0,
+      "maximum": 1000000,
+      "type": "number"
+    },
+    "regime": {
+      "enum": [
+        "lq",
+        "eq"
+      ],
+      "type": "string"
+    },
+    "unit": {
+      "enum": [
+        "ml",
+        "L",
+        "g",
+        "kg"
+      ],
+      "type": "string"
+    }
+  },
+  "required": [
+    "quantity",
+    "unit"
+  ],
+  "type": "object"
+}

removedInput schema / properties / consignment / properties / lines / items / properties / quantity / properties / value / exclusiveMinimum
```
Removed value: -0
```
addedInput schema / properties / consignment / properties / lines / items / properties / quantity / properties / value / minimum
```
Added value: +0
```
changedInput schema / properties / consignment / properties / lines / items / properties / un_number / pattern
```
Previous value: -"^(?:UN\\s?)?\\d{4}$"New value: +"^(?:(?:UN\\s?)?\\d{4}|ID\\s?\\d{4})$"
```

Changed2 schema fields changedNov 4, 2026
- removedOutput schema / properties / _meta / properties / receipt / properties / reason / const
```
Removed value: -"key_required"
```
- addedOutput schema / properties / _meta / properties / receipt / properties / reason / enum
```
Added value: +[
+  "key_required",
+  "quota"
+]
```

Changed1 schema field changedOct 30, 2026

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"
+}

Changed2 schema fields changedOct 30, 2026

addedInput schema / properties / as_of

Added value: +{
+  "description": "YYYY-MM-DD the answer is for (default today, UTC); picks the ADR edition when edition is omitted, and is echoed in the answer and its check receipt.",
+  "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+  "type": "string"
+}

addedInput schema / properties / edition

Added value: +{
+  "description": "ADR edition: \"2025\" or \"2027\". Wins over as_of. Omit it and as_of picks the edition by the legal timeline: before 2027-01-01 ADR 2025; from 2027-01-01 ADR 2027 (ADR 2025 may still be applied until 2027-06-30 under 1.6.1.1 — edition \"2025\" answers on it until then); from 2027-07-01 ADR 2027 only. An ADR 2027 answer for a date before 2027-01-01 carries an EDITION_NOT_YET_APPLICABLE warning.",
+  "enum": [
+    "2025",
+    "2027"
+  ],
+  "type": "string"
+}

Changed1 schema field changedOct 29, 2026
- addedOutput schema / properties / _meta / properties / edition_basis
```
Added value: +{
+  "type": "string"
+}
```
Changed36 schema fields changedOct 29, 2026
- removedInput schema / properties / consignment / properties / journey / properties / date / description
```
Removed value: -"Date of carriage, YYYY-MM-DD."
```
- removedInput schema / properties / consignment / properties / journey / properties / destination / description
```
Removed value: -"UN/LOCODE or ISO country code of the destination."
```
- removedInput schema / properties / consignment / properties / journey / properties / mode / description
```
Removed value: -"road | air | sea | multimodal."
```
- removedInput schema / properties / consignment / properties / journey / properties / origin / description
```
Removed value: -"UN/LOCODE or ISO country code of the origin."
```
- removedInput schema / properties / consignment / properties / journey / properties / tunnels_on_route / description
```
Removed value: -"ADR tunnel categories on the route (A–E)."
```
- removedInput schema / properties / consignment / properties / lines / description
```
Removed value: -"The lines of the load. Required."
```
- removedInput schema / properties / consignment / properties / lines / items / properties / description / description
```
Removed value: -"What the line is, at most 200 characters."
```
- removedInput schema / properties / consignment / properties / lines / items / properties / dims / description
```
Removed value: -"Dimensions of ONE package: { l, w, h, unit: mm | cm | m | in }."
```
- removedInput schema / properties / consignment / properties / lines / items / properties / hs_code / description
```
Removed value: -"HS / tariff commodity code, 6–10 digits."
```
- removedInput schema / properties / consignment / properties / lines / items / properties / packages / description
```
Removed value: -"The pieces: how many, of what type, and their total gross mass."
```
- removedInput schema / properties / consignment / properties / lines / items / properties / packages / properties / count / description
```
Removed value: -"Number of identical packages (pieces) on the line."
```
- removedInput schema / properties / consignment / properties / lines / items / properties / packages / properties / gross_kg / description
```
Removed value: -"Gross mass of ALL the line's packages together, in kg."
```
- removedInput schema / properties / consignment / properties / lines / items / properties / packages / properties / type / description
```
Removed value: -"Package type, e.g. \"pallet\", \"drum\", \"carton\"."
```
- removedInput schema / properties / consignment / properties / lines / items / properties / packing_group / description
```
Removed value: -"Packing group, to pin one ADR Table A row of a multi-row UN."
```
- removedInput schema / properties / consignment / properties / lines / items / properties / quantity / description
```
Removed value: -"The dangerous-goods quantity (ADR 1.1.3.6.3), separate from the gross mass of the packages."
```
- removedInput schema / properties / consignment / properties / lines / items / properties / quantity / properties / basis / description
```
Removed value: -"\"net\" (the goods) or \"gross\" (with packaging). 1.1.3.6.3 counts net; a gross figure scores no points."
```
- removedInput schema / properties / consignment / properties / lines / items / properties / quantity / properties / unit / description
```
Removed value: -"\"L\" or \"kg\" — checked against the dimension ADR 1.1.3.6.3 counts for the row."
```
- removedInput schema / properties / consignment / properties / lines / items / properties / quantity / properties / value / description
```
Removed value: -"The dangerous-goods quantity for the whole line, all packages together."
```
- removedInput schema / properties / consignment / properties / lines / items / properties / stackable / description
```
Removed value: -"Whether the packages may be stacked."
```
- removedInput schema / properties / consignment / properties / lines / items / properties / un_number / description
```
Removed value: -"UN number of a dangerous-goods line."
```
- removedInput schema / properties / consignment / properties / lines / items / properties / value / description
```
Removed value: -"Customs value of the whole line (all packages together)."
```
- removedInput schema / properties / consignment / properties / lines / items / properties / value / properties / amount / description
```
Removed value: -"The amount, 0 or more."
```
- removedInput schema / properties / consignment / properties / lines / items / properties / value / properties / currency / description
```
Removed value: -"ISO 4217 currency code, e.g. \"GBP\"."
```
- removedInput schema / properties / consignment / properties / lines / items / properties / variant_index / description
```
Removed value: -"ADR Table A variant index (as adr_lookup returns it), to pin one row."
```
- removedInput schema / properties / consignment / properties / options / properties / air_volumetric_divisor / description
```
Removed value: -"IATA volumetric divisor, cm³/kg (default 6000)."
```
- removedInput schema / properties / consignment / properties / options / properties / awb_number / description
```
Removed value: -"IATA air waybill number (check digit validated, advisory)."
```
- removedInput schema / properties / consignment / properties / options / properties / container_number / description
```
Removed value: -"ISO 6346 container number (check digit validated, advisory)."
```
- removedInput schema / properties / consignment / properties / options / properties / freight_cost / description
```
Removed value: -"Freight cost for the customs value."
```
- removedInput schema / properties / consignment / properties / options / properties / freight_cost / properties / amount / description
```
Removed value: -"The amount, 0 or more."
```
- removedInput schema / properties / consignment / properties / options / properties / freight_cost / properties / currency / description
```
Removed value: -"ISO 4217 currency code, e.g. \"GBP\"."
```
- removedInput schema / properties / consignment / properties / options / properties / incoterm / description
```
Removed value: -"Incoterms 2020 rule."
```
- removedInput schema / properties / consignment / properties / options / properties / insurance_cost / description
```
Removed value: -"Insurance cost for the customs value."
```
- removedInput schema / properties / consignment / properties / options / properties / insurance_cost / properties / amount / description
```
Removed value: -"The amount, 0 or more."
```
- removedInput schema / properties / consignment / properties / options / properties / insurance_cost / properties / currency / description
```
Removed value: -"ISO 4217 currency code, e.g. \"GBP\"."
```
- removedInput schema / properties / consignment / properties / vehicle / properties / max_mass_t / description
```
Removed value: -"Maximum permissible mass, tonnes."
```
- removedInput schema / properties / consignment / properties / vehicle / properties / type / description
```
Removed value: -"Vehicle type, e.g. \"artic\", \"rigid 7.5 t\"."
```

Changed1 schema field changedOct 29, 2026

addedOutput schema / properties / _meta

Added value: +{
+  "additionalProperties": {},
+  "properties": {
+    "check_id": {
+      "type": "string"
+    },
+    "receipt_url": {
+      "type": "string"
+    }
+  },
+  "type": "object"
+}

Changed1 schema field changedOct 29, 2026

addedInput schema / properties / consignment

Added value: +{
+  "additionalProperties": false,
+  "description": "Alternative to the other arguments: the consignment object (https://www.freightutils.com/schema/consignment-object.v1.json) — lines[] (description, un_number, packing_group, variant_index, quantity {value, unit, basis}, packages {count, type, gross_kg}, hs_code, value {amount, currency}, dims, stackable), journey {origin, destination, date, tunnels_on_route, mode}, vehicle, options. Send it alone; an input the tool needs and the object lacks comes back in missing_inputs.",
+  "properties": {
+    "journey": {
+      "additionalProperties": false,
+      "properties": {
+        "date": {
+          "description": "Date of carriage, YYYY-MM-DD.",
+          "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+          "type": "string"
+        },
+        "destination": {
+          "description": "UN/LOCODE or ISO country code of the destination.",
+          "pattern": "^[A-Za-z]{2}(?:\\s?[A-Za-z2-9]{3})?$",
+          "type": "string"
+        },
+        "mode": {
+          "description": "road | air | sea | multimodal.",
+          "enum": [
+            "road",
+            "air",
+            "sea",
+            "multimodal"
+          ],
+          "type": "string"
+        },
+        "origin": {
+          "description": "UN/LOCODE or ISO country code of the origin.",
+          "pattern": "^[A-Za-z]{2}(?:\\s?[A-Za-z2-9]{3})?$",
+          "type": "string"
+        },
+        "tunnels_on_route": {
+          "description": "ADR tunnel categories on the route (A–E).",
+          "items": {
+            "enum": [
+              "A",
+              "B",
+              "C",
+              "D",
+              "E"
+            ],
+            "type": "string"
+          },
+          "maxItems": 20,
+          "type": "array"
+        }
+      },
+      "type": "object"
+    },
+    "lines": {
+      "description": "The lines of the load. Required.",
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "description": {
+            "description": "What the line is, at most 200 characters.",
+            "maxLength": 200,
+            "type": "string"
+          },
+          "dims": {
+            "additionalProperties": false,
+            "description": "Dimensions of ONE package: { l, w, h, unit: mm | cm | m | in }.",
+            "properties": {
+              "h": {
+                "exclusiveMinimum": 0,
+                "maximum": 100000,
+                "type": "number"
+              },
+              "l": {
+                "exclusiveMinimum": 0,
+                "maximum": 100000,
+                "type": "number"
+              },
+              "unit": {
+                "enum": [
+                  "mm",
+                  "cm",
+                  "m",
+                  "in"
+                ],
+                "type": "string"
+              },
+              "w": {
+                "exclusiveMinimum": 0,
+                "maximum": 100000,
+                "type": "number"
+              }
+            },
+            "required": [
+              "l",
+              "w",
+              "h",
+              "unit"
+            ],
+            "type": "object"
+          },
+          "hs_code": {
+            "description": "HS / tariff commodity code, 6–10 digits.",
+            "pattern": "^\\d{6,10}$",
+            "type": "string"
+          },
+          "packages": {
+            "additionalProperties": false,
+            "description": "The pieces: how many, of what type, and their total gross mass.",
+            "properties": {
+              "count": {
+                "description": "Number of identical packages (pieces) on the line.",
+                "exclusiveMinimum": 0,
+                "maximum": 100000,
+                "type": "integer"
+              },
+              "gross_kg": {
+                "description": "Gross mass of ALL the line's packages together, in kg.",
+                "exclusiveMinimum": 0,
+                "maximum": 1000000,
+                "type": "number"
+              },
+              "type": {
+                "description": "Package type, e.g. \"pallet\", \"drum\", \"carton\".",
+                "maxLength": 40,
+                "type": "string"
+              }
+            },
+            "required": [
+              "count"
+            ],
+            "type": "object"
+          },
+          "packing_group": {
+            "description": "Packing group, to pin one ADR Table A row of a multi-row UN.",
+            "enum": [
+              "I",
+              "II",
+              "III"
+            ],
+            "type": "string"
+          },
+          "quantity": {
+            "additionalProperties": false,
+            "description": "The dangerous-goods quantity (ADR 1.1.3.6.3), separate from the gross mass of the packages.",
+            "properties": {
+              "basis": {
+                "description": "\"net\" (the goods) or \"gross\" (with packaging). 1.1.3.6.3 counts net; a gross figure scores no points.",
+                "enum": [
+                  "net",
+                  "gross"
+                ],
+                "type": "string"
+              },
+              "unit": {
+                "description": "\"L\" or \"kg\" — checked against the dimension ADR 1.1.3.6.3 counts for the row.",
+                "enum": [
+                  "L",
+                  "kg"
+                ],
+                "type": "string"
+              },
+              "value": {
+                "description": "The dangerous-goods quantity for the whole line, all packages together.",
+                "exclusiveMinimum": 0,
+                "maximum": 1000000000,
+                "type": "number"
+              }
+            },
+            "required": [
+              "value"
+            ],
+            "type": "object"
+          },
+          "stackable": {
+            "description": "Whether the packages may be stacked.",
+            "type": "boolean"
+          },
+          "un_number": {
+            "description": "UN number of a dangerous-goods line.",
+            "pattern": "^(?:UN\\s?)?\\d{4}$",
+            "type": "string"
+          },
+          "value": {
+            "additionalProperties": false,
+            "description": "Customs value of the whole line (all packages together).",
+            "properties": {
+              "amount": {
+                "description": "The amount, 0 or more.",
+                "maximum": 1000000000000,
+                "minimum": 0,
+                "type": "number"
+              },
+              "currency": {
+                "description": "ISO 4217 currency code, e.g. \"GBP\".",
+                "pattern": "^[A-Z]{3}$",
+                "type": "string"
+              }
+            },
+            "required": [
+              "amount",
+              "currency"
+            ],
+            "type": "object"
+          },
+          "variant_index": {
+            "description": "ADR Table A variant index (as adr_lookup returns it), to pin one row.",
+            "maximum": 1000,
+            "minimum": 0,
+            "type": "integer"
+          }
+        },
+        "type": "object"
+      },
+      "maxItems": 50,
+      "minItems": 1,
+      "type": "array"
+    },
+    "options": {
+      "additionalProperties": false,
+      "properties": {
+        "air_volumetric_divisor": {
+          "description": "IATA volumetric divisor, cm³/kg (default 6000).",
+          "exclusiveMinimum": 0,
+          "maximum": 10000,
+          "type": "number"
+        },
+        "awb_number": {
+          "description": "IATA air waybill number (check digit validated, advisory).",
+          "maxLength": 20,
+          "type": "string"
+        },
+        "container_number": {
+          "description": "ISO 6346 container number (check digit validated, advisory).",
+          "maxLength": 20,
+          "type": "string"
+        },
+        "freight_cost": {
+          "additionalProperties": false,
+          "description": "Freight cost for the customs value.",
+          "properties": {
+            "amount": {
+              "description": "The amount, 0 or more.",
+              "maximum": 1000000000000,
+              "minimum": 0,
+              "type": "number"
+            },
+            "currency": {
+              "description": "ISO 4217 currency code, e.g. \"GBP\".",
+              "pattern": "^[A-Z]{3}$",
+              "type": "string"
+            }
+          },
+          "required": [
+            "amount",
+            "currency"
+          ],
+          "type": "object"
+        },
+        "incoterm": {
+          "description": "Incoterms 2020 rule.",
+          "enum": [
+            "EXW",
+            "FCA",
+            "FAS",
+            "FOB",
+            "CFR",
+            "CIF",
+            "CPT",
+            "CIP",
+            "DAP",
+            "DPU",
+            "DDP"
+          ],
+          "type": "string"
+        },
+        "insurance_cost": {
+          "additionalProperties": false,
+          "description": "Insurance cost for the customs value.",
+          "properties": {
+            "amount": {
+              "description": "The amount, 0 or more.",
+              "maximum": 1000000000000,
+              "minimum": 0,
+              "type": "number"
+            },
+            "currency": {
+              "description": "ISO 4217 currency code, e.g. \"GBP\".",
+              "pattern": "^[A-Z]{3}$",
+              "type": "string"
+            }
+          },
+          "required": [
+            "amount",
+            "currency"
+          ],
+          "type": "object"
+        }
+      },
+      "type": "object"
+    },
+    "vehicle": {
+      "additionalProperties": false,
+      "properties": {
+        "axles": {
+          "maximum": 12,
+          "minimum": 1,
+          "type": "integer"
+        },
+        "max_mass_t": {
+          "description": "Maximum permissible mass, tonnes.",
+          "exclusiveMinimum": 0,
+          "maximum": 100,
+          "type": "number"
+        },
+        "type": {
+          "description": "Vehicle type, e.g. \"artic\", \"rigid 7.5 t\".",
+          "maxLength": 60,
+          "type": "string"
+        }
+      },
+      "type": "object"
+    }
+  },
+  "required": [
+    "lines"
+  ],
+  "type": "object"
+}

Changed5 schema fields changedOct 29, 2026

addedOutput schema / properties / as_of

Added value: +{
+  "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+  "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 / status

Added value: +{
+  "enum": [
+    "ok",
+    "partial",
+    "not_found",
+    "unsupported",
+    "ambiguous"
+  ],
+  "type": "string"
+}

Changed2 schema fields changedOct 28, 2026
- removedOutput schema / properties / validity / properties / effective_to / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedOutput schema / properties / validity / properties / effective_to / type
```
Added value: +[
+  "string",
+  "null"
+]
```
Changed2 schema fields changedOct 8, 2026
- addedInput schema / additionalProperties
```
Added value: +false
```
- addedInput schema / properties / items / items / additionalProperties
```
Added value: +false
```
Changed5 schema fields changedAug 11, 2026
- 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"
+]
```

Changed1 schema field changedJul 9, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "_source": {
+      "additionalProperties": false,
+      "properties": {
+        "checked": {
+          "type": "string"
+        },
+        "name": {
+          "type": "string"
+        },
+        "provenance_status": {
+          "enum": [
+            "verified",
+            "pending-verification",
+            "computed",
+            "live"
+          ],
+          "type": "string"
+        },
+        "source_url": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "name",
+        "checked",
+        "provenance_status"
+      ],
+      "type": "object"
+    },
+    "blocking_errors": {
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "code": {
+            "type": "string"
+          },
+          "message": {
+            "type": "string"
+          },
+          "recovery": {
+            "additionalProperties": false,
+            "properties": {
+              "action": {
+                "type": "string"
+              },
+              "params": {
+                "additionalProperties": {},
+                "propertyNames": {
+                  "type": "string"
+                },
+                "type": "object"
+              },
+              "tool": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "action"
+            ],
+            "type": "object"
+          }
+        },
+        "required": [
+          "code",
+          "message",
+          "recovery"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "citation": {
+      "additionalProperties": false,
+      "properties": {
+        "qualifier": {
+          "type": "string"
+        },
+        "text": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "text"
+      ],
+      "type": "object"
+    },
+    "confidence": {
+      "additionalProperties": false,
+      "properties": {
+        "basis": {
+          "enum": [
+            "deterministic",
+            "provenance",
+            "match_quality",
+            "freshness"
+          ],
+          "type": "string"
+        },
+        "level": {
+          "enum": [
+            "high",
+            "medium",
+            "low"
+          ],
+          "type": "string"
+        },
+        "score": {
+          "maximum": 1,
+          "minimum": 0,
+          "type": "number"
+        }
+      },
+      "required": [
+        "level",
+        "basis"
+      ],
+      "type": "object"
+    },
+    "envelope_version": {
+      "const": "1",
+      "type": "string"
+    },
+    "normalized_input": {
+      "additionalProperties": {},
+      "propertyNames": {
+        "type": "string"
+      },
+      "type": "object"
+    },
+    "ok": {
+      "type": "boolean"
+    },
+    "result": {
+      "additionalProperties": {},
+      "propertyNames": {
+        "type": "string"
+      },
+      "type": "object"
+    },
+    "validity": {
+      "additionalProperties": false,
+      "properties": {
+        "as_of": {
+          "type": "string"
+        },
+        "effective_from": {
+          "type": "string"
+        },
+        "effective_to": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        }
+      },
+      "required": [
+        "as_of"
+      ],
+      "type": "object"
+    },
+    "warnings": {
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "code": {
+            "type": "string"
+          },
+          "details": {
+            "additionalProperties": {},
+            "propertyNames": {
+              "type": "string"
+            },
+            "type": "object"
+          },
+          "message": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "code",
+          "message"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    }
+  },
+  "required": [
+    "envelope_version",
+    "ok",
+    "result",
+    "confidence",
+    "_source",
+    "citation"
+  ],
+  "type": "object"
+}

Changed17 schema fields changedJun 17, 2026

changedInput schema / properties / items / description

Previous value: -"Array of consignment items"New value: +"Deprecated flat alias — dimensions in cm, weight in kg. Prefer \"lines\". Provide lines OR items."

changedInput schema / properties / items / items / properties / description / description
```
Previous value: -"Item label"New value: +"Item description"
```
changedInput schema / properties / items / items / properties / gross_weight / description
```
Previous value: -"Weight per piece in kg"New value: +"Gross weight per piece in kg"
```
addedInput schema / properties / items / items / properties / gross_weight / exclusiveMinimum
```
Added value: +0
```

addedInput schema / properties / items / items / properties / hs_code

Added value: +{
+  "description": "Optional HS commodity code",
+  "type": "string"
+}

changedInput schema / properties / items / items / properties / pallet_type / description
```
Previous value: -"Pallet type"New value: +"Pallet type (informational)"
```

changedInput schema / properties / items / items / properties / pallet_type / enum

Previous value: -[
-  "none",
-  "euro",
-  "uk",
-  "us"
-]New value: +[
+  "none",
+  "euro",
+  "uk",
+  "us",
+  "custom"
+]

changedInput schema / properties / items / items / properties / quantity / description
```
Previous value: -"Number of pieces"New value: +"Number of pieces (default 1)"
```
changedInput schema / properties / items / items / properties / stackable / description
```
Previous value: -"Can items be stacked?"New value: +"Can the item be stacked?"
```

addedInput schema / properties / items / items / properties / un_number

Added value: +{
+  "description": "Optional UN number for dangerous-goods reference",
+  "type": "string"
+}

changedInput schema / properties / items / items / required

Previous value: -[
-  "length",
-  "width",
-  "height",
-  "quantity",
-  "gross_weight"
-]New value: +[
+  "length",
+  "width",
+  "height",
+  "gross_weight"
+]

addedInput schema / properties / items / maxItems
```
Added value: +50
```
addedInput schema / properties / items / minItems
```
Added value: +1
```

addedInput schema / properties / lines

Added value: +{
+  "description": "Canonical consignment lines (preferred). Each: { quantity, dims:{l,w,h,unit}, weight:{value,unit}, optional description / hs_code / un_number / stackable }.",
+  "items": {
+    "additionalProperties": false,
+    "properties": {
+      "description": {
+        "description": "Optional item label",
+        "maxLength": 200,
+        "type": "string"
+      },
+      "dims": {
+        "additionalProperties": false,
+        "properties": {
+          "h": {
+            "description": "Height in the given unit",
+            "exclusiveMinimum": 0,
+            "type": "number"
+          },
+          "l": {
+            "description": "Length in the given unit",
+            "exclusiveMinimum": 0,
+            "type": "number"
+          },
+          "unit": {
+            "description": "Dimension unit: mm | cm | m | in",
+            "enum": [
+              "mm",
+              "cm",
+              "m",
+              "in"
+            ],
+            "type": "string"
+          },
+          "w": {
+            "description": "Width in the given unit",
+            "exclusiveMinimum": 0,
+            "type": "number"
+          }
+        },
+        "required": [
+          "l",
+          "w",
+          "h",
+          "unit"
+        ],
+        "type": "object"
+      },
+      "hs_code": {
+        "description": "Optional HS commodity code",
+        "pattern": "^\\d{6,10}$",
+        "type": "string"
+      },
+      "quantity": {
+        "description": "Number of identical pieces",
+        "exclusiveMinimum": 0,
+        "maximum": 100000,
+        "type": "integer"
+      },
+      "stackable": {
+        "description": "Whether the line may be stacked two-high (halves its loading-metre footprint)",
+        "type": "boolean"
+      },
+      "un_number": {
+        "description": "Optional UN number for dangerous-goods reference",
+        "pattern": "^(UN)?\\d{4}$",
+        "type": "string"
+      },
+      "weight": {
+        "additionalProperties": false,
+        "properties": {
+          "unit": {
+            "description": "Weight unit: kg | g | t | lb",
+            "enum": [
+              "kg",
+              "g",
+              "t",
+              "lb"
+            ],
+            "type": "string"
+          },
+          "value": {
+            "description": "Gross weight per piece in the given unit",
+            "exclusiveMinimum": 0,
+            "type": "number"
+          }
+        },
+        "required": [
+          "value",
+          "unit"
+        ],
+        "type": "object"
+      }
+    },
+    "required": [
+      "quantity",
+      "dims",
+      "weight"
+    ],
+    "type": "object"
+  },
+  "maxItems": 50,
+  "minItems": 1,
+  "type": "array"
+}

addedInput schema / properties / mode

Added value: +{
+  "description": "Transport mode: sea | air | road (default road). Selects the chargeable-weight basis.",
+  "enum": [
+    "sea",
+    "air",
+    "road"
+  ],
+  "type": "string"
+}

addedInput schema / properties / options

Added value: +{
+  "additionalProperties": false,
+  "description": "Optional: { air_volumetric_divisor, container_number, awb_number }.",
+  "properties": {
+    "air_volumetric_divisor": {
+      "description": "IATA volumetric divisor in cm³/kg (default 6000). Only affects air.",
+      "exclusiveMinimum": 0,
+      "maximum": 10000,
+      "type": "number"
+    },
+    "awb_number": {
+      "description": "IATA 11-digit air waybill number — check-digit validated, advisory only",
+      "maxLength": 20,
+      "type": "string"
+    },
+    "container_number": {
+      "description": "ISO 6346 container number — check-digit validated, advisory only",
+      "maxLength": 20,
+      "type": "string"
+    }
+  },
+  "type": "object"
+}

removedInput schema / required
```
Removed value: -[
-  "items"
-]
```

Changed11 schema fields changedApr 29, 2026

removedInput schema / properties / items / items / properties / grossWeightKg

Removed value: -{
-  "description": "Weight per piece in kg",
-  "type": "number"
-}

addedInput schema / properties / items / items / properties / gross_weight

Added value: +{
+  "description": "Weight per piece in kg",
+  "type": "number"
+}

addedInput schema / properties / items / items / properties / height

Added value: +{
+  "description": "Height in cm",
+  "exclusiveMinimum": 0,
+  "type": "number"
+}

removedInput schema / properties / items / items / properties / heightCm

Removed value: -{
-  "description": "Height in cm",
-  "exclusiveMinimum": 0,
-  "type": "number"
-}

addedInput schema / properties / items / items / properties / length

Added value: +{
+  "description": "Length in cm",
+  "exclusiveMinimum": 0,
+  "type": "number"
+}

removedInput schema / properties / items / items / properties / lengthCm

Removed value: -{
-  "description": "Length in cm",
-  "exclusiveMinimum": 0,
-  "type": "number"
-}

removedInput schema / properties / items / items / properties / palletType

Removed value: -{
-  "description": "Pallet type",
-  "enum": [
-    "none",
-    "euro",
-    "uk",
-    "us"
-  ],
-  "type": "string"
-}

addedInput schema / properties / items / items / properties / pallet_type

Added value: +{
+  "description": "Pallet type",
+  "enum": [
+    "none",
+    "euro",
+    "uk",
+    "us"
+  ],
+  "type": "string"
+}

addedInput schema / properties / items / items / properties / width

Added value: +{
+  "description": "Width in cm",
+  "exclusiveMinimum": 0,
+  "type": "number"
+}

removedInput schema / properties / items / items / properties / widthCm

Removed value: -{
-  "description": "Width in cm",
-  "exclusiveMinimum": 0,
-  "type": "number"
-}

changedInput schema / properties / items / items / required

Previous value: -[
-  "lengthCm",
-  "widthCm",
-  "heightCm",
-  "quantity",
-  "grossWeightKg"
-]New value: +[
+  "length",
+  "width",
+  "height",
+  "quantity",
+  "gross_weight"
+]

First observedApr 23, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds substantial behavior beyond them: determinism, that flags are advisory only and never assert compliance, the specific flag categories (implausible density, mode/option mismatch, ADR 2025 dangerous-goods, container/AWB check digits), that invalid lines error naming the offending field, and that rate-limit errors carry reset_at. That is materially more than the annotations supply.

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 purpose is front-loaded and the remaining paragraphs are labelled by function (inputs, behavior, returns, editions, limitations, related), so scanning is easy. It is long and the Returns paragraph restates fields an output schema already enumerates, which is mild redundancy, but no sentence is filler.

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?

For a high-complexity tool with nested objects, 7 parameters and an output schema, the definition covers input shape, defaults, error behavior, edition selection, advisory-flag semantics and limits. The explicit non-regulatory disclaimer is important for a dangerous-goods-adjacent calculator and is stated clearly.

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 schema carries the parameter detail and a baseline 3 is the floor. The description still adds non-obvious meaning: the air_volumetric_divisor default of 6000 and that it only affects air, that items[] is legacy cm/kg, and the edition-vs-as_of precedence rule including the ADR 2025/2027 transition window. It does not document the nested consignment object that the schema also exposes.

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 plus resource: calculate per-line and grand totals for a multi-item mixed consignment, enumerating the concrete outputs (CBM, LDM, volumetric weight, mode-specific chargeable figure). The 'Related' line explicitly separates it from cbm_calculator / chargeable_weight_calculator / ldm_calculator by calling those 'single-figure versions', so an agent can distinguish intent without opening any schema.

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

Usage Guidelines4/5

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

Declares the default mode (road) and the accepted input shapes, stating lines[] is canonical and items[] is a deprecated legacy alias with cm/kg units. The Related section routes the agent to shipment_summary for vehicle/container suggestions and adr_lookup for flagged UN numbers. It stops short of an explicit 'use this instead of X when Y' exclusion rule, so it is strong context rather than full when/when-not guidance.

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

All FreightUtils MCP Server 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.

Consignment Calculator

Input Schema

Output Schema

Schema Changelog

TDQS

Glama MCP Gateway

Resources