FreightUtils MCP Server

chargeable_weight_calculator

Read-onlyIdempotent

Calculate air freight chargeable weight by comparing total gross weight against volumetric weight (L×W×H per piece ÷ divisor) to output the billed weight, basis and CBM for each shipment.

Instructions

Calculate air freight chargeable weight — the greater of actual gross weight and volumetric weight, which is what airlines bill. Volumetric weight (kg) = (L x W x H in cm) / divisor; the IATA-standard divisor is 6,000 (1 CBM = 166.67 kg), while express integrators (DHL, FedEx, UPS) typically use 5,000.

Behavior: deterministic; the dimensions are per piece and gross_weight_kg is the TOTAL for all pieces; totals are computed from unrounded figures and rounded only for display (10,000 pieces of 5 x 5 x 6 cm = 250 kg); basis reports which weight governs ("volumetric" = cargo is light for its size, "actual" = dense). Air mode only — sea W/M (1 CBM = 1,000 kg) is covered by consignment_calculator with mode=sea. Missing or non-positive inputs error with the failing parameter named. Rate-limited: a limit error carries reset_at, the UTC time the allowance resets.

Returns: chargeable_weight_kg, basis, volumetric_weight_kg (the total; the hosted endpoint names it volumetricWeightTotalKg) and volumetric_weight_per_piece_kg, gross_weight_kg, cbm, ratio, factor and pieces under result; normalized_input echoes the interpreted inputs (gross_weight_basis, dimensions_basis) and any defaults applied; plus confidence, _source and citation (the FreightUtils v1 response envelope). Field names as this package serves them (snake_case); the hosted /api/mcp endpoint serves the same fields in camelCase (e.g. total_cbm → totalCbm).

Related: cbm_calculator (volume only), consignment_calculator (multi-line, all modes), uld_lookup (the equipment the freight flies in).

Input Schema

Name	Required	Description
`factor`	No	Volumetric divisor in cm³/kg. Default: 6000 (IATA standard); express carriers typically 5000.
`pieces`	No	Number of identical pieces. Default: 1.
`width_cm`	Yes	Width of one piece in centimetres (> 0). Example: 80.
`height_cm`	Yes	Height of one piece in centimetres (> 0). Example: 100.
`length_cm`	Yes	Length of one piece in centimetres (> 0). Example: 120.
`gross_weight_kg`	Yes	Actual gross weight of the WHOLE shipment (all pieces) in kilograms. Example: 500.

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.

Changed4 schema fields changedv2.27.0Oct 31, 2026

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

Changed10 schema fields changedv2.24.0Oct 29, 2026

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": {
-      "basis": {
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "cbm": {
-        "type": [
-          "number",
-          "null"
-        ]
-      },
-      "chargeable_weight_kg": {
-        "type": [
-          "number",
-          "null"
-        ]
-      },
-      "factor": {
-        "type": [
-          "number",
-          "null"
-        ]
-      },
-      "gross_weight_kg": {
-        "type": [
-          "number",
-          "null"
-        ]
-      },
-      "meta": {
-        "anyOf": [
-          {
-            "additionalProperties": {},
-            "type": "object"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "pieces": {
-        "type": [
-          "number",
-          "null"
-        ]
-      },
-      "ratio": {
-        "type": [
-          "number",
-          "null"
-        ]
-      },
-      "volumetric_weight_kg": {
-        "type": [
-          "number",
-          "null"
-        ]
-      },
-      "volumetric_weight_per_piece_kg": {
-        "type": [
-          "number",
-          "null"
-        ]
-      }
-    },
-    "type": "object"
-  },
-  {
-    "additionalProperties": {},
-    "type": "object"
-  }
-]New value: +[
+  {
+    "additionalProperties": {},
+    "properties": {
+      "basis": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "cbm": {
+        "type": [
+          "number",
+          "null"
+        ]
+      },
+      "chargeable_weight_kg": {
+        "type": [
+          "number",
+          "null"
+        ]
+      },
+      "factor": {
+        "type": [
+          "number",
+          "null"
+        ]
+      },
+      "gross_weight_kg": {
+        "type": [
+          "number",
+          "null"
+        ]
+      },
+      "meta": {
+        "anyOf": [
+          {
+            "additionalProperties": {},
+            "propertyNames": {
+              "type": "string"
+            },
+            "type": "object"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "pieces": {
+        "type": [
+          "number",
+          "null"
+        ]
+      },
+      "ratio": {
+        "type": [
+          "number",
+          "null"
+        ]
+      },
+      "volumetric_weight_kg": {
+        "type": [
+          "number",
+          "null"
+        ]
+      },
+      "volumetric_weight_per_piece_kg": {
+        "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"
+}
```

Changed2 schema fields changedv2.22.3Oct 14, 2026
- addedInput schema / properties / factor / maximum
```
Added value: +9007199254740991
```
- addedInput schema / properties / pieces / maximum
```
Added value: +9007199254740991
```
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"
+]
```

Changed7 schema fields changedv2.11.0Jul 10, 2026

changedInput schema / properties / factor / description

Previous value: -"Volumetric divisor (default: 6000 IATA standard, DHL uses 5000)"New value: +"Volumetric divisor in cm³/kg. Default: 6000 (IATA standard); express carriers typically 5000."

changedInput schema / properties / gross_weight_kg / description

Previous value: -"Actual gross weight in kilograms"New value: +"Actual gross weight of the WHOLE shipment (all pieces) in kilograms. Example: 500."

changedInput schema / properties / height_cm / description

Previous value: -"Height in centimetres"New value: +"Height of one piece in centimetres (> 0). Example: 100."

changedInput schema / properties / length_cm / description

Previous value: -"Length in centimetres"New value: +"Length of one piece in centimetres (> 0). Example: 120."

changedInput schema / properties / pieces / description

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

changedInput schema / properties / width_cm / description

Previous value: -"Width in centimetres"New value: +"Width of one piece in centimetres (> 0). Example: 80."

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": {
+            "basis": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "cbm": {
+              "type": [
+                "number",
+                "null"
+              ]
+            },
+            "chargeable_weight_kg": {
+              "type": [
+                "number",
+                "null"
+              ]
+            },
+            "factor": {
+              "type": [
+                "number",
+                "null"
+              ]
+            },
+            "gross_weight_kg": {
+              "type": [
+                "number",
+                "null"
+              ]
+            },
+            "meta": {
+              "anyOf": [
+                {
+                  "additionalProperties": {},
+                  "type": "object"
+                },
+                {
+                  "type": "null"
+                }
+              ]
+            },
+            "pieces": {
+              "type": [
+                "number",
+                "null"
+              ]
+            },
+            "ratio": {
+              "type": [
+                "number",
+                "null"
+              ]
+            },
+            "volumetric_weight_kg": {
+              "type": [
+                "number",
+                "null"
+              ]
+            },
+            "volumetric_weight_per_piece_kg": {
+              "type": [
+                "number",
+                "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"
+}

First observedv1.0.0Apr 3, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds genuine behavioral context beyond them: deterministic execution, per-piece dimensions vs total gross weight, unrounded intermediate math with display-only rounding, named-parameter errors, and rate-limit reset_at semantics.

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 rule, then cleanly sectioned into Behavior, Returns, and Related. It is dense but nearly every sentence earns its place; the enumeration of return fields and the camelCase naming digression are somewhat padded given an output schema exists.

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 deterministic calculator with 6 params, full schema coverage, and an output schema, the description is more than sufficient — it even pre-empts rounding and unit confusion that would otherwise cause incorrect calls. Nothing an agent needs 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 is 3, but the description adds real meaning: it clarifies that dimensions are per piece while gross_weight_kg is the shipment total, and explains the divisor's business meaning (6000 IATA vs 5000 express) in a way that informs parameter choice.

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+resource ('Calculate air freight chargeable weight') and immediately defines the governing rule (greater of actual vs volumetric). It distinguishes itself from siblings by naming cbm_calculator, consignment_calculator, and uld_lookup with their respective scopes.

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 bounds the tool to air mode and routes the sea W/M case to consignment_calculator with mode=sea. The 'Related' section names alternatives and what each one handles, so the agent can pick the right tool without opening schemas.

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