FreightUtils MCP Server

chargeable_weight_calculator

Read-onlyIdempotent

Calculate air freight chargeable weight—the greater of actual gross weight and volumetric weight (LxWxH cm ÷ 6000 or 5000)—to find the billable weight airlines charge.

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

TableJSON 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

TableJSON Schema

Name	Required	Description	Default
`ok`	Yes
`result`	Yes
`_source`	Yes
`citation`	Yes
`validity`	No
`warnings`	No
`confidence`	Yes
`blocking_errors`	No
`envelope_version`	Yes
`normalized_input`	No

Schema Changelog

Changes observed during successful MCP inspections.

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 already establish readOnly/idempotent/non-destructive, so the bar is easily cleared, and the description still adds substantial behavior: deterministic output, unrounded-then-rounded-for-display math with a worked example (10,000 pcs = 250 kg), the meaning of basis values, explicit input-validation error behavior, and rate-limit reset_at semantics. This is exactly the context annotations cannot carry.

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 core formula and then the per-piece/total and rounding caveats, so the important content is not buried. It is dense but generally earns its length; the extended field-by-field return listing and camelCase/snake_case mapping notes are somewhat redundant given a full output schema exists, which keeps it from a 5.

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 calculator with 6 parameters and an output schema, every decision an agent must make — which weight governs, per-piece vs total inputs, divisor choice, unit basis, error and rate-limit behavior — is covered. Nothing needed to invoke it correctly is missing.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3, but the description earns above baseline by disambiguating the trickiest parameter relationship — dimensions are per piece while gross_weight_kg is the TOTAL across all pieces — a distinction that is easy to get wrong even with the schema text present.

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 and resource ('Calculate air freight chargeable weight') and immediately defines the computation (greater of actual gross weight and volumetric weight). It squarely distinguishes itself from siblings by naming cbm_calculator, consignment_calculator and uld_lookup with a short role for each.

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 scopes itself to air mode and states the exclusion — sea W/M is handled by consignment_calculator with mode=sea — so an agent knows both when to use it and when to route elsewhere. The Related line adds a secondary routing map for volume-only and multi-line cases.

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