FreightUtils MCP Server

validate

Read-onlyIdempotent

Check and parse freight identifiers—container (ISO 6346), air waybill (IATA), and IMO—using public check-digit algorithms, scanning free text or a single typed 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

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; or "consignment" with the consignment argument.
`value`	No	A single identifier to validate (typed mode). Requires type — value without type is refused. Example: "MSKU3068808".
`consignment`	No	With type "consignment": the consignment object to validate. The answer says whether it is valid and which checks it carries the inputs for.

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.

Changed8 schema fields changedv2.27.0Oct 31, 2026

addedInput schema / properties / consignment

Added value: +{
+  "additionalProperties": {},
+  "description": "With type \"consignment\": the consignment object to validate. The answer says whether it is valid and which checks it carries the inputs for.",
+  "propertyNames": {
+    "type": "string"
+  },
+  "type": "object"
+}

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; or \"consignment\" with the consignment argument."

changedInput schema / properties / type / enum

Previous value: -[
-  "container",
-  "awb",
-  "imo"
-]New value: +[
+  "container",
+  "awb",
+  "imo",
+  "consignment"
+]

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

changedOutput schema / properties / result / anyOf

Previous value: -[
-  {
-    "additionalProperties": {},
-    "properties": {
-      "disclaimer": {
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "found": {
-        "anyOf": [
-          {
-            "items": {
-              "additionalProperties": {},
-              "properties": {
-                "_source": {
-                  "anyOf": [
-                    {
-                      "additionalProperties": {},
-                      "propertyNames": {
-                        "type": "string"
-                      },
-                      "type": "object"
-                    },
-                    {
-                      "type": "null"
-                    }
-                  ]
-                },
-                "check_digit": {
-                  "anyOf": [
-                    {
-                      "additionalProperties": {},
-                      "propertyNames": {
-                        "type": "string"
-                      },
-                      "type": "object"
-                    },
-                    {
-                      "type": "null"
-                    }
-                  ]
-                },
-                "details": {
-                  "anyOf": [
-                    {
-                      "additionalProperties": {},
-                      "propertyNames": {
-                        "type": "string"
-                      },
-                      "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": {},
-    "propertyNames": {
-      "type": "string"
-    },
-    "type": "object"
-  }
-]New value: +[
+  {
+    "additionalProperties": {},
+    "properties": {
+      "disclaimer": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "failure": {
+        "anyOf": [
+          {
+            "additionalProperties": {},
+            "properties": {
+              "example": {
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "expected_format": {
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "message": {
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "reason": {
+                "anyOf": [
+                  {
+                    "enum": [
+                      "INVALID_CHECK_DIGIT",
+                      "WRONG_LENGTH",
+                      "BAD_CHARSET",
+                      "UNKNOWN_PREFIX",
+                      "UNSUPPORTED_TYPE",
+                      "AMBIGUOUS"
+                    ],
+                    "type": "string"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ]
+              }
+            },
+            "type": "object"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "found": {
+        "anyOf": [
+          {
+            "items": {
+              "additionalProperties": {},
+              "properties": {
+                "_source": {
+                  "anyOf": [
+                    {
+                      "additionalProperties": {},
+                      "propertyNames": {
+                        "type": "string"
+                      },
+                      "type": "object"
+                    },
+                    {
+                      "type": "null"
+                    }
+                  ]
+                },
+                "check_digit": {
+                  "anyOf": [
+                    {
+                      "additionalProperties": {},
+                      "propertyNames": {
+                        "type": "string"
+                      },
+                      "type": "object"
+                    },
+                    {
+                      "type": "null"
+                    }
+                  ]
+                },
+                "details": {
+                  "anyOf": [
+                    {
+                      "additionalProperties": {},
+                      "propertyNames": {
+                        "type": "string"
+                      },
+                      "type": "object"
+                    },
+                    {
+                      "type": "null"
+                    }
+                  ]
+                },
+                "failure": {
+                  "anyOf": [
+                    {
+                      "additionalProperties": {},
+                      "properties": {
+                        "example": {
+                          "type": [
+                            "string",
+                            "null"
+                          ]
+                        },
+                        "expected_format": {
+                          "type": [
+                            "string",
+                            "null"
+                          ]
+                        },
+                        "message": {
+                          "type": [
+                            "string",
+                            "null"
+                          ]
+                        },
+                        "reason": {
+                          "anyOf": [
+                            {
+                              "enum": [
+                                "INVALID_CHECK_DIGIT",
+                                "WRONG_LENGTH",
+                                "BAD_CHARSET",
+                                "UNKNOWN_PREFIX",
+                                "UNSUPPORTED_TYPE",
+                                "AMBIGUOUS"
+                              ],
+                              "type": "string"
+                            },
+                            {
+                              "type": "null"
+                            }
+                          ]
+                        }
+                      },
+                      "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": {},
+    "propertyNames": {
+      "type": "string"
+    },
+    "type": "object"
+  }
+]

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": {
-      "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"
-  }
-]New value: +[
+  {
+    "additionalProperties": {},
+    "properties": {
+      "disclaimer": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "found": {
+        "anyOf": [
+          {
+            "items": {
+              "additionalProperties": {},
+              "properties": {
+                "_source": {
+                  "anyOf": [
+                    {
+                      "additionalProperties": {},
+                      "propertyNames": {
+                        "type": "string"
+                      },
+                      "type": "object"
+                    },
+                    {
+                      "type": "null"
+                    }
+                  ]
+                },
+                "check_digit": {
+                  "anyOf": [
+                    {
+                      "additionalProperties": {},
+                      "propertyNames": {
+                        "type": "string"
+                      },
+                      "type": "object"
+                    },
+                    {
+                      "type": "null"
+                    }
+                  ]
+                },
+                "details": {
+                  "anyOf": [
+                    {
+                      "additionalProperties": {},
+                      "propertyNames": {
+                        "type": "string"
+                      },
+                      "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": {},
+    "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"
+}
```

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.8/5.0

Behavior5/5

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

Annotations already cover safety (readOnly, idempotent, closed-world), yet the description still adds substantial behavior: deterministic check-digit arithmetic, per-identifier result fields, the airline ambiguity policy (null airline + airline_candidates[] rather than a guessed carrier), empty-state behavior (empty found[] with a note), and rate-limit reset_at semantics. It also declares the STRUCTURAL ONLY limitation, which is critical to prevent misuse as a registry or tracking lookup.

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, then modes, behavior, returns, limitations, related — a strong scan order. Slightly long, and the 'Returns:' section partially repeats what the behavior paragraph already says about per-identifier fields, which is the main reason it isn't 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 validator with nested objects and 4 optional params, everything an agent needs is present: both invocation modes, the structural-only caveat, ambiguity handling, empty results, and rate-limit signaling. With an output schema present, the description need not explain the envelope, yet it does so briefly without bloating.

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 baseline is 3. The description adds mode-selection semantics that go beyond field-level docs — the OR relationship between text and value+type, and value-without-type being refused — plus what each result entry reports per type (container owner prefix, AWB airline prefix). It does not cover the consignment object that appears in the schema enum, leaving that path under-explained.

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 ('Validate and parse freight identifiers') and enumerates the three standards (ISO 6346, IATA modulus-7, IMO). The Related line explicitly distinguishes it from container_lookup (type specs, not numbers) and airline_lookup, so an agent can route without opening a schema.

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 frames two modes with the exact argument combinations: text=<arbitrary string> for scanning free text, OR value=<identifier> + type=<container|awb|imo> for a single check. Gives a concrete motivating scenario (booking-email line) and names the sibling tools it is not.

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