FreightUtils MCP Server

hs_code_lookup

Read-onlyIdempotent

Search HS 2022 commodity codes by description, 2–6 digit code, or section to classify goods for customs. Returns six-digit international codes with hierarchy and confidence.

Instructions

Search 6,940 WCO Harmonized System (HS 2022) commodity codes — the 6-digit international customs classification layer. The first 2 digits are the chapter, 4 the heading, 6 the subheading.

Provide ONE of: query (free-text description search, min 2 chars), code (2-6 digit lookup, written with or without dots or spaces — "8471.30" is 847130 — returns the code plus its hierarchy), or section (Roman numeral I-XXI to browse a section).

Behavior: read-only; description search runs first against the HS 2022 descriptions (UN Comtrade H6); when none contains the words, it falls back to the UK Trade Tariff search references (HMRC's index of everyday goods names), so "laptop" finds 847130 and "computers" finds heading 8471. A fallback match is medium confidence: matched_via names HMRC's index, the citation asks you to confirm the code, and the formal tariff wording ("automatic data processing machines") stays the surest search. count 0 with an empty results[] is still a valid answer when neither finds the words. Rate-limited: a limit error carries reset_at, the UTC time the allowance resets.

Returns: the query/code echo, count and results[] (hscode, description and hierarchy context) under result, plus confidence, _source and citation (the FreightUtils v1 response envelope).

Limitations: the 6-digit international level only — national tariff lines (8-10 digits) and duty rates are set per country; classification here is indicative, not a binding ruling.

Related: uk_duty_calculator (duty/VAT for a code found here), ics2_check (EU ENS goods-description quality — a different check entirely).

Input Schema

Name	Required	Description
`code`	No	Exact HS code or prefix — 2, 4 or 6 digits, with or without dots or spaces. Examples: "8471", "8471.30".
`codes`	No	Batch: up to 50 HS codes. Send alone; answered as results[] in input order, each with its own status. One call against the daily limit, N against the Pro monthly allowance.
`query`	No	Search words (min 2 chars), matched against the official HS descriptions first, then HMRC everyday goods names (medium confidence). Examples: "automatic data", "laptop".
`section`	No	Browse a section by Roman numeral I-XXI. Example: "XVI" (machinery).

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.

Changed5 schema fields changedv2.27.0Oct 31, 2026

addedInput schema / properties / codes

Added value: +{
+  "description": "Batch: up to 50 HS codes. Send alone; answered as results[] in input order, each with its own status. One call against the daily limit, N against the Pro monthly allowance.",
+  "items": {
+    "maxLength": 14,
+    "type": "string"
+  },
+  "maxItems": 50,
+  "minItems": 1,
+  "type": "array"
+}

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

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": {
-      "code": {
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "count": {
-        "type": [
-          "number",
-          "null"
-        ]
-      },
-      "meta": {
-        "anyOf": [
-          {
-            "additionalProperties": {},
-            "type": "object"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "query": {
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "results": {
-        "anyOf": [
-          {
-            "items": {
-              "additionalProperties": {},
-              "type": "object"
-            },
-            "type": "array"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "section": {
-        "type": [
-          "string",
-          "null"
-        ]
-      }
-    },
-    "type": "object"
-  },
-  {
-    "additionalProperties": {},
-    "type": "object"
-  }
-]New value: +[
+  {
+    "additionalProperties": {},
+    "properties": {
+      "code": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "count": {
+        "type": [
+          "number",
+          "null"
+        ]
+      },
+      "meta": {
+        "anyOf": [
+          {
+            "additionalProperties": {},
+            "propertyNames": {
+              "type": "string"
+            },
+            "type": "object"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "query": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "results": {
+        "anyOf": [
+          {
+            "items": {
+              "additionalProperties": {},
+              "propertyNames": {
+                "type": "string"
+              },
+              "type": "object"
+            },
+            "type": "array"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "section": {
+        "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"
+}
```

Changed3 schema fields changedv2.22.3Oct 14, 2026

changedInput schema / properties / code / description

Previous value: -"Exact HS code or prefix — 2, 4 or 6 digits. Example: \"8471\"."New value: +"Exact HS code or prefix — 2, 4 or 6 digits, with or without dots or spaces. Examples: \"8471\", \"8471.30\"."

removedInput schema / properties / code / pattern
```
Removed value: -"^\\d{2,6}$"
```

changedInput schema / properties / query / description

Previous value: -"Keyword search on official HS descriptions (min 2 chars). Formal tariff wording works best. Example: \"automatic data\" rather than \"laptop\"."New value: +"Search words (min 2 chars), matched against the official HS descriptions first, then HMRC everyday goods names (medium confidence). Examples: \"automatic data\", \"laptop\"."

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

Changed4 schema fields changedv2.11.0Jul 10, 2026

changedInput schema / properties / code / description

Previous value: -"Exact HS code lookup (2-6 digits)"New value: +"Exact HS code or prefix — 2, 4 or 6 digits. Example: \"8471\"."

changedInput schema / properties / query / description

Previous value: -"Search by product description (min 2 chars)"New value: +"Keyword search on official HS descriptions (min 2 chars). Formal tariff wording works best. Example: \"automatic data\" rather than \"laptop\"."

changedInput schema / properties / section / description

Previous value: -"Browse by section (Roman numeral I–XXI, e.g., \"II\")"New value: +"Browse a section by Roman numeral I-XXI. Example: \"XVI\" (machinery)."

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": {
+            "code": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "count": {
+              "type": [
+                "number",
+                "null"
+              ]
+            },
+            "meta": {
+              "anyOf": [
+                {
+                  "additionalProperties": {},
+                  "type": "object"
+                },
+                {
+                  "type": "null"
+                }
+              ]
+            },
+            "query": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "results": {
+              "anyOf": [
+                {
+                  "items": {
+                    "additionalProperties": {},
+                    "type": "object"
+                  },
+                  "type": "array"
+                },
+                {
+                  "type": "null"
+                }
+              ]
+            },
+            "section": {
+              "type": [
+                "string",
+                "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"
+}

Changed4 schema fields changedv2.5.0Jun 22, 2026
- addedInput schema / properties / code / pattern
```
Added value: +"^\\d{2,6}$"
```
- addedInput schema / properties / query / minLength
```
Added value: +2
```
- changedInput schema / properties / section / description
```
Previous value: -"Browse by section (Roman numeral, e.g., \"II\")"New value: +"Browse by section (Roman numeral I–XXI, e.g., \"II\")"
```
- addedInput schema / properties / section / pattern
```
Added value: +"^[ivxIVX]{1,5}$"
```
First observedv1.0.0Apr 3, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Goes well beyond the annotations: discloses the two-tier search fallback (HS 2022 first, then HMRC UK Trade Tariff index), what 'medium confidence' and matched_via mean, that count 0 with empty results[] is a valid answer, and that rate-limit errors carry reset_at. The annotations already cover read-only/idempotence, so this is pure added behavioral value.

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 resource and scope, then cleanly segmented into Provide / Behavior / Returns / Limitations / Related. Slightly long and includes light redundancy (the chapter/heading/subheading explainer) but every block is scannable and purposeful.

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?

Complete for a read-only lookup: input modes, fallback semantics, rate-limit behavior, confidence interpretation, the 6-digit limitation versus national tariff lines, and explicit sibling routing are all covered. Even though an output schema exists, the description correctly frames how to read confidence and empty results.

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: the query fallback and its confidence implications ('laptop' → 847130), the accept-with-dots normalization, and that count 0 is not an error. It still omits any mention of the `codes` batch parameter's semantics.

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 (search), resource (6,940 WCO HS 2022 commodity codes) and scope (the 6-digit international layer), and names the sibling tools it is not (uk_duty_calculator, ics2_check). An agent can distinguish it from the other lookup siblings 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?

Explicitly enumerates three input modes (query / code / section) with the condition that selects each, and routes to the duty calculator and ICS2 check. However, it says 'Provide ONE of' the three named params while the schema declares a fourth routing mode, the batch `codes` array, which the description never mentions — a gap that could steer an agent away from batching.

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