FreightUtils MCP Server

unlocode_lookup

Read-onlyIdempotent

Look up UN/LOCODE transport locations worldwide by exact code or name to retrieve ports, airports, rail/road terminals, ICDs, and border crossings with country and function filters.

Instructions

Search 116,086 UN/LOCODE transport locations worldwide — ports, airports, rail and road terminals, inland container depots and border crossings. Codes are 5 characters: a 2-letter ISO country code + a 3-character location code (GBLHR = London Heathrow, NLRTM = Rotterdam).

Provide code for an exact record, or query (name search, min 2 chars) optionally narrowed by country and function_type; limit caps results (default 20, max 100). The spaced notation "GB LHR" reads as GBLHR in either.

Behavior: read-only; exact code hits are provenance-based while fuzzy name hits report match quality via the envelope's confidence (basis match_quality); an unknown code errors with a not-found message. Rate-limited: a limit error carries reset_at, the UTC time the allowance resets.

Returns: the location record(s) — code, name and name_ascii, country, subdivision, functions[], status, coordinates {lat, lon} and iata_code where assigned — under result, plus confidence, _source and citation (the FreightUtils v1 response envelope).

Limitations: an administrative code list (UNECE UN/LOCODE 2025-1) — confirm operational status and coordinates with the port or authority before critical use.

Related: airport_lookup (airport-specific records including ICAO codes), nearest_airport (find airports by coordinates).

Input Schema

Name	Required	Description
`code`	No	Exact UN/LOCODE — 5 characters, optionally spaced. Examples: "GBLHR", "GB LHR", "NLRTM".
`codes`	No	Batch: up to 50 UN/LOCODEs. 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.
`limit`	No	Maximum results. Default: 20, max: 100.
`query`	No	Location name search (min 2 chars). Examples: "rotterdam", "heathrow".
`country`	No	Filter by 2-letter ISO country code. Examples: "GB", "NL".
`function_type`	No	Filter by location function.

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 UN/LOCODEs. 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": {
-      "audited_at": {
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "code": {
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "coordinates": {
-        "anyOf": [
-          {
-            "additionalProperties": true,
-            "properties": {
-              "lat": {
-                "type": [
-                  "number",
-                  "null"
-                ]
-              },
-              "lon": {
-                "type": [
-                  "number",
-                  "null"
-                ]
-              }
-            },
-            "type": "object"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "count": {
-        "type": [
-          "number",
-          "null"
-        ]
-      },
-      "country": {
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "functions": {
-        "anyOf": [
-          {
-            "items": {
-              "type": "string"
-            },
-            "type": "array"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "iata_code": {
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "location_code": {
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "name": {
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "name_ascii": {
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "results": {
-        "anyOf": [
-          {
-            "items": {},
-            "type": "array"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "status": {
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "subdivision": {
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "verified": {
-        "type": [
-          "boolean",
-          "null"
-        ]
-      }
-    },
-    "type": "object"
-  },
-  {
-    "additionalProperties": {},
-    "type": "object"
-  }
-]New value: +[
+  {
+    "additionalProperties": {},
+    "properties": {
+      "audited_at": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "code": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "coordinates": {
+        "anyOf": [
+          {
+            "additionalProperties": {},
+            "properties": {
+              "lat": {
+                "type": [
+                  "number",
+                  "null"
+                ]
+              },
+              "lon": {
+                "type": [
+                  "number",
+                  "null"
+                ]
+              }
+            },
+            "type": "object"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "count": {
+        "type": [
+          "number",
+          "null"
+        ]
+      },
+      "country": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "functions": {
+        "anyOf": [
+          {
+            "items": {
+              "type": "string"
+            },
+            "type": "array"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "iata_code": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "location_code": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "name": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "name_ascii": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "results": {
+        "anyOf": [
+          {
+            "items": {},
+            "type": "array"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "status": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "subdivision": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "verified": {
+        "type": [
+          "boolean",
+          "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"
+}
```

Changed2 schema fields changedv2.22.3Oct 14, 2026

changedInput schema / properties / code / description

Previous value: -"Exact UN/LOCODE — 5 characters. Examples: \"GBLHR\", \"NLRTM\"."New value: +"Exact UN/LOCODE — 5 characters, optionally spaced. Examples: \"GBLHR\", \"GB LHR\", \"NLRTM\"."

changedInput schema / properties / code / pattern

Previous value: -"^[A-Za-z0-9]{5}$"New value: +"^\\s*[A-Za-z]{2}[\\s-]?[A-Za-z0-9]{3}\\s*$"

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

Changed6 schema fields changedv2.11.0Jul 10, 2026

changedInput schema / properties / code / description

Previous value: -"Exact UN/LOCODE lookup (e.g., \"GBLHR\", \"NLRTM\")"New value: +"Exact UN/LOCODE — 5 characters. Examples: \"GBLHR\", \"NLRTM\"."

changedInput schema / properties / country / description

Previous value: -"Filter by country code (e.g., \"GB\", \"NL\")"New value: +"Filter by 2-letter ISO country code. Examples: \"GB\", \"NL\"."

changedInput schema / properties / function_type / description

Previous value: -"Filter by location function"New value: +"Filter by location function."

changedInput schema / properties / limit / description

Previous value: -"Max results (default: 20, max: 100)"New value: +"Maximum results. Default: 20, max: 100."

changedInput schema / properties / query / description

Previous value: -"Search by location name (e.g., \"rotterdam\", \"heathrow\")"New value: +"Location name search (min 2 chars). Examples: \"rotterdam\", \"heathrow\"."

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": {
+            "audited_at": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "code": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "coordinates": {
+              "anyOf": [
+                {
+                  "additionalProperties": true,
+                  "properties": {
+                    "lat": {
+                      "type": [
+                        "number",
+                        "null"
+                      ]
+                    },
+                    "lon": {
+                      "type": [
+                        "number",
+                        "null"
+                      ]
+                    }
+                  },
+                  "type": "object"
+                },
+                {
+                  "type": "null"
+                }
+              ]
+            },
+            "count": {
+              "type": [
+                "number",
+                "null"
+              ]
+            },
+            "country": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "functions": {
+              "anyOf": [
+                {
+                  "items": {
+                    "type": "string"
+                  },
+                  "type": "array"
+                },
+                {
+                  "type": "null"
+                }
+              ]
+            },
+            "iata_code": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "location_code": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "name": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "name_ascii": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "results": {
+              "anyOf": [
+                {
+                  "items": {},
+                  "type": "array"
+                },
+                {
+                  "type": "null"
+                }
+              ]
+            },
+            "status": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "subdivision": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "verified": {
+              "type": [
+                "boolean",
+                "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"
+}

Changed8 schema fields changedv2.5.0Jun 22, 2026

removedInput schema / properties / code / maxLength
```
Removed value: -5
```
removedInput schema / properties / code / minLength
```
Removed value: -5
```

changedInput schema / properties / code / pattern

Previous value: -"^[A-Z0-9]{5}$"New value: +"^[A-Za-z0-9]{5}$"

removedInput schema / properties / country / maxLength
```
Removed value: -2
```
removedInput schema / properties / country / minLength
```
Removed value: -2
```

changedInput schema / properties / country / pattern

Previous value: -"^[A-Z]{2}$"New value: +"^[A-Za-z]{2}$"

removedInput schema / properties / function

Removed value: -{
-  "description": "Filter by function: port, airport, rail, road, icd, border",
-  "type": "string"
-}

addedInput schema / properties / function_type

Added value: +{
+  "description": "Filter by location function",
+  "enum": [
+    "port",
+    "airport",
+    "rail",
+    "road",
+    "icd",
+    "border"
+  ],
+  "type": "string"
+}

Addedv2.1.1May 17, 2026

TDQS

A4.4/5.0

Behavior5/5

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

Annotations only cover the read-only/idempotent profile, and the description adds substantial behavior beyond them: exact hits are provenance-based while fuzzy hits report match quality via envelope confidence, unknown codes produce a not-found error, and rate-limit errors carry reset_at. It also flags the data as an administrative code list that shouldn't be trusted for operational status without authority confirmation.

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 what and scope, then modes, then behavior, errors and limitations — a sensible order with little waste. The 'Returns:' paragraph partly duplicates the existing output schema, though the envelope and confidence context still adds value.

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 six-parameter, zero-required lookup with an output schema, the description covers invocation modes, error semantics, rate limiting, data provenance caveats and sibling routing. An agent has everything needed to call it correctly and interpret failures.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

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

Schema description coverage is 100%, so the baseline is 3; the description's main added value is the note that spaced notation 'GB LHR' resolves to GBLHR either way, plus the limit default/max which the schema already states. It never mentions the `codes` batch parameter (up to 50, answered as results[] in input order), leaving that mode entirely to the schema.

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 with scope: search 116,086 UN/LOCODE transport locations, enumerating the location types covered. It also explains the code structure (2-letter ISO + 3-char location, with GBLHR/NLRTM examples), which lets an agent distinguish it from airport_lookup and other lookup siblings.

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 two clear invocation modes (exact `code` vs. `query` name search narrowed by country/function_type) and routes airport-specific needs to airport_lookup and coordinate-based needs to nearest_airport. It lacks an explicit 'do not use for X' exclusion, but the context needed to pick this tool is complete.

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