FreightUtils MCP Server

uk_duty_calculator

Read-onlyIdempotent

Estimate UK import duty and VAT for a 10-digit commodity code using live GOV.UK Trade Tariff rates, with CIF value and origin country.

Instructions

Estimate UK import duty and VAT for a commodity code using the LIVE GOV.UK Trade Tariff — rates are fetched per request, not from a static table. The CIF value is composed from customs_value + freight_cost + insurance_cost; duty = CIF x the duty rate for the origin country; VAT (typically 20%) applies on the duty-inclusive value.

Provide commodity_code (a declarable 10-digit code), origin_country (ISO-2) and customs_value in GBP; freight_cost, insurance_cost and incoterm are optional refinements.

Behavior: live lookup plus deterministic arithmetic on the returned rate; a 6- or 8-digit code is refused — never padded with zeros to a code you did not send — with declarable_codes, the 10-digit codes beneath it in the UK Trade Tariff (610910 → 6109100010, 6109100090); an origin that is not an ISO 3166-1 country is refused; origin-dependent measures the tariff cannot resolve automatically surface in warnings. Rate-limited: a limit error carries reset_at, the UTC time the allowance resets.

Returns: commodity_code and description, origin country, cif_value, duty_rate (+ percent), duty_amount, vat_rate, vat_amount, total_import_taxes, total_landed_cost and warnings under result (amounts in GBP); validity.as_of marks the live-rate timestamp; 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).

Limitations: an estimate, not a customs ruling — excise, quotas, anti-dumping measures, reliefs and origin-proof requirements can change the outcome; confirm with a customs broker or HMRC before relying on it.

Related: hs_code_lookup (find the 6-digit code first), incoterms_lookup (who actually pays these costs).

Input Schema

TableJSON Schema

Name	Required	Description
`incoterm`	No	Incoterms 2020 basis of the customs_value — documents which costs are already included.
`freight_cost`	No	Freight cost in GBP, 0 or more — added to the CIF value. Default: 0.
`customs_value`	Yes	Goods value in GBP. Example: 1000.
`commodity_code`	Yes	UK tariff commodity code — the declarable 10 digits. Example: "8471300000" (portable computers). A 6- or 8-digit code is refused with the declarable codes beneath it.
`insurance_cost`	No	Insurance cost in GBP, 0 or more — added to the CIF value. Default: 0.
`origin_country`	Yes	ISO 2-letter country of origin. Examples: "CN", "DE", "US".

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.

Changed6 schema fields changedv2.22.3Oct 14, 2026

changedInput schema / properties / commodity_code / description

Previous value: -"HS/UK tariff code, 6-10 digits. Example: \"8471300000\" (portable computers). 6-digit codes may need the declarable 8/10-digit line."New value: +"UK tariff commodity code — the declarable 10 digits. Example: \"8471300000\" (portable computers). A 6- or 8-digit code is refused with the declarable codes beneath it."

changedInput schema / properties / commodity_code / pattern

Previous value: -"^\\d{6,10}$"New value: +"^[\\d\\s]{6,14}$"

changedInput schema / properties / freight_cost / description

Previous value: -"Freight cost in GBP — added to the CIF value. Default: 0."New value: +"Freight cost in GBP, 0 or more — added to the CIF value. Default: 0."

addedInput schema / properties / freight_cost / minimum
```
Added value: +0
```

changedInput schema / properties / insurance_cost / description

Previous value: -"Insurance cost in GBP — added to the CIF value. Default: 0."New value: +"Insurance cost in GBP, 0 or more — added to the CIF value. Default: 0."

addedInput schema / properties / insurance_cost / minimum
```
Added value: +0
```

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

Previous value: -"HS/tariff code (6–10 digits, e.g., \"847989\")"New value: +"HS/UK tariff code, 6-10 digits. Example: \"8471300000\" (portable computers). 6-digit codes may need the declarable 8/10-digit line."

changedInput schema / properties / customs_value / description

Previous value: -"Goods value in GBP"New value: +"Goods value in GBP. Example: 1000."

changedInput schema / properties / freight_cost / description

Previous value: -"Freight cost in GBP (added to CIF value)"New value: +"Freight cost in GBP — added to the CIF value. Default: 0."

changedInput schema / properties / incoterm / description

Previous value: -"Incoterm basis"New value: +"Incoterms 2020 basis of the customs_value — documents which costs are already included."

changedInput schema / properties / insurance_cost / description

Previous value: -"Insurance cost in GBP (added to CIF value)"New value: +"Insurance cost in GBP — added to the CIF value. Default: 0."

changedInput schema / properties / origin_country / description

Previous value: -"ISO 2-letter origin country code (e.g., \"CN\", \"DE\")"New value: +"ISO 2-letter country of origin. Examples: \"CN\", \"DE\", \"US\"."

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": {
+            "cif_value": {
+              "type": [
+                "number",
+                "null"
+              ]
+            },
+            "commodity_code": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "commodity_description": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "disclaimer": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "duty_amount": {
+              "type": [
+                "number",
+                "null"
+              ]
+            },
+            "duty_rate": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "duty_rate_percent": {
+              "type": [
+                "number",
+                "null"
+              ]
+            },
+            "origin_country": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "origin_country_name": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "source": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "total_import_taxes": {
+              "type": [
+                "number",
+                "null"
+              ]
+            },
+            "total_landed_cost": {
+              "type": [
+                "number",
+                "null"
+              ]
+            },
+            "vat_amount": {
+              "type": [
+                "number",
+                "null"
+              ]
+            },
+            "vat_rate": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "vat_rate_percent": {
+              "type": [
+                "number",
+                "null"
+              ]
+            },
+            "warnings": {
+              "anyOf": [
+                {
+                  "items": {},
+                  "type": "array"
+                },
+                {
+                  "type": "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"
+}

Changed5 schema fields changedv2.5.0Jun 22, 2026
- changedInput schema / properties / incoterm / description
```
Previous value: -"Incoterm (e.g., \"FOB\", \"CIF\", \"EXW\")"New value: +"Incoterm basis"
```
- addedInput schema / properties / incoterm / enum
```
Added value: +[
+  "EXW",
+  "FCA",
+  "FAS",
+  "FOB",
+  "CFR",
+  "CIF",
+  "CPT",
+  "CIP",
+  "DAP",
+  "DPU",
+  "DDP"
+]
```
- removedInput schema / properties / origin_country / maxLength
```
Removed value: -2
```
- removedInput schema / properties / origin_country / minLength
```
Removed value: -2
```
- changedInput schema / properties / origin_country / pattern
```
Previous value: -"^[A-Z]{2}$"New value: +"^[A-Za-z]{2}$"
```
Addedv2.1.1May 17, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds substantial value beyond them: live per-request rate fetching, refusal of 6-/8-digit codes with declarable_codes returned, refusal of non-ISO origins, origin-dependent measures surfacing as warnings, and a rate-limit error carrying reset_at. This is exactly the behavioral disclosure an agent needs.

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 formula, then behavior, returns, limitations, and related tools in a scannable structure. It is dense but nearly every sentence carries distinct operational information; the snake_case/camelCase endpoint note is the one mildly tangential addition.

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?

A complex, revenue-relevant calculation tool with a live external dependency, and the description covers computation, failure modes, rate limiting, return envelope semantics, and explicit limitations (excise, quotas, anti-dumping, not a customs ruling). Combined with the output schema and annotations, 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.

Parameters4/5

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

Schema coverage is 100%, so the schema already documents all six parameters and the baseline is 3. The description goes further by explaining the CIF composition formula (customs_value + freight_cost + insurance_cost), the duty and VAT arithmetic, and the role of incoterm as documenting which costs are already included.

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+resource (estimate UK import duty and VAT for a commodity code) and immediately distinguishes itself from its siblings by naming hs_code_lookup and incoterms_lookup and their roles. An agent knows exactly what this tool computes and when it is the right choice.

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?

Gives a clear workflow prerequisite (hs_code_lookup to find the 6-digit code first) and marks which parameters are required vs optional refinements. It never states an explicit when-not-to-use case (e.g. duty-only or VAT-only scenarios), so it falls short of a clean 5.

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