FreightUtils MCP Server

validate

Read-onlyIdempotent

Verify freight identifiers against public check-digit algorithms: ISO 6346 containers, IATA AWB numbers and IMO ship IDs. Parse text or verify a single value.

Instructions

Validate and parse freight identifiers by their public check-digit algorithms: shipping container numbers (ISO 6346), air waybill (AWB) numbers (IATA modulus-7) and IMO ship identification numbers.

Two modes: pass text= to find and validate every identifier in it (e.g. a booking-email line), OR pass value= + type=<container|awb|imo> to validate one.

Behavior: deterministic check-digit arithmetic; per identifier found it reports type, the normalised form, valid (pass/fail), expected vs actual check digit, and details (container: owner prefix + equipment category; AWB: airline prefix + the airline from the AWB-prefix dataset when ONE record holds the prefix — when several do (e.g. 020: Lufthansa and Lufthansa Cargo), airline is null and airline_candidates[] lists every holder with airline_note saying why, never a guessed carrier; IMO: the 7-digit number); text mode with no identifiers found returns an empty found[] with a note. Rate-limited: a limit error carries reset_at, the UTC time the allowance resets.

Returns: found[] (each entry with its own _source naming the standard applied) and disclaimer under result, plus confidence, _source and citation (the FreightUtils v1 response envelope).

Limitations: STRUCTURAL ONLY — a valid check digit means well-formed, NOT that the container, shipment or vessel exists or is active; not a registry or tracking lookup.

Related: container_lookup (container TYPE specs, not numbers), airline_lookup (the AWB-prefix dataset the airline resolution uses).

Input Schema

TableJSON Schema

Name	Required	Description
`text`	No	Arbitrary string to scan for container / AWB / IMO identifiers (parse mode). Provide this OR value+type. Example: "2 cntrs MSKU3068808 / TGHU7654325 on AWB 176-12345675".
`type`	No	Identifier type for value: container = ISO 6346, awb = IATA air waybill, imo = IMO ship number.
`value`	No	A single identifier to validate (typed mode). Requires type — value without type is refused. Example: "MSKU3068808".

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

changedInput schema / properties / value / description

Previous value: -"A single identifier to validate (typed mode). Requires type. Example: \"MSKU3068808\"."New value: +"A single identifier to validate (typed mode). Requires type — value without type is refused. Example: \"MSKU3068808\"."

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

Changed17 schema fields changedv2.11.0Jul 10, 2026

changedInput schema / properties / text / description

Previous value: -"Arbitrary string to scan for container / AWB / IMO identifiers (parse mode). Provide this OR value+type."New value: +"Arbitrary string to scan for container / AWB / IMO identifiers (parse mode). Provide this OR value+type. Example: \"2 cntrs MSKU3068808 / TGHU7654325 on AWB 176-12345675\"."

changedInput schema / properties / type / description

Previous value: -"Identifier type for value: container = ISO 6346, awb = IATA Air Waybill, imo = IMO ship number."New value: +"Identifier type for value: container = ISO 6346, awb = IATA air waybill, imo = IMO ship number."

changedInput schema / properties / value / description

Previous value: -"A single identifier to validate (typed mode). Requires type."New value: +"A single identifier to validate (typed mode). Requires type. Example: \"MSKU3068808\"."

addedOutput schema / properties / _source

Added value: +{
+  "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"
+}

addedOutput schema / properties / blocking_errors

Added value: +{
+  "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"
+}

addedOutput schema / properties / citation

Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "qualifier": {
+      "type": "string"
+    },
+    "text": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "text"
+  ],
+  "type": "object"
+}

addedOutput schema / properties / confidence

Added value: +{
+  "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"
+}

removedOutput schema / properties / disclaimer
```
Removed value: -{
-  "type": "string"
-}
```

addedOutput schema / properties / envelope_version

Added value: +{
+  "const": "1",
+  "type": "string"
+}

removedOutput schema / properties / found

Removed value: -{
-  "items": {
-    "additionalProperties": false,
-    "properties": {
-      "_source": {
-        "additionalProperties": false,
-        "properties": {
-          "authority": {
-            "type": "string"
-          },
-          "computed_by": {
-            "type": "string"
-          },
-          "reference": {
-            "type": "string"
-          },
-          "source_url": {
-            "type": "string"
-          },
-          "standard": {
-            "type": "string"
-          },
-          "type": {
-            "type": "string"
-          }
-        },
-        "required": [
-          "type",
-          "standard",
-          "reference",
-          "authority",
-          "source_url",
-          "computed_by"
-        ],
-        "type": "object"
-      },
-      "check_digit": {
-        "additionalProperties": false,
-        "properties": {
-          "actual": {
-            "type": [
-              "number",
-              "null"
-            ]
-          },
-          "expected": {
-            "type": [
-              "number",
-              "null"
-            ]
-          }
-        },
-        "required": [
-          "expected",
-          "actual"
-        ],
-        "type": "object"
-      },
-      "details": {
-        "additionalProperties": {},
-        "type": "object"
-      },
-      "normalised": {
-        "type": "string"
-      },
-      "raw": {
-        "type": "string"
-      },
-      "type": {
-        "type": "string"
-      },
-      "valid": {
-        "type": "boolean"
-      }
-    },
-    "required": [
-      "type",
-      "raw",
-      "normalised",
-      "valid",
-      "check_digit",
-      "details",
-      "_source"
-    ],
-    "type": "object"
-  },
-  "type": "array"
-}

addedOutput schema / properties / normalized_input

Added value: +{
+  "additionalProperties": {},
+  "type": "object"
+}

removedOutput schema / properties / note

Removed value: -{
-  "type": "string"
-}

addedOutput schema / properties / ok
```
Added value: +{
+  "type": "boolean"
+}
```

addedOutput schema / properties / result

Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": true,
+      "properties": {
+        "disclaimer": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "found": {
+          "anyOf": [
+            {
+              "items": {
+                "additionalProperties": true,
+                "properties": {
+                  "_source": {
+                    "anyOf": [
+                      {
+                        "additionalProperties": {},
+                        "type": "object"
+                      },
+                      {
+                        "type": "null"
+                      }
+                    ]
+                  },
+                  "check_digit": {
+                    "anyOf": [
+                      {
+                        "additionalProperties": {},
+                        "type": "object"
+                      },
+                      {
+                        "type": "null"
+                      }
+                    ]
+                  },
+                  "details": {
+                    "anyOf": [
+                      {
+                        "additionalProperties": {},
+                        "type": "object"
+                      },
+                      {
+                        "type": "null"
+                      }
+                    ]
+                  },
+                  "normalised": {
+                    "type": [
+                      "string",
+                      "null"
+                    ]
+                  },
+                  "raw": {
+                    "type": [
+                      "string",
+                      "null"
+                    ]
+                  },
+                  "type": {
+                    "type": [
+                      "string",
+                      "null"
+                    ]
+                  },
+                  "valid": {
+                    "type": [
+                      "boolean",
+                      "null"
+                    ]
+                  }
+                },
+                "type": "object"
+              },
+              "type": "array"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "note": {
+          "type": [
+            "string",
+            "null"
+          ]
+        }
+      },
+      "type": "object"
+    },
+    {
+      "additionalProperties": {},
+      "type": "object"
+    }
+  ]
+}

addedOutput schema / properties / validity

Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "as_of": {
+      "type": "string"
+    },
+    "effective_from": {
+      "type": "string"
+    },
+    "effective_to": {
+      "type": [
+        "string",
+        "null"
+      ]
+    }
+  },
+  "required": [
+    "as_of"
+  ],
+  "type": "object"
+}

addedOutput schema / properties / warnings

Added value: +{
+  "items": {
+    "additionalProperties": false,
+    "properties": {
+      "code": {
+        "type": "string"
+      },
+      "details": {
+        "additionalProperties": {},
+        "type": "object"
+      },
+      "message": {
+        "type": "string"
+      }
+    },
+    "required": [
+      "code",
+      "message"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}

changedOutput schema / required

Previous value: -[
-  "found",
-  "disclaimer"
-]New value: +[
+  "envelope_version",
+  "ok",
+  "result",
+  "confidence",
+  "_source",
+  "citation"
+]

Addedv2.10.0Jun 24, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Annotations already establish read-only, idempotent, non-destructive and closed-world, so the bar is lower; the description still adds substantial behavioral context: deterministic check-digit arithmetic, per-identifier reporting fields, the ambiguous-airline-prefix resolution rule (airline null plus airline_candidates[] rather than a guess), empty-result behavior, rate limiting with reset_at, and the FreightUtils v1 response envelope.

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 modes, then behavior, returns, limitations and related tools in clearly labelled blocks. It is long, but nearly every sentence carries non-redundant information for a multi-mode validator, so it is dense rather than padded.

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 three-parameter validator with an output schema, the description covers everything an agent needs: mode selection, enum values, resolution edge cases, empty results, rate-limit signaling, and the structural-only limitation. The existence of an output schema means return-value detail is a bonus rather than a requirement, and it is supplied anyway.

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 the schema already documents all three parameters, the enum, the 'value requires type' constraint and examples. The description restates the mode split but adds no syntax or semantic detail beyond what the schema provides; baseline 3 is appropriate.

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 (validate/parse) and resource (freight identifiers), enumerating the three standards (ISO 6346, IATA modulus-7, IMO) it applies. It also explicitly distinguishes itself from siblings by noting container_lookup is about container TYPE specs rather than numbers, and airline_lookup is the prefix dataset used for resolution.

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 lays out the two mutually exclusive modes (text=<arbitrary string> to scan, or value=<identifier> + type=<enum> for one) with a concrete example for each. It names the related tools and the condition that separates them, and adds a clear when-not statement ('STRUCTURAL ONLY — not a registry or tracking lookup').

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