FreightUtils MCP Server

cbm_calculator

Read-onlyIdempotent

Calculate shipment cubic metres (CBM) from per-piece length, width and height in centimetres, scaling by piece count and converting totals to cubic feet, litres and cubic inches.

Instructions

Calculate cubic metres (CBM) for a shipment from per-piece dimensions. CBM is the standard volume unit in international shipping: 1 CBM = 1m x 1m x 1m = 1,000 litres, and ocean freight prices per "freight tonne" (1 CBM or 1,000 kg, whichever is greater).

Behavior: deterministic — identical inputs always return identical figures; total volume = pieces x per-piece CBM (totals are computed from unrounded figures and rounded only for display), with conversions to cubic feet, cubic inches and litres (exact factors: 1 ft = 0.3048 m). Missing or non-positive dimensions error with a validation message naming the parameter. Rate-limited: a limit error carries reset_at, the UTC time the allowance resets.

Returns: cbm_per_piece, total_cbm, cubic_feet, litres, cubic_inches and pieces under result, 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: chargeable_weight_calculator (air billing weight from the same dims), consignment_calculator (multi-line totals), unit_converter (single conversions), shipment_summary (full composite analysis).

Input Schema

TableJSON Schema

Name	Required	Description
`pieces`	No	Number of identical pieces — total volume scales linearly. 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.

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.

Changed1 schema field changedv2.22.3Oct 14, 2026
- 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"
+]
```

Changed5 schema fields changedv2.11.0Jul 10, 2026

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 — total volume scales linearly. 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": {
+            "cbm_per_piece": {
+              "type": [
+                "number",
+                "null"
+              ]
+            },
+            "cubic_feet": {
+              "type": [
+                "number",
+                "null"
+              ]
+            },
+            "cubic_inches": {
+              "type": [
+                "number",
+                "null"
+              ]
+            },
+            "litres": {
+              "type": [
+                "number",
+                "null"
+              ]
+            },
+            "meta": {
+              "anyOf": [
+                {
+                  "additionalProperties": {},
+                  "type": "object"
+                },
+                {
+                  "type": "null"
+                }
+              ]
+            },
+            "pieces": {
+              "type": [
+                "number",
+                "null"
+              ]
+            },
+            "total_cbm": {
+              "type": [
+                "number",
+                "null"
+              ]
+            },
+            "total_volume_m3": {
+              "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.4/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, closed-world), and the description layers on substantial extra behavior: deterministic identity of outputs, totals computed from unrounded figures and rounded only for display, exact conversion factors, validation errors that name the offending parameter, and rate-limit errors carrying reset_at. This is exactly the added context that annotations cannot 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 in the first sentence, followed by behavior, returns and related tools in a clean progression with no filler. The Returns paragraph partially duplicates the output schema's field list, which is the only notable redundancy in an otherwise tight definition.

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 a validation surface, the definition covers inputs, arithmetic semantics, rounding, error and rate-limit behavior, and even the snake_case vs camelCase field-naming difference between the package and the hosted endpoint. Nothing an agent needs to call it correctly is missing.

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

Parameters3/5

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

Schema description coverage is 100%, so all four parameters (pieces plus the three dimensions) are already documented in the schema with types, bounds and examples. The description restates the linear scaling relationship (pieces x per-piece CBM) but adds no new syntax or format guidance beyond the schema, so the baseline 3 applies.

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 cubic metres (CBM) for a shipment from per-piece dimensions' — and immediately defines the domain term. The Related section names the adjacent calculators, so an agent can tell this apart from chargeable_weight_calculator, consignment_calculator and unit_converter 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?

The Related line routes the agent with explicit conditions: use chargeable_weight_calculator for air billing weight from the same dims, consignment_calculator for multi-line totals, unit_converter for single conversions, shipment_summary for composite analysis. This is clear alternative mapping, though it stops short of stating an explicit 'do not use this when…' exclusion.

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