Skip to main content
Glama
Sign In

FreightUtils MCP Server

by io.github.SoapyRED
OverviewDiscussionsAdmin

Nearest Airport

nearest_airport
Read-onlyIdempotent

Find the airports nearest to a caller-provided latitude/longitude, sorted by great-circle (haversine) distance with distance_km on each result. Searches 86,248 airports (OurAirports, public domain).

Provide latitude and longitude (decimal degrees); optional radius_km, max_results (1-50, default 10), type filter (e.g. large_airport only) and include_all. By default only airports with scheduled airline service and an IATA code are ranked — never a heliport or a closed field; include_all: true ranks every type except closed fields, and type filters on that type. Coordinates are INPUT only — nothing is stored or logged.

Behavior: deterministic distance sort; confidence reflects proximity and airport size (a large airport within 25 km scores high; closed/heliport/seaplane results cap lower). This tool does NOT geocode place names and does NOT compute routes — pass coordinates you already hold. Rate-limited: a limit error carries reset_at, the UTC time the allowance resets.

Returns: count, results[] (the airport record plus distance_km), distance_basis ("great_circle"), filter (scheduled_iata / all / type) and filter_description under result, plus confidence, _source and citation (the FreightUtils v1 response envelope).

Limitations: reference data only — not for navigation; verify codes with IATA / ICAO.

Related: airport_lookup (exact code or name lookup, no distance), unlocode_lookup (named transport-location search).

Identifiers: Each record carries fu_id, a stable FreightUtils identifier (and fu_version_id where the dataset has editions); resolve_reference resolves one to exactly its record.

Input Schema

NameRequiredDescriptionDefault
typeNoOptional filter by airport type
latitudeYesLatitude in decimal degrees (-90 to 90)
longitudeYesLongitude in decimal degrees (-180 to 180)
radius_kmNoOptional maximum distance in kilometres
include_allNoDefault false: only airports with scheduled airline service and an IATA code (no heliports). true: every airport type except closed fields.
max_resultsNoMax results to return (1–50, default 10)

Output Schema

NameRequiredDescriptionDefault
okYes
_metaNo
as_ofNo
resultYes
statusNo
_sourceYes
editionNo
citationYes
validityNo
warningsNo
confidenceYes
missing_inputsNo
blocking_errorsNo
envelope_versionYes
normalized_inputNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • addedOutput schema / properties / _meta / properties / upstream
      Added value: +{
+  "additionalProperties": {},
+  "properties": {
+    "datasets": {
+      "additionalProperties": {
+        "additionalProperties": {},
+        "properties": {
+          "kind": {
+            "anyOf": [
+              {
+                "enum": [
+                  "watched",
+                  "checksum-only",
+                  "manual"
+                ],
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "last_success": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "reason": {
+            "type": "string"
+          },
+          "stale": {
+            "type": "boolean"
+          },
+          "state": {
+            "enum": [
+              "in_step",
+              "changed_upstream",
+              "schema_drift",
+              "unreachable",
+              "window_missed",
+              "unknown"
+            ],
+            "type": "string"
+          },
+          "window_days": {
+            "type": [
+              "number",
+              "null"
+            ]
+          }
+        },
+        "required": [
+          "state",
+          "kind",
+          "last_success",
+          "window_days",
+          "stale"
+        ],
+        "type": "object"
+      },
+      "propertyNames": {
+        "type": "string"
+      },
+      "type": "object"
+    },
+    "stale": {
+      "type": "boolean"
+    },
+    "state": {
+      "enum": [
+        "in_step",
+        "changed_upstream",
+        "schema_drift",
+        "unreachable",
+        "window_missed",
+        "unknown"
+      ],
+      "type": "string"
+    },
+    "state_read_at": {
+      "type": [
+        "string",
+        "null"
+      ]
+    }
+  },
+  "required": [
+    "state",
+    "stale",
+    "state_read_at",
+    "datasets"
+  ],
+  "type": "object"
+}
  2. Changed1 schema field changed
    • addedOutput schema / properties / _meta / properties / ids
      Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "pattern": {
+      "type": "string"
+    },
+    "scheme": {
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    }
+  },
+  "required": [
+    "scheme",
+    "pattern"
+  ],
+  "type": "object"
+}
  3. Changed2 schema fields changed
    • removedOutput schema / properties / _meta / properties / receipt / properties / reason / const
      Removed value: -"key_required"
    • addedOutput schema / properties / _meta / properties / receipt / properties / reason / enum
      Added value: +[
+  "key_required",
+  "quota"
+]
  4. Changed1 schema field changed
    • addedInput schema / properties / include_all
      Added value: +{
+  "description": "Default false: only airports with scheduled airline service and an IATA code (no heliports). true: every airport type except closed fields.",
+  "type": "boolean"
+}
  5. Changed1 schema field changed
    • 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"
+}
  6. Changed1 schema field changed
    • addedOutput schema / properties / _meta / properties / edition_basis
      Added value: +{
+  "type": "string"
+}
  7. Changed1 schema field changed
    • addedOutput schema / properties / _meta
      Added value: +{
+  "additionalProperties": {},
+  "properties": {
+    "check_id": {
+      "type": "string"
+    },
+    "receipt_url": {
+      "type": "string"
+    }
+  },
+  "type": "object"
+}
  8. Changed5 schema fields changed
    • addedOutput schema / properties / as_of
      Added value: +{
+  "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+  "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 / status
      Added value: +{
+  "enum": [
+    "ok",
+    "partial",
+    "not_found",
+    "unsupported",
+    "ambiguous"
+  ],
+  "type": "string"
+}
  9. Changed2 schema fields changed
    • removedOutput schema / properties / validity / properties / effective_to / anyOf
      Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
    • addedOutput schema / properties / validity / properties / effective_to / type
      Added value: +[
+  "string",
+  "null"
+]
  10. Changed1 schema field changed
    • addedInput schema / additionalProperties
      Added value: +false
  11. Changed5 schema fields changed
    • 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"
+]
  12. Changed18 schema fields changed
    • changedOutput schema / properties / _source / additionalProperties
      Previous value: -{
-  "type": "string"
-}New value: +false
    • removedOutput schema / properties / _source / description
      Removed value: -"Provenance envelope (OurAirports, cross-checked)"
    • addedOutput schema / properties / _source / properties
      Added value: +{
+  "checked": {
+    "type": "string"
+  },
+  "name": {
+    "type": "string"
+  },
+  "provenance_status": {
+    "enum": [
+      "verified",
+      "pending-verification",
+      "computed",
+      "live"
+    ],
+    "type": "string"
+  },
+  "source_url": {
+    "type": "string"
+  }
+}
    • removedOutput schema / properties / _source / propertyNames
      Removed value: -{
-  "type": "string"
-}
    • addedOutput schema / properties / _source / required
      Added value: +[
+  "name",
+  "checked",
+  "provenance_status"
+]
    • addedOutput schema / properties / blocking_errors
      Added value: +{
+  "items": {
+    "additionalProperties": false,
+    "properties": {
+      "code": {
+        "type": "string"
+      },
+      "message": {
+        "type": "string"
+      },
+      "recovery": {
+        "additionalProperties": false,
+        "properties": {
+          "action": {
+            "type": "string"
+          },
+          "params": {
+            "additionalProperties": {},
+            "propertyNames": {
+              "type": "string"
+            },
+            "type": "object"
+          },
+          "tool": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "action"
+        ],
+        "type": "object"
+      }
+    },
+    "required": [
+      "code",
+      "message",
+      "recovery"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}
    • addedOutput schema / properties / citation
      Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "qualifier": {
+      "type": "string"
+    },
+    "text": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "text"
+  ],
+  "type": "object"
+}
    • addedOutput schema / properties / confidence
      Added value: +{
+  "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"
+}
    • removedOutput schema / properties / count
      Removed value: -{
-  "type": "number"
-}
    • removedOutput schema / properties / disclaimer
      Removed value: -{
-  "type": "string"
-}
    • addedOutput schema / properties / envelope_version
      Added value: +{
+  "const": "1",
+  "type": "string"
+}
    • addedOutput schema / properties / normalized_input
      Added value: +{
+  "additionalProperties": {},
+  "propertyNames": {
+    "type": "string"
+  },
+  "type": "object"
+}
    • addedOutput schema / properties / ok
      Added value: +{
+  "type": "boolean"
+}
    • addedOutput schema / properties / result
      Added value: +{
+  "additionalProperties": {},
+  "propertyNames": {
+    "type": "string"
+  },
+  "type": "object"
+}
    • removedOutput schema / properties / results
      Removed value: -{
-  "description": "Nearest airports, ascending by distance_km",
-  "items": {
-    "additionalProperties": false,
-    "properties": {
-      "country": {
-        "description": "ISO 3166-1 alpha-2 country code",
-        "type": "string"
-      },
-      "country_name": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "distance_km": {
-        "description": "Great-circle distance from the query point, km",
-        "type": "number"
-      },
-      "elevation_ft": {
-        "anyOf": [
-          {
-            "type": "number"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "iata_code": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "description": "IATA 3-letter code (null if none)"
-      },
-      "ident": {
-        "description": "ICAO / OurAirports ident",
-        "type": "string"
-      },
-      "latitude": {
-        "type": "number"
-      },
-      "longitude": {
-        "type": "number"
-      },
-      "municipality": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "name": {
-        "type": "string"
-      },
-      "region": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "description": "Region / subdivision (readable)"
-      },
-      "type": {
-        "description": "large_airport | medium_airport | small_airport | heliport | closed | seaplane_base",
-        "type": "string"
-      }
-    },
-    "required": [
-      "ident",
-      "iata_code",
-      "name",
-      "type",
-      "municipality",
-      "region",
-      "country",
-      "country_name",
-      "latitude",
-      "longitude",
-      "elevation_ft",
-      "distance_km"
-    ],
-    "type": "object"
-  },
-  "type": "array"
-}
    • addedOutput schema / properties / validity
      Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "as_of": {
+      "type": "string"
+    },
+    "effective_from": {
+      "type": "string"
+    },
+    "effective_to": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    }
+  },
+  "required": [
+    "as_of"
+  ],
+  "type": "object"
+}
    • addedOutput schema / properties / warnings
      Added value: +{
+  "items": {
+    "additionalProperties": false,
+    "properties": {
+      "code": {
+        "type": "string"
+      },
+      "details": {
+        "additionalProperties": {},
+        "propertyNames": {
+          "type": "string"
+        },
+        "type": "object"
+      },
+      "message": {
+        "type": "string"
+      }
+    },
+    "required": [
+      "code",
+      "message"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}
    • changedOutput schema / required
      Previous value: -[
-  "count",
-  "results",
-  "disclaimer",
-  "_source"
-]New value: +[
+  "envelope_version",
+  "ok",
+  "result",
+  "confidence",
+  "_source",
+  "citation"
+]
  13. Added

TDQS

A4.8/5.0
Behavior5/5

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

Beyond the annotations (which only declare read-only/idempotent/non-destructive), it discloses the default ranking rule (scheduled service + IATA only, never heliports or closed fields), how confidence is computed and capped, the rate-limit failure mode with reset_at, and that coordinates are input only with no storage or logging. These are substantive operational details an agent could not get from the structured fields.

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 the core purpose, then cleanly partitioned into Behavior, Returns, Limitations and Related sections. There is mild redundancy in restating the heliport/closed-field exclusion twice and the Returns list partly duplicates the output schema, but no sentence is truly wasted.

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 6-parameter read-only lookup with an output schema, everything an agent needs is present: input units and ranges, filtering defaults, determinism, error behavior, confidence interpretation, and reference-data caveats. The fu_id/citation note covers identifier traceability even though the return shape itself is carried by the output schema.

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 already 100%, so the baseline is 3, but the description adds real meaning: the interplay between include_all and type ('ranks every type except closed fields, and type filters on that type') and the default scheduled-service/IATA scoping are not obvious from the schema alone. It doesn't add anything on radius_km or max_results beyond the schema, which keeps it short of 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?

States a specific verb and resource ('Find the airports nearest to a caller-provided latitude/longitude') plus the ranking method (haversine, distance_km per result) and corpus size (86,248 OurAirports records). It is immediately distinguishable from airport_lookup, which is described as an exact code/name lookup with no distance.

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?

Explicitly defines the preconditions ('Provide latitude and longitude'), the exclusions ('does NOT geocode place names and does NOT compute routes — pass coordinates you already hold'), and names the correct sibling for the alternative task ('airport_lookup (exact code or name lookup, no distance)'). Nothing about when to choose this tool is left to inference.

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

All FreightUtils MCP Server toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources