Skip to main content
Glama
Sign In
FreightUtils MCP Server

FreightUtils MCP Server

by SoapyRED
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

nearest_airport

Read-onlyIdempotent

Locates airports near a given latitude/longitude, sorted by great-circle distance, defaulting to scheduled IATA-service airports.

Instructions

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

Input Schema

NameRequiredDescriptionDefault
typeNoOptional filter by airport type. Example: "large_airport".
latitudeYesLatitude in decimal degrees (-90 to 90). Example: 51.47.
longitudeYesLongitude in decimal degrees (-180 to 180). Example: -0.4543.
radius_kmNoMaximum distance in kilometres — omit for no radius cap.
include_allNoDefault false: only airports with scheduled airline service and an IATA code (no heliports). true: every airport type except closed fields.
max_resultsNoMaximum results (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. Changed6 schema fields changedv2.27.0
    • 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"
+}
    • 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"
+}
    • changedOutput schema / properties / result / anyOf
      Previous value: -[
-  {
-    "additionalProperties": {},
-    "properties": {
-      "count": {
-        "type": [
-          "number",
-          "null"
-        ]
-      },
-      "disclaimer": {
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "meta": {
-        "anyOf": [
-          {
-            "additionalProperties": {},
-            "propertyNames": {
-              "type": "string"
-            },
-            "type": "object"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "results": {
-        "anyOf": [
-          {
-            "items": {
-              "additionalProperties": {},
-              "properties": {
-                "country": {
-                  "type": [
-                    "string",
-                    "null"
-                  ]
-                },
-                "country_name": {
-                  "type": [
-                    "string",
-                    "null"
-                  ]
-                },
-                "elevation_ft": {
-                  "type": [
-                    "number",
-                    "null"
-                  ]
-                },
-                "iata_code": {
-                  "type": [
-                    "string",
-                    "null"
-                  ]
-                },
-                "ident": {
-                  "type": [
-                    "string",
-                    "null"
-                  ]
-                },
-                "latitude": {
-                  "type": [
-                    "number",
-                    "null"
-                  ]
-                },
-                "longitude": {
-                  "type": [
-                    "number",
-                    "null"
-                  ]
-                },
-                "municipality": {
-                  "type": [
-                    "string",
-                    "null"
-                  ]
-                },
-                "name": {
-                  "type": [
-                    "string",
-                    "null"
-                  ]
-                },
-                "region": {
-                  "type": [
-                    "string",
-                    "null"
-                  ]
-                },
-                "type": {
-                  "type": [
-                    "string",
-                    "null"
-                  ]
-                }
-              },
-              "type": "object"
-            },
-            "type": "array"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      }
-    },
-    "type": "object"
-  },
-  {
-    "additionalProperties": {},
-    "propertyNames": {
-      "type": "string"
-    },
-    "type": "object"
-  }
-]New value: +[
+  {
+    "additionalProperties": {},
+    "properties": {
+      "count": {
+        "type": [
+          "number",
+          "null"
+        ]
+      },
+      "disclaimer": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "distance_basis": {
+        "anyOf": [
+          {
+            "const": "great_circle",
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "filter": {
+        "anyOf": [
+          {
+            "enum": [
+              "scheduled_iata",
+              "all",
+              "type"
+            ],
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "filter_description": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "meta": {
+        "anyOf": [
+          {
+            "additionalProperties": {},
+            "propertyNames": {
+              "type": "string"
+            },
+            "type": "object"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "results": {
+        "anyOf": [
+          {
+            "items": {
+              "additionalProperties": {},
+              "properties": {
+                "country": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                },
+                "country_name": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                },
+                "elevation_ft": {
+                  "type": [
+                    "number",
+                    "null"
+                  ]
+                },
+                "gps_code": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                },
+                "iata_code": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                },
+                "icao_code": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                },
+                "ident": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                },
+                "iso_region": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                },
+                "keywords": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                },
+                "latitude": {
+                  "type": [
+                    "number",
+                    "null"
+                  ]
+                },
+                "longitude": {
+                  "type": [
+                    "number",
+                    "null"
+                  ]
+                },
+                "municipality": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                },
+                "name": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                },
+                "region": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                },
+                "scheduled_service": {
+                  "type": [
+                    "boolean",
+                    "null"
+                  ]
+                },
+                "type": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                }
+              },
+              "type": "object"
+            },
+            "type": "array"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      }
+    },
+    "type": "object"
+  },
+  {
+    "additionalProperties": {},
+    "propertyNames": {
+      "type": "string"
+    },
+    "type": "object"
+  }
+]
  2. Changed10 schema fields changedv2.24.0
    • 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": {
-      "count": {
-        "type": [
-          "number",
-          "null"
-        ]
-      },
-      "disclaimer": {
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "meta": {
-        "anyOf": [
-          {
-            "additionalProperties": {},
-            "type": "object"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "results": {
-        "anyOf": [
-          {
-            "items": {
-              "additionalProperties": true,
-              "properties": {
-                "country": {
-                  "type": [
-                    "string",
-                    "null"
-                  ]
-                },
-                "country_name": {
-                  "type": [
-                    "string",
-                    "null"
-                  ]
-                },
-                "elevation_ft": {
-                  "type": [
-                    "number",
-                    "null"
-                  ]
-                },
-                "iata_code": {
-                  "type": [
-                    "string",
-                    "null"
-                  ]
-                },
-                "ident": {
-                  "type": [
-                    "string",
-                    "null"
-                  ]
-                },
-                "latitude": {
-                  "type": [
-                    "number",
-                    "null"
-                  ]
-                },
-                "longitude": {
-                  "type": [
-                    "number",
-                    "null"
-                  ]
-                },
-                "municipality": {
-                  "type": [
-                    "string",
-                    "null"
-                  ]
-                },
-                "name": {
-                  "type": [
-                    "string",
-                    "null"
-                  ]
-                },
-                "region": {
-                  "type": [
-                    "string",
-                    "null"
-                  ]
-                },
-                "type": {
-                  "type": [
-                    "string",
-                    "null"
-                  ]
-                }
-              },
-              "type": "object"
-            },
-            "type": "array"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      }
-    },
-    "type": "object"
-  },
-  {
-    "additionalProperties": {},
-    "type": "object"
-  }
-]New value: +[
+  {
+    "additionalProperties": {},
+    "properties": {
+      "count": {
+        "type": [
+          "number",
+          "null"
+        ]
+      },
+      "disclaimer": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "meta": {
+        "anyOf": [
+          {
+            "additionalProperties": {},
+            "propertyNames": {
+              "type": "string"
+            },
+            "type": "object"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "results": {
+        "anyOf": [
+          {
+            "items": {
+              "additionalProperties": {},
+              "properties": {
+                "country": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                },
+                "country_name": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                },
+                "elevation_ft": {
+                  "type": [
+                    "number",
+                    "null"
+                  ]
+                },
+                "iata_code": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                },
+                "ident": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                },
+                "latitude": {
+                  "type": [
+                    "number",
+                    "null"
+                  ]
+                },
+                "longitude": {
+                  "type": [
+                    "number",
+                    "null"
+                  ]
+                },
+                "municipality": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                },
+                "name": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                },
+                "region": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                },
+                "type": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                }
+              },
+              "type": "object"
+            },
+            "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"
+}
  3. Changed5 schema fields changedv2.17.2
    • 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"
+]
  4. Changed29 schema fields changedv2.11.0
    • changedInput schema / properties / latitude / description
      Previous value: -"Latitude in decimal degrees (-90 to 90)"New value: +"Latitude in decimal degrees (-90 to 90). Example: 51.47."
    • changedInput schema / properties / longitude / description
      Previous value: -"Longitude in decimal degrees (-180 to 180)"New value: +"Longitude in decimal degrees (-180 to 180). Example: -0.4543."
    • changedInput schema / properties / max_results / description
      Previous value: -"Max results to return (1-50, default 10)"New value: +"Maximum results (1-50). Default: 10."
    • changedInput schema / properties / radius_km / description
      Previous value: -"Optional maximum distance in kilometres"New value: +"Maximum distance in kilometres — omit for no radius cap."
    • changedInput schema / properties / type / description
      Previous value: -"Optional filter by airport type"New value: +"Optional filter by airport type. Example: \"large_airport\"."
    • removedOutput schema / properties / _source / properties / authority
      Removed value: -{
-  "type": "string"
-}
    • addedOutput schema / properties / _source / properties / checked
      Added value: +{
+  "type": "string"
+}
    • removedOutput schema / properties / _source / properties / data_vintage
      Removed value: -{
-  "type": "string"
-}
    • removedOutput schema / properties / _source / properties / dataset
      Removed value: -{
-  "type": "string"
-}
    • removedOutput schema / properties / _source / properties / licence
      Removed value: -{
-  "type": "string"
-}
    • addedOutput schema / properties / _source / properties / name
      Added value: +{
+  "type": "string"
+}
    • addedOutput schema / properties / _source / properties / provenance_status
      Added value: +{
+  "enum": [
+    "verified",
+    "pending-verification",
+    "computed",
+    "live"
+  ],
+  "type": "string"
+}
    • removedOutput schema / properties / _source / properties / retrieved_via
      Removed value: -{
-  "type": "string"
-}
    • removedOutput schema / properties / _source / properties / type
      Removed value: -{
-  "type": "string"
-}
    • changedOutput schema / properties / _source / required
      Previous value: -[
-  "type",
-  "authority"
-]New 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": {},
+            "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"
+}
    • removedOutput schema / properties / meta
      Removed value: -{
-  "additionalProperties": {},
-  "type": "object"
-}
    • addedOutput schema / properties / normalized_input
      Added value: +{
+  "additionalProperties": {},
+  "type": "object"
+}
    • addedOutput schema / properties / ok
      Added value: +{
+  "type": "boolean"
+}
    • addedOutput schema / properties / result
      Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": true,
+      "properties": {
+        "count": {
+          "type": [
+            "number",
+            "null"
+          ]
+        },
+        "disclaimer": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "meta": {
+          "anyOf": [
+            {
+              "additionalProperties": {},
+              "type": "object"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "results": {
+          "anyOf": [
+            {
+              "items": {
+                "additionalProperties": true,
+                "properties": {
+                  "country": {
+                    "type": [
+                      "string",
+                      "null"
+                    ]
+                  },
+                  "country_name": {
+                    "type": [
+                      "string",
+                      "null"
+                    ]
+                  },
+                  "elevation_ft": {
+                    "type": [
+                      "number",
+                      "null"
+                    ]
+                  },
+                  "iata_code": {
+                    "type": [
+                      "string",
+                      "null"
+                    ]
+                  },
+                  "ident": {
+                    "type": [
+                      "string",
+                      "null"
+                    ]
+                  },
+                  "latitude": {
+                    "type": [
+                      "number",
+                      "null"
+                    ]
+                  },
+                  "longitude": {
+                    "type": [
+                      "number",
+                      "null"
+                    ]
+                  },
+                  "municipality": {
+                    "type": [
+                      "string",
+                      "null"
+                    ]
+                  },
+                  "name": {
+                    "type": [
+                      "string",
+                      "null"
+                    ]
+                  },
+                  "region": {
+                    "type": [
+                      "string",
+                      "null"
+                    ]
+                  },
+                  "type": {
+                    "type": [
+                      "string",
+                      "null"
+                    ]
+                  }
+                },
+                "type": "object"
+              },
+              "type": "array"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        }
+      },
+      "type": "object"
+    },
+    {
+      "additionalProperties": {},
+      "type": "object"
+    }
+  ]
+}
    • removedOutput schema / properties / results
      Removed value: -{
-  "items": {
-    "additionalProperties": false,
-    "properties": {
-      "country": {
-        "type": "string"
-      },
-      "country_name": {
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "distance_km": {
-        "type": "number"
-      },
-      "elevation_ft": {
-        "type": [
-          "number",
-          "null"
-        ]
-      },
-      "iata_code": {
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "ident": {
-        "type": "string"
-      },
-      "latitude": {
-        "type": "number"
-      },
-      "longitude": {
-        "type": "number"
-      },
-      "municipality": {
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "name": {
-        "type": "string"
-      },
-      "region": {
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "type": {
-        "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": {
+      "type": [
+        "string",
+        "null"
+      ]
+    }
+  },
+  "required": [
+    "as_of"
+  ],
+  "type": "object"
+}
    • addedOutput schema / properties / warnings
      Added value: +{
+  "items": {
+    "additionalProperties": false,
+    "properties": {
+      "code": {
+        "type": "string"
+      },
+      "details": {
+        "additionalProperties": {},
+        "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"
+]
  5. Addedv2.10.0

TDQS

A4.6/5.0
Behavior4/5

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

Goes well beyond the readOnly/idempotent annotations: discloses the deterministic sort, the default filter (scheduled service + IATA only, no heliports/closed fields), include_all semantics, confidence scoring behavior, rate limiting with reset_at, and that coordinates are input-only and never stored. The only gap is that it re-describes return fields rather than trusting the output schema.

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 inputs, then segmented into Behavior / Returns / Limitations / Related, so an agent can skim to the section it needs. Slightly over-long: the 'FreightUtils v1 response envelope' aside and the Returns block duplicate the output schema.

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 format, filtering defaults, ranking semantics, confidence meaning, rate-limit recovery, and a limitations caveat about navigation/reference data. 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 baseline is 3; the description earns above that by explaining the interaction the schema only states in isolation — that include_all widens the candidate set while type narrows it. Defaults (max_results 10, radius omitted = no cap) are repeated rather than new, keeping 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?

Opens with a specific verb+resource+scope: find airports nearest a caller-supplied lat/lon, ranked by haversine distance with distance_km on each result. It also quantifies the corpus (86,248 airports, OurAirports) and explicitly separates itself from airport_lookup (exact code/name, 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?

States explicit exclusions — 'does NOT geocode place names and does NOT compute routes — pass coordinates you already hold' — which is exactly the failure mode an agent would hit. It also routes to two named alternatives (airport_lookup, unlocode_lookup) with the condition distinguishing them.

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

Deploy Server

Other Tools