FreightUtils MCP Server

airline_lookup

Read-onlyIdempotent

Search 6,356 airlines by name, IATA code, ICAO code, AWB prefix, or country to identify carriers and verify the airline behind an air waybill.

Instructions

Search 6,356 airlines by name, IATA code, ICAO code, AWB prefix, or country. AWB prefixes are the first 3 digits of an air waybill number and identify the issuing carrier (e.g. 176 = Emirates).

Provide ONE parameter: query is a ranked fuzzy search across names and codes; iata / icao / prefix / country are exact filters.

Behavior: read-only; fuzzy query hits report their match quality through the envelope's confidence (basis match_quality, score 0-1) with a FUZZY_BEST_MATCH advisory naming the matched field; a query that contains no name falls back to the closest names in the dataset ("Emirats" → Emirates). A query or country answer is a list: summary rows, 25 per page, with total, truncated and next_offset (full: true for full records); an iata / icao / prefix answer is the holder records in full. Rate-limited: a limit error carries reset_at, the UTC time the allowance resets.

Returns: count and results[] — per airline: airline_name, iata_code, icao_code, awb_prefix[], callsign, country, has_cargo and verification fields (aliases and sources in full records) — under result, plus confidence, _source and citation (the FreightUtils v1 response envelope).

Limitations: this dataset's provenance is pending independent verification (the envelope's provenance_status says so) — confirm operationally critical codes with IATA/ICAO or the carrier.

Related: airport_lookup (searches AIRPORTS, not carriers), validate (checks an AWB number's check digit and names its airline from this dataset when one record holds the prefix, otherwise lists the candidates).

Input Schema

Name	Required	Description
`full`	No	Lists only: true returns full records (provenance, sources, rationale) instead of summary rows, five per page by default. A single-record call always returns the full record.
`iata`	No	Exact IATA code — 2 alphanumeric characters. Examples: "EK", "U2".
`icao`	No	Exact ICAO code — 3 letters. Examples: "UAE", "BAW".
`limit`	No	Lists only: rows per page (default: every summary row; 5 with full: true).
`query`	No	Ranked fuzzy search across name, codes, prefix and country (min 2 chars). Example: "emirates".
`offset`	No	Lists only: rows to skip (default 0). The response gives total and next_offset.
`prefix`	No	Exact AWB prefix — the first 3 digits of an air waybill. Example: "176".
`country`	No	Filter by country name (min 2 chars). Example: "Netherlands".

Output 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.

Changed3 schema fields changedv2.22.3Oct 14, 2026

addedInput schema / properties / full

Added value: +{
+  "description": "Lists only: true returns full records (provenance, sources, rationale) instead of summary rows, five per page by default. A single-record call always returns the full record.",
+  "type": "boolean"
+}

addedInput schema / properties / limit

Added value: +{
+  "description": "Lists only: rows per page (default: every summary row; 5 with full: true).",
+  "maximum": 100,
+  "minimum": 1,
+  "type": "integer"
+}

addedInput schema / properties / offset

Added value: +{
+  "description": "Lists only: rows to skip (default 0). The response gives total and next_offset.",
+  "maximum": 9007199254740991,
+  "minimum": 0,
+  "type": "integer"
+}

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

Previous value: -"Filter by country name (min 2 chars)"New value: +"Filter by country name (min 2 chars). Example: \"Netherlands\"."

changedInput schema / properties / iata / description

Previous value: -"Exact IATA code (2 alphanumeric chars)"New value: +"Exact IATA code — 2 alphanumeric characters. Examples: \"EK\", \"U2\"."

changedInput schema / properties / icao / description

Previous value: -"Exact ICAO code (3 letters)"New value: +"Exact ICAO code — 3 letters. Examples: \"UAE\", \"BAW\"."

changedInput schema / properties / prefix / description

Previous value: -"AWB prefix (3 digits, e.g., \"176\")"New value: +"Exact AWB prefix — the first 3 digits of an air waybill. Example: \"176\"."

changedInput schema / properties / query / description

Previous value: -"General search (name, code, prefix, or country — min 2 chars)"New value: +"Ranked fuzzy search across name, codes, prefix and country (min 2 chars). Example: \"emirates\"."

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": {
+            "count": {
+              "type": [
+                "number",
+                "null"
+              ]
+            },
+            "meta": {
+              "anyOf": [
+                {
+                  "additionalProperties": {},
+                  "type": "object"
+                },
+                {
+                  "type": "null"
+                }
+              ]
+            },
+            "results": {
+              "anyOf": [
+                {
+                  "items": {
+                    "additionalProperties": true,
+                    "properties": {
+                      "airline_name": {
+                        "type": [
+                          "string",
+                          "null"
+                        ]
+                      },
+                      "aliases": {
+                        "anyOf": [
+                          {
+                            "items": {
+                              "type": "string"
+                            },
+                            "type": "array"
+                          },
+                          {
+                            "type": "null"
+                          }
+                        ]
+                      },
+                      "audited_at": {
+                        "type": [
+                          "string",
+                          "null"
+                        ]
+                      },
+                      "awb_prefix": {
+                        "anyOf": [
+                          {
+                            "items": {
+                              "type": "string"
+                            },
+                            "type": "array"
+                          },
+                          {
+                            "type": "null"
+                          }
+                        ]
+                      },
+                      "callsign": {
+                        "type": [
+                          "string",
+                          "null"
+                        ]
+                      },
+                      "country": {
+                        "type": [
+                          "string",
+                          "null"
+                        ]
+                      },
+                      "has_cargo": {
+                        "type": [
+                          "boolean",
+                          "null"
+                        ]
+                      },
+                      "iata_code": {
+                        "type": [
+                          "string",
+                          "null"
+                        ]
+                      },
+                      "icao_code": {
+                        "type": [
+                          "string",
+                          "null"
+                        ]
+                      },
+                      "slug": {
+                        "type": [
+                          "string",
+                          "null"
+                        ]
+                      },
+                      "verified": {
+                        "type": [
+                          "boolean",
+                          "null"
+                        ]
+                      }
+                    },
+                    "type": "object"
+                  },
+                  "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"
+}

Changed8 schema fields changedv2.5.0Jun 22, 2026
- changedInput schema / properties / iata / description
```
Previous value: -"Exact IATA code (2 chars, e.g., \"EK\")"New value: +"Exact IATA code (2 alphanumeric chars)"
```
- removedInput schema / properties / iata / maxLength
```
Removed value: -2
```
- removedInput schema / properties / iata / minLength
```
Removed value: -2
```
- addedInput schema / properties / iata / pattern
```
Added value: +"^[A-Za-z0-9]{2}$"
```
- changedInput schema / properties / icao / description
```
Previous value: -"Exact ICAO code (3 chars, e.g., \"UAE\")"New value: +"Exact ICAO code (3 letters)"
```
- removedInput schema / properties / icao / maxLength
```
Removed value: -3
```
- removedInput schema / properties / icao / minLength
```
Removed value: -3
```
- addedInput schema / properties / icao / pattern
```
Added value: +"^[A-Za-z]{3}$"
```
Changed7 schema fields changedv2.1.1May 17, 2026
- addedInput schema / properties / country / minLength
```
Added value: +2
```
- addedInput schema / properties / iata / maxLength
```
Added value: +2
```
- addedInput schema / properties / iata / minLength
```
Added value: +2
```
- addedInput schema / properties / icao / maxLength
```
Added value: +3
```
- addedInput schema / properties / icao / minLength
```
Added value: +3
```
- addedInput schema / properties / prefix / pattern
```
Added value: +"^\\d{3}$"
```
- addedInput schema / properties / query / minLength
```
Added value: +2
```
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 (which only declare read-only/idempotent/non-destructive) by disclosing fuzzy-match confidence semantics, the FUZZY_BEST_MATCH advisory, no-name fallback behavior with a concrete example, pagination row counts, full-vs-summary behavior, and a rate limit whose error carries reset_at. It also flags the provenance caveat.

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-loads purpose and is organized into Behavior, Returns, Limitations and Related blocks. It is on the long side, and the 'Returns' enumeration of per-airline fields is largely redundant given a structured output schema exists, but the content is dense and each block earns its place.

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 an 8-parameter, no-required-params lookup with annotations and an output schema, the description covers purpose, invocation mode, fuzzy/fallback semantics, pagination, rate limiting, and a data-provenance limitation. 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 baseline is 3, but the description adds real meaning: it explains that query is a ranked fuzzy search while iata/icao/prefix/country are exact filters, and defines the AWB prefix concept (first 3 digits of an air waybill, e.g. 176 = Emirates). The 'Provide ONE parameter' constraint is also semantics not in 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 and resource (search airlines) plus the exact search dimensions (name, IATA, ICAO, AWB prefix, country) and the dataset size. It also names sibling tools it is NOT (airport_lookup searches airports, not carriers), so an agent can distinguish it without opening a 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 tells the agent to provide ONE parameter and splits usage semantics into fuzzy (query) vs exact (iata/icao/prefix/country), which is actionable guidance. The Related section names the alternative tools and their distinct scopes, though it stops short of a full when-not-this-tool-rule.

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