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 inputs to calculate landed cost.

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

Name	Required	Description
`lines`	No	Batch: up to 10 lines, each { commodity_code, origin_country, customs_value, freight_cost?, insurance_cost?, incoterm? }. Send alone; answered as results[] in input order, each line its own receipt. One call against the daily limit, N against the Pro monthly allowance.
`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`	No	Goods value in GBP. Required unless lines[] is sent. Example: 1000.
`commodity_code`	No	Required unless lines[] is sent. 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`	No	Required unless lines[] is sent. ISO 2-letter country of origin. Examples: "CN", "DE", "US".

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.

Changed9 schema fields changedv2.27.0Oct 31, 2026

changedInput schema / properties / commodity_code / description

Previous 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."New value: +"Required unless lines[] is sent. 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 / customs_value / description

Previous value: -"Goods value in GBP. Example: 1000."New value: +"Goods value in GBP. Required unless lines[] is sent. Example: 1000."

addedInput schema / properties / lines

Added value: +{
+  "description": "Batch: up to 10 lines, each { commodity_code, origin_country, customs_value, freight_cost?, insurance_cost?, incoterm? }. Send alone; answered as results[] in input order, each line its own receipt. One call against the daily limit, N against the Pro monthly allowance.",
+  "items": {
+    "additionalProperties": {},
+    "propertyNames": {
+      "type": "string"
+    },
+    "type": "object"
+  },
+  "maxItems": 10,
+  "minItems": 1,
+  "type": "array"
+}

changedInput schema / properties / origin_country / description

Previous value: -"ISO 2-letter country of origin. Examples: \"CN\", \"DE\", \"US\"."New value: +"Required unless lines[] is sent. ISO 2-letter country of origin. Examples: \"CN\", \"DE\", \"US\"."

removedInput schema / required

Removed value: -[
-  "commodity_code",
-  "origin_country",
-  "customs_value"
-]

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": {
-      "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"
-  }
-]New value: +[
+  {
+    "additionalProperties": {},
+    "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": {},
+    "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"
+}
```

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

A3.7/5.0

Behavior1/5

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

The description says rates are fetched live per request from GOV.UK, which is an external open-world interaction. The annotations declare openWorldHint=false, so the description directly contradicts that structured signal. Despite otherwise rich disclosure of refusals, warnings and rate limits, this contradiction forces a 1 under the rules.

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?

The description is front-loaded and well organized into behavior, returns, limitations and related tools. It is somewhat long and includes a detailed Returns section that is partly redundant with the output schema, plus envelope/casing notes that are not essential for invocation.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex live-rate calculator, the description covers the core workflow, refusals, warnings, rate limiting, limitations and related tools, and the output schema handles return fields. The main gap is that the batch `lines` mode is only documented in the schema, not in the description, and the live-fetch behavior conflicts with openWorldHint.

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 useful meaning beyond the schema by explaining how CIF is composed, how duty is calculated, and how VAT applies. It does omit the batch `lines` parameter from the prose, which keeps it from being a 5.

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 description states a specific verb and resource: estimate UK import duty and VAT for a commodity code using the live GOV.UK Trade Tariff. It clearly distinguishes this from related lookup tools by naming hs_code_lookup and incoterms_lookup as adjacent steps.

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?

It gives clear invocation guidance for commodity_code, origin_country and customs_value, explains optional refinements, and points to hs_code_lookup and incoterms_lookup for related needs. However, it does not explain the batch `lines` mode in prose, nor does it explicitly state when to choose this tool over every relevant sibling.

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

uk_duty_calculator

Instructions

Input Schema

Output Schema

Schema Changelog

TDQS

Other Tools