FreightUtils MCP Server

consignment_calculator

Read-onlyIdempotent

Calculate per-line and total CBM, LDM, volumetric weight, and mode-specific chargeable figures for multi-item consignments, with advisory flags for density, dangerous goods, and document check digits.

Instructions

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.
`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	Legacy flat alias — dimensions in cm, weight in kg. Prefer lines.
`lines`	No	Canonical consignment lines (preferred, 1-50). Provide lines OR items.
`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 settings.
`consignment`	No	Alternative to the other arguments: the consignment object (https://www.freightutils.com/schema/consignment-object.v1.json) — lines[], journey, vehicle, options. Send it alone; an input this 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.

Changed7 schema fields changedv2.27.0Oct 31, 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 / consignment

Added value: +{
+  "additionalProperties": {},
+  "description": "Alternative to the other arguments: the consignment object (https://www.freightutils.com/schema/consignment-object.v1.json) — lines[], journey, vehicle, options. Send it alone; an input this tool needs and the object lacks comes back in missing_inputs.",
+  "propertyNames": {
+    "type": "string"
+  },
+  "type": "object"
+}

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

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

Changed11 schema fields changedv2.24.0Oct 29, 2026

addedInput schema / properties / items / items / properties / quantity / maximum
```
Added value: +9007199254740991
```

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": {
-      "air_volumetric_divisor": {
-        "type": [
-          "number",
-          "null"
-        ]
-      },
-      "disclaimer": {
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "flags": {
-        "anyOf": [
-          {
-            "items": {},
-            "type": "array"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "mode": {
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "per_line": {
-        "anyOf": [
-          {
-            "items": {
-              "additionalProperties": true,
-              "properties": {
-                "cbm": {
-                  "type": [
-                    "number",
-                    "null"
-                  ]
-                },
-                "chargeable_weight_kg": {
-                  "type": [
-                    "number",
-                    "null"
-                  ]
-                },
-                "density_kg_per_m3": {
-                  "type": [
-                    "number",
-                    "null"
-                  ]
-                },
-                "description": {
-                  "type": [
-                    "string",
-                    "null"
-                  ]
-                },
-                "gross_weight_kg": {
-                  "type": [
-                    "number",
-                    "null"
-                  ]
-                },
-                "ldm": {
-                  "type": [
-                    "number",
-                    "null"
-                  ]
-                },
-                "quantity": {
-                  "type": [
-                    "number",
-                    "null"
-                  ]
-                },
-                "revenue_tonnes": {
-                  "type": [
-                    "number",
-                    "null"
-                  ]
-                },
-                "volumetric_weight_kg": {
-                  "type": [
-                    "number",
-                    "null"
-                  ]
-                }
-              },
-              "type": "object"
-            },
-            "type": "array"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "schema_version": {
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "totals": {
-        "anyOf": [
-          {
-            "additionalProperties": {},
-            "type": "object"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      }
-    },
-    "type": "object"
-  },
-  {
-    "additionalProperties": {},
-    "type": "object"
-  }
-]New value: +[
+  {
+    "additionalProperties": {},
+    "properties": {
+      "air_volumetric_divisor": {
+        "type": [
+          "number",
+          "null"
+        ]
+      },
+      "disclaimer": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "flags": {
+        "anyOf": [
+          {
+            "items": {},
+            "type": "array"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "mode": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "per_line": {
+        "anyOf": [
+          {
+            "items": {
+              "additionalProperties": {},
+              "properties": {
+                "cbm": {
+                  "type": [
+                    "number",
+                    "null"
+                  ]
+                },
+                "chargeable_weight_kg": {
+                  "type": [
+                    "number",
+                    "null"
+                  ]
+                },
+                "density_kg_per_m3": {
+                  "type": [
+                    "number",
+                    "null"
+                  ]
+                },
+                "description": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                },
+                "gross_weight_kg": {
+                  "type": [
+                    "number",
+                    "null"
+                  ]
+                },
+                "ldm": {
+                  "type": [
+                    "number",
+                    "null"
+                  ]
+                },
+                "quantity": {
+                  "type": [
+                    "number",
+                    "null"
+                  ]
+                },
+                "revenue_tonnes": {
+                  "type": [
+                    "number",
+                    "null"
+                  ]
+                },
+                "volumetric_weight_kg": {
+                  "type": [
+                    "number",
+                    "null"
+                  ]
+                }
+              },
+              "type": "object"
+            },
+            "type": "array"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "schema_version": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "totals": {
+        "anyOf": [
+          {
+            "additionalProperties": {},
+            "propertyNames": {
+              "type": "string"
+            },
+            "type": "object"
+          },
+          {
+            "type": "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"
+}
```

Changed7 schema fields changedv2.22.3Oct 14, 2026
- addedInput schema / properties / lines / items / properties / description / maxLength
```
Added value: +200
```
- addedInput schema / properties / lines / items / properties / hs_code / pattern
```
Added value: +"^\\d{6,10}$"
```
- addedInput schema / properties / lines / items / properties / quantity / maximum
```
Added value: +100000
```
- addedInput schema / properties / lines / items / properties / un_number / pattern
```
Added value: +"^(UN)?\\d{4}$"
```
- addedInput schema / properties / options / properties / air_volumetric_divisor / maximum
```
Added value: +10000
```
- addedInput schema / properties / options / properties / awb_number / maxLength
```
Added value: +20
```
- addedInput schema / properties / options / properties / container_number / maxLength
```
Added value: +20
```
Changed5 schema fields changedv2.17.2Aug 21, 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"
+]
```

Changed28 schema fields changedv2.11.0Jul 10, 2026

changedInput schema / properties / items / description

Previous value: -"Deprecated flat alias — dimensions in cm, weight in kg. Prefer lines."New value: +"Legacy flat alias — dimensions in cm, weight in kg. Prefer lines."

changedInput schema / properties / items / items / properties / description / description
```
Previous value: -"Item description"New value: +"Item description."
```

changedInput schema / properties / items / items / properties / gross_weight / description

Previous value: -"Gross weight per piece in kg"New value: +"Gross weight per piece in kg."

changedInput schema / properties / items / items / properties / height / description
```
Previous value: -"Height in cm"New value: +"Height in cm."
```
changedInput schema / properties / items / items / properties / length / description
```
Previous value: -"Length in cm"New value: +"Length in cm."
```

changedInput schema / properties / items / items / properties / pallet_type / description

Previous value: -"Pallet type (informational)"New value: +"Pallet type (informational)."

changedInput schema / properties / items / items / properties / quantity / description

Previous value: -"Number of pieces (default 1)"New value: +"Number of pieces. Default: 1."

changedInput schema / properties / items / items / properties / width / description
```
Previous value: -"Width in cm"New value: +"Width in cm."
```

changedInput schema / properties / lines / description

Previous value: -"Canonical consignment lines (preferred). Provide lines OR items."New value: +"Canonical consignment lines (preferred, 1-50). Provide lines OR items."

changedInput schema / properties / lines / items / properties / description / description
```
Previous value: -"Optional item label"New value: +"Optional item label."
```

changedInput schema / properties / lines / items / properties / dims / description

Previous value: -"Dimensions with unit"New value: +"Per-piece dimensions with unit."

changedInput schema / properties / lines / items / properties / dims / properties / h / description
```
Previous value: -"Height in the given unit"New value: +"Height in the given unit."
```
changedInput schema / properties / lines / items / properties / dims / properties / l / description
```
Previous value: -"Length in the given unit"New value: +"Length in the given unit."
```
changedInput schema / properties / lines / items / properties / dims / properties / unit / description
```
Previous value: -"Dimension unit"New value: +"Dimension unit."
```
changedInput schema / properties / lines / items / properties / dims / properties / w / description
```
Previous value: -"Width in the given unit"New value: +"Width in the given unit."
```

changedInput schema / properties / lines / items / properties / hs_code / description

Previous value: -"Optional HS commodity code (6–10 digits)"New value: +"Optional HS commodity code (6-10 digits)."

changedInput schema / properties / lines / items / properties / quantity / description

Previous value: -"Number of identical pieces"New value: +"Number of identical pieces on this line."

changedInput schema / properties / lines / items / properties / stackable / description

Previous value: -"Stack two-high (halves loading-metre footprint)"New value: +"Stack two-high (halves the loading-metre footprint)."

changedInput schema / properties / lines / items / properties / un_number / description

Previous value: -"Optional UN number for dangerous-goods reference"New value: +"Optional UN number — triggers the dangerous-goods advisory flag."

changedInput schema / properties / lines / items / properties / weight / description
```
Previous value: -"Weight with unit"New value: +"Per-piece weight with unit."
```
changedInput schema / properties / lines / items / properties / weight / properties / unit / description
```
Previous value: -"Weight unit"New value: +"Weight unit."
```
changedInput schema / properties / lines / items / properties / weight / properties / value / description
```
Previous value: -"Gross weight per piece"New value: +"Gross weight per piece."
```

changedInput schema / properties / mode / description

Previous value: -"Transport mode: sea | air | road (default road)"New value: +"Transport mode: sea | air | road. Default: road."

changedInput schema / properties / options / description

Previous value: -"Optional settings"New value: +"Optional settings."

changedInput schema / properties / options / properties / air_volumetric_divisor / description

Previous value: -"IATA volumetric divisor in cm³/kg (default 6000). Air only."New value: +"IATA volumetric divisor in cm³/kg. Default: 6000. Air mode only."

changedInput schema / properties / options / properties / awb_number / description

Previous value: -"IATA 11-digit air waybill number, check-digit validated"New value: +"IATA 11-digit air waybill number — check-digit validated into flags."

changedInput schema / properties / options / properties / container_number / description

Previous value: -"ISO 6346 container number, check-digit validated"New value: +"ISO 6346 container number — check-digit validated into flags."

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": {},
+                "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": {},
+      "type": "object"
+    },
+    "ok": {
+      "type": "boolean"
+    },
+    "result": {
+      "anyOf": [
+        {
+          "additionalProperties": true,
+          "properties": {
+            "air_volumetric_divisor": {
+              "type": [
+                "number",
+                "null"
+              ]
+            },
+            "disclaimer": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "flags": {
+              "anyOf": [
+                {
+                  "items": {},
+                  "type": "array"
+                },
+                {
+                  "type": "null"
+                }
+              ]
+            },
+            "mode": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "per_line": {
+              "anyOf": [
+                {
+                  "items": {
+                    "additionalProperties": true,
+                    "properties": {
+                      "cbm": {
+                        "type": [
+                          "number",
+                          "null"
+                        ]
+                      },
+                      "chargeable_weight_kg": {
+                        "type": [
+                          "number",
+                          "null"
+                        ]
+                      },
+                      "density_kg_per_m3": {
+                        "type": [
+                          "number",
+                          "null"
+                        ]
+                      },
+                      "description": {
+                        "type": [
+                          "string",
+                          "null"
+                        ]
+                      },
+                      "gross_weight_kg": {
+                        "type": [
+                          "number",
+                          "null"
+                        ]
+                      },
+                      "ldm": {
+                        "type": [
+                          "number",
+                          "null"
+                        ]
+                      },
+                      "quantity": {
+                        "type": [
+                          "number",
+                          "null"
+                        ]
+                      },
+                      "revenue_tonnes": {
+                        "type": [
+                          "number",
+                          "null"
+                        ]
+                      },
+                      "volumetric_weight_kg": {
+                        "type": [
+                          "number",
+                          "null"
+                        ]
+                      }
+                    },
+                    "type": "object"
+                  },
+                  "type": "array"
+                },
+                {
+                  "type": "null"
+                }
+              ]
+            },
+            "schema_version": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "totals": {
+              "anyOf": [
+                {
+                  "additionalProperties": {},
+                  "type": "object"
+                },
+                {
+                  "type": "null"
+                }
+              ]
+            }
+          },
+          "type": "object"
+        },
+        {
+          "additionalProperties": {},
+          "type": "object"
+        }
+      ]
+    },
+    "validity": {
+      "additionalProperties": false,
+      "properties": {
+        "as_of": {
+          "type": "string"
+        },
+        "effective_from": {
+          "type": "string"
+        },
+        "effective_to": {
+          "type": [
+            "string",
+            "null"
+          ]
+        }
+      },
+      "required": [
+        "as_of"
+      ],
+      "type": "object"
+    },
+    "warnings": {
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "code": {
+            "type": "string"
+          },
+          "details": {
+            "additionalProperties": {},
+            "type": "object"
+          },
+          "message": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "code",
+          "message"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    }
+  },
+  "required": [
+    "envelope_version",
+    "ok",
+    "result",
+    "confidence",
+    "_source",
+    "citation"
+  ],
+  "type": "object"
+}

Changed15 schema fields changedv2.4.1Jun 18, 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."

changedInput schema / properties / items / items / properties / gross_weight / description

Previous value: -"Gross weight per item in kg"New value: +"Gross weight per piece in kg"

addedInput schema / properties / items / items / properties / gross_weight / exclusiveMinimum
```
Added value: +0
```
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: -[
-  "euro",
-  "uk",
-  "us",
-  "custom",
-  "none"
-]New value: +[
+  "none",
+  "euro",
+  "uk",
+  "us",
+  "custom"
+]

changedInput schema / properties / items / items / properties / quantity / description

Previous value: -"Number of items (default: 1)"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?"
```

changedInput schema / properties / items / items / required

Previous value: -[
-  "length",
-  "width",
-  "height"
-]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). Provide lines OR items.",
+  "items": {
+    "additionalProperties": false,
+    "properties": {
+      "description": {
+        "description": "Optional item label",
+        "type": "string"
+      },
+      "dims": {
+        "additionalProperties": false,
+        "description": "Dimensions with unit",
+        "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",
+            "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 (6–10 digits)",
+        "type": "string"
+      },
+      "quantity": {
+        "description": "Number of identical pieces",
+        "exclusiveMinimum": 0,
+        "type": "integer"
+      },
+      "stackable": {
+        "description": "Stack two-high (halves loading-metre footprint)",
+        "type": "boolean"
+      },
+      "un_number": {
+        "description": "Optional UN number for dangerous-goods reference",
+        "type": "string"
+      },
+      "weight": {
+        "additionalProperties": false,
+        "description": "Weight with unit",
+        "properties": {
+          "unit": {
+            "description": "Weight unit",
+            "enum": [
+              "kg",
+              "g",
+              "t",
+              "lb"
+            ],
+            "type": "string"
+          },
+          "value": {
+            "description": "Gross weight per piece",
+            "exclusiveMinimum": 0,
+            "type": "number"
+          }
+        },
+        "required": [
+          "value",
+          "unit"
+        ],
+        "type": "object"
+      }
+    },
+    "required": [
+      "quantity",
+      "dims",
+      "weight"
+    ],
+    "type": "object"
+  },
+  "maxItems": 50,
+  "minItems": 1,
+  "type": "array"
+}

changedInput schema / properties / mode / description

Previous value: -"Transport mode (default: road)"New value: +"Transport mode: sea | air | road (default road)"

changedInput schema / properties / mode / enum

Previous value: -[
-  "road",
-  "air",
-  "sea"
-]New value: +[
+  "sea",
+  "air",
+  "road"
+]

addedInput schema / properties / options

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

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

Addedv2.1.1May 17, 2026

TDQS

A4.6/5.0

Behavior4/5

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

Annotations already cover safety (readOnly=true, destructive=false, idempotent=true), yet the description adds substantive non-structural behavior: deterministic execution, flags are advisory only and never assert compliance, invalid lines error naming the offending field, and rate-limit errors carry reset_at. The edition/as_of timeline is disclosed but is largely duplicated from the schema's own edition documentation.

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 purpose and inputs, then behavior, then returns, then edition rules and limitations – a sensible ordering. It is long, however, and the ADR edition timeline is explained in both the body and the schema, so a few sentences do not fully earn their place.

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

Completeness5/5

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

Given seven parameters with nested objects, an output schema, and a schema-linked canonical reference, the description covers everything an agent needs: input shapes, defaults, flags, error behavior, edition precedence, limitations, and the sibling routing. Return values are additionally summarized despite the output schema existing, which is harmless redundancy rather than a gap.

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 description coverage is 100%, so the baseline is 3; the description goes beyond it by spelling out cross-parameter semantics the schema states piecemeal (edition wins over as_of, air divisor defaults to 6000 and applies to air only, container/AWB numbers produce check-digit flags). Some of this repeats the schema's own field text, so it is additive rather than transformative.

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?

States a specific verb (calculate) and a precisely scoped resource (per-line and grand totals for mixed consignments), enumerating the exact figures produced (CBM, LDM, volumetric weight, mode-specific chargeable figure). It also distinguishes itself from the single-figure siblings by contrast, so an agent can route correctly without opening 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?

Explicitly names the alternatives and what each adds (cbm_calculator / chargeable_weight_calculator / ldm_calculator are single-figure; shipment_summary adds vehicle suggestion and duty estimates; adr_lookup explains a flagged UN number). It also states the canonical-vs-legacy input preference (lines[] preferred, items[] legacy), which is a routing decision inside the call itself.

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