FreightUtils MCP Server

container_lookup

Read-onlyIdempotent

Look up ISO shipping-container dimensions, capacity and payload, or supply item dimensions to calculate how many items fit inside a container.

Instructions

Get ISO shipping-container specifications, with optional load-fit maths. Covers 10 types: 20ft/40ft standard, 40ft and 45ft high-cube, 20ft/40ft reefer, 20ft/40ft open-top and 20ft/40ft flat-rack.

Provide type as a slug (e.g. "20ft-standard", "40ft-high-cube") for one container's record; omit it to list all 10 as summary rows (full: true for full records). Add item dimensions (item_length_cm/width_cm/height_cm, optional item_weight_kg and item_quantity) to also compute how many such items fit.

Behavior: read-only reference data with per-record provenance (sources, audited_at, decision_rationale); type is read in any letter case, as the ISO size-type code ("45G1") or the short form of its name ("40HC"); an unknown type errors with the valid slugs and the closest one ("20ft-standrd" → 20ft-standard). Fit calculations are geometric best-effort — they do not model load distribution, securing or mixed cargo. Rate-limited: a limit error carries reset_at, the UTC time the allowance resets.

Returns: the container record — internal/external/door dimensions (cm), capacity_cbm, tare_weight_kg, max_gross_kg, max_payload_kg and euro/GMA pallet counts — 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). A list (no single record asked for) returns summary rows with total, truncated, next_offset and detail_hint; full: true returns full records five per page, with offset / limit to page.

Limitations: manufacturer-typical specs, provenance pending independent verification (the envelope's provenance_status says so) — actual equipment varies by lessor and line; confirm against the carrier's equipment guide.

Related: validate (checks a container NUMBER's ISO 6346 check digit — not specs), cbm_calculator / consignment_calculator (the cargo volume to fill it), uld_lookup (the air-freight equivalent).

Input Schema

Name	Required	Description
`full`	No	Lists only: true returns full records (provenance, sources, rationale) instead of summary rows, five per page by default. A single-record call always returns the full record.
`type`	No	Container slug. Examples: "20ft-standard", "40ft-high-cube", "20ft-reefer". Omit to list all 10 types.
`limit`	No	Lists only: rows per page (default: every summary row; 5 with full: true).
`offset`	No	Lists only: rows to skip (default 0). The response gives total and next_offset.
`item_quantity`	No	Number of items to check against the container.
`item_width_cm`	No	Item width in cm.
`item_height_cm`	No	Item height in cm.
`item_length_cm`	No	Item length in cm — provide all three item dims to get a load-fit calculation.
`item_weight_kg`	No	Weight of ONE item in kg — caps the fit by max payload. 0 or omitted: no weight check.

Output 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.

Changed7 schema fields changedv2.22.3Oct 14, 2026

addedInput schema / properties / full

Added value: +{
+  "description": "Lists only: true returns full records (provenance, sources, rationale) instead of summary rows, five per page by default. A single-record call always returns the full record.",
+  "type": "boolean"
+}

addedInput schema / properties / item_quantity / maximum
```
Added value: +9007199254740991
```

changedInput schema / properties / item_weight_kg / description

Previous value: -"Item weight in kg — caps the fit by max payload."New value: +"Weight of ONE item in kg — caps the fit by max payload. 0 or omitted: no weight check."

removedInput schema / properties / item_weight_kg / exclusiveMinimum
```
Removed value: -0
```
addedInput schema / properties / item_weight_kg / minimum
```
Added value: +0
```

addedInput schema / properties / limit

Added value: +{
+  "description": "Lists only: rows per page (default: every summary row; 5 with full: true).",
+  "maximum": 100,
+  "minimum": 1,
+  "type": "integer"
+}

addedInput schema / properties / offset

Added value: +{
+  "description": "Lists only: rows to skip (default 0). The response gives total and next_offset.",
+  "maximum": 9007199254740991,
+  "minimum": 0,
+  "type": "integer"
+}

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 / item_height_cm / description

Previous value: -"Item height in cm"New value: +"Item height in cm."

changedInput schema / properties / item_length_cm / description

Previous value: -"Item length in cm (for loading calculation)"New value: +"Item length in cm — provide all three item dims to get a load-fit calculation."

changedInput schema / properties / item_quantity / description

Previous value: -"Number of items"New value: +"Number of items to check against the container."

changedInput schema / properties / item_weight_kg / description

Previous value: -"Item weight in kg"New value: +"Item weight in kg — caps the fit by max payload."

changedInput schema / properties / item_width_cm / description

Previous value: -"Item width in cm"New value: +"Item width in cm."

changedInput schema / properties / type / description

Previous value: -"Container slug (e.g., \"20ft-standard\", \"40ft-high-cube\"). Omit to list all types."New value: +"Container slug. Examples: \"20ft-standard\", \"40ft-high-cube\", \"20ft-reefer\". Omit to list all 10 types."

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": {
+            "audited_at": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "capacity_cbm": {
+              "type": [
+                "number",
+                "null"
+              ]
+            },
+            "containers": {
+              "anyOf": [
+                {
+                  "items": {},
+                  "type": "array"
+                },
+                {
+                  "type": "null"
+                }
+              ]
+            },
+            "count": {
+              "type": [
+                "number",
+                "null"
+              ]
+            },
+            "description": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "door_height_cm": {
+              "type": [
+                "number",
+                "null"
+              ]
+            },
+            "door_width_cm": {
+              "type": [
+                "number",
+                "null"
+              ]
+            },
+            "euro_pallets": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "external_height_cm": {
+              "type": [
+                "number",
+                "null"
+              ]
+            },
+            "external_length_cm": {
+              "type": [
+                "number",
+                "null"
+              ]
+            },
+            "external_width_cm": {
+              "type": [
+                "number",
+                "null"
+              ]
+            },
+            "gma_pallets": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "internal_height_cm": {
+              "type": [
+                "number",
+                "null"
+              ]
+            },
+            "internal_length_cm": {
+              "type": [
+                "number",
+                "null"
+              ]
+            },
+            "internal_width_cm": {
+              "type": [
+                "number",
+                "null"
+              ]
+            },
+            "iso_code": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "loading": {
+              "anyOf": [
+                {
+                  "additionalProperties": {},
+                  "type": "object"
+                },
+                {
+                  "type": "null"
+                }
+              ]
+            },
+            "max_gross_kg": {
+              "type": [
+                "number",
+                "null"
+              ]
+            },
+            "max_payload_kg": {
+              "type": [
+                "number",
+                "null"
+              ]
+            },
+            "name": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "notes": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "slug": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "tare_weight_kg": {
+              "type": [
+                "number",
+                "null"
+              ]
+            },
+            "verified": {
+              "type": [
+                "boolean",
+                "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"
+}

Changed1 schema field changedv2.5.0Jun 22, 2026
- addedInput schema / properties / type / minLength
```
Added value: +2
```
First observedv1.0.0Apr 3, 2026

TDQS

A4.6/5.0

Behavior4/5

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

Annotations already declare read-only, idempotent, non-destructive and closed-world, so the safety profile is covered — but the description goes further and adds real behavioral context: per-record provenance, case-insensitive/ISO-code/short-form type parsing, the unknown-type error with slug suggestions, the rate limit and its reset_at behavior, and the request envelope (confidence, _source, citation, provenance_status).

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?

Purpose, coverage and the primary type/omit choice are front-loaded, and the prose is dense but organised. It is however long for a reference lookup, and parts of it restate schema-level semantics already documented per-parameter (full, limit/offset paging, item weight behavior).

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 9-parameter, zero-required reference tool with an output schema, everything needed to call and interpret it is present: the type slug format and error recovery, the list vs single-record modes with pagination and truncation flags, the fit-calculation method and its documented limitations, and the manufacturer-typical-specs caveat.

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 meaning the schema does not carry: 'type' is accepted in any letter case, as the ISO size-type code ('45G1') or the short name form ('40HC'), and an unknown value errors with the valid slugs plus the closest match. It also clarifies that item dims together trigger the fit calculation and weight caps it by max payload.

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?

The opening sentence states a specific verb and resource ('Get ISO shipping-container specifications, with optional load-fit maths') and immediately scopes coverage to 10 named container types. It is clearly distinguishable from siblings like uld_lookup (air freight) and validate (check digits), which the description also names explicitly.

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?

It gives explicit mode-selection rules: provide 'type' for one record, omit it to list all 10, add item dimensions to get a load-fit calculation. The 'Related' block routes the agent away from this tool for adjacent jobs (validate for ISO 6346 numbers, cbm/consignment calculators for cargo volume filled, uld_lookup for the air equivalent), with the distinguishing condition stated for each.

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