FreightUtils MCP Server

unlocode_lookup

Read-onlyIdempotent

Look up UN/LOCODE transport locations by exact code or name search, filtering by country and function, to retrieve port, airport, rail, road, ICD, or border records.

Instructions

Search 116,232 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

TableJSON Schema

Name	Required	Description
`code`	No	Exact UN/LOCODE — 5 characters, optionally spaced. Examples: "GBLHR", "GB LHR", "NLRTM".
`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

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.

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

Behavior5/5

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

Annotations cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description still adds substantive behavior: exact hits are provenance-based while fuzzy name hits carry confidence via envelope basis match_quality, an unknown code produces a not-found error, and rate limiting surfaces reset_at (UTC reset time). The 116,232-record fixed list also corroborates openWorldHint=false rather than contradicting it.

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 code format, then clearly sectioned into invocation, behavior, returns and limitations. It is dense and mostly earns its length, but the 'Returns:' block partially duplicates the existing output schema and could be trimmed.

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 5-parameter lookup with full schema coverage, annotations and an output schema, this description covers everything an agent needs: what it is, how to call it, error and rate-limit behavior, and the authoritative-source caveat about confirming operational status. Nothing material 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 baseline is 3, but the description adds real value beyond it: the spaced notation rule ('GB LHR' resolves to GBLHR), the min-2-char query constraint, and the limit default/max. It stops short of explaining how code and query interact when both are supplied, or how country/function_type behave on a mass name match.

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 (search the UN/LOCODE transport-location list) and immediately scopes the domain with the code format and concrete examples (GBLHR, NLRTM). It explicitly differentiates itself from the two closest siblings, airport_lookup and nearest_airport, so an agent can route without opening schemas.

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?

Gives the two invocation modes (exact `code` vs. `query` name search) and the narrowing filters (country, function_type, limit). The 'Related:' line names both alternatives and the condition that selects each (airport-specific records with ICAO codes; coordinate-based airport search), which is the explicit routing an agent needs.

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