Skip to main content
Glama

Vessel Tracking

by io.github.pipeworx-io
OverviewDiscussionsAdmin

Live Ships In Area

live_ships_in_area
Read-onlyIdempotent

Live ship positions right now in a geographic area, from AIS radio broadcasts — what vessels are sailing near a port, coastline, strait or set of coordinates at this moment. Returns each vessel heard with its position, speed, course, navigational status, type, destination and IMO where broadcast, plus a breakdown by vessel type (cargo, tanker, passenger, fishing, tug). Give either a centre point (latitude + longitude + radius_km) or a bounding box. COVERAGE IS PARTIAL AND TERRESTRIAL — there is no receiver coverage in the Persian Gulf, Strait of Hormuz, Gulf of Oman or Red Sea, so this tool cannot answer questions about those waters (use chokepoint_status for Hormuz/Suez/Bab el-Mandeb transit counts instead). Counts are vessels heard during a listening window of a few seconds, not a complete count of vessels present.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
eastNoBounding box eastern longitude
westNoBounding box western longitude
limitNoMaximum vessels to return (default 50, max 300)
northNoBounding box northern latitude
southNoBounding box southern latitude (alternative to centre+radius)
_apiKeyNoaisstream.io API key (free at aisstream.io)
latitudeNoCentre latitude, e.g. 43.3 for Marseille
longitudeNoCentre longitude, e.g. 5.4 for Marseille
radius_kmNoRadius around the centre point in km (default 50, max 500)
ship_typeNoOptional filter on decoded type, e.g. "tanker", "cargo", "passenger", "fishing", "tug"
window_secondsNoHow long to listen, 3-25 seconds (default 12). Longer windows hear more vessels, especially anchored ones which only transmit every ~3 minutes.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / examples
      Previous value: -[
-  {
-    "_apiKey": "your-vessel-tracking-api-key",
-    "latitude": 43.3,
-    "longitude": 5.4,
-    "radius_km": 50
-  },
-  {
-    "_apiKey": "your-vessel-tracking-api-key",
-    "east": 0.1,
-    "north": 51.5,
-    "ship_type": "tanker",
-    "south": 51.4,
-    "west": -0.1,
-    "window_seconds": 20
-  }
-]New value: +[
+  {
+    "latitude": 43.3,
+    "longitude": 5.4,
+    "radius_km": 50
+  },
+  {
+    "east": 0.1,
+    "north": 51.5,
+    "ship_type": "tanker",
+    "south": 51.4,
+    "west": -0.1,
+    "window_seconds": 20
+  }
+]
  2. First observed

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, openWorld, non-destructive), and the description adds behavior beyond them: coverage is partial and terrestrial, and counts reflect only vessels heard during a few-second listening window rather than a complete census. This temporal/coverage caveat is exactly the kind of limitation that prevents an agent from over-claiming results.

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, then inputs, then the critical coverage caveat, then the counting caveat. Every sentence is substantive, though the parenthetical enumeration of use cases ('port, coastline, strait or set of coordinates') is slightly redundant with the opening clause.

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?

With no output schema and 11 parameters, the description carries the return-value burden and does so: it enumerates position, speed, course, navigational status, type, destination, IMO, and a by-type breakdown. Combined with the coverage and listening-window caveats, an agent has everything needed to call and interpret it correctly.

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 description coverage is 100%, so the baseline is 3; the description adds real meaning on top by framing the centre-vs-bounding-box alternative and explaining that longer window_seconds hear more vessels (especially anchored ones transmitting every ~3 minutes). It doesn't clarify the limit semantics or ship_type values beyond what the schema already provides, so it stops short of 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+resource+scope: 'Live ship positions right now in a geographic area, from AIS radio broadcasts.' The area-based scope contrasts clearly with the singular sibling live_ship_position, and the description names the concrete things it answers (vessels near a port, coastline, strait, or coordinates).

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?

Explicit when-not guidance: no receiver coverage in the Persian Gulf, Strait of Hormuz, Gulf of Oman or Red Sea, with a named alternative (chokepoint_status) for those waters. It also states the two accepted input modes (centre+radius or bounding box), so an agent knows exactly how to invoke it.

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

All Vessel Tracking 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