Skip to main content
Glama

Vessel Tracking

by io.github.pipeworx-io
OverviewDiscussionsAdmin

Live Ship Position

live_ship_position
Read-onlyIdempotent

Where is a specific ship right now — live AIS position for one or more vessels by MMSI number. Returns position, speed, course, navigational status and destination as currently broadcast. BEST EFFORT BY NATURE: this listens for a live broadcast rather than reading a stored position, and many vessels transmit less than once a minute, so a single call frequently hears nothing even for a ship that is definitely sailing. Measured behaviour, not a caveat for form. Improve the odds with a longer window_seconds, or use live_ships_in_area if you know roughly where the ship is. For a guaranteed last-known position rather than a live catch, use vesselfinder_vessel (paid key). 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
mmsiYesOne or more 9-digit MMSI numbers, e.g. ["219034351"]
_apiKeyNoaisstream.io API key (free at aisstream.io)
window_secondsNoHow long to listen, 3-40 seconds (default 30). Hit rate scales almost linearly with this: many vessels transmit less than once a minute, so a 10-second window will usually miss and a 40-second one often succeeds. Prefer a long window here — the wait buys the answer.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / examples
      Previous value: -[
-  {
-    "_apiKey": "your-vessel-tracking-api-key",
-    "mmsi": [
-      "219034351"
-    ]
-  },
-  {
-    "_apiKey": "your-vessel-tracking-api-key",
-    "mmsi": [
-      "219034351",
-      "636014797"
-    ],
-    "window_seconds": 40
-  }
-]New value: +[
+  {
+    "mmsi": [
+      "219034351"
+    ]
+  },
+  {
+    "mmsi": [
+      "219034351",
+      "636014797"
+    ],
+    "window_seconds": 40
+  }
+]
  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), but the description goes well beyond them: best-effort broadcast listening, frequent empty results for moving ships, partial terrestrial receiver coverage, and the semantic that counts are heard-during-window rather than vessels present. That is exactly the behavioral context annotations cannot carry.

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 answer and then layered with caveats in priority order. Slightly long, and the meta sentence 'Measured behaviour, not a caveat for form' is defensible but borderline filler; all other sentences carry operational information.

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, the description still names the returned fields, explains the false-negative failure mode, and bounds geographic coverage. An agent has everything needed to decide whether the result is trustworthy and what to do on an empty response.

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, but the description adds real meaning: window_seconds is framed as a hit-rate lever with an explicit monotonic relationship ('prefer a long window here — the wait buys the answer'), which is more than the schema restates. It does not restate the MMSI format or _apiKey beyond 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 ('live AIS position for one or more vessels by MMSI') and enumerates the returned fields. It explicitly differentiates itself from live_ships_in_area and vesselfinder_vessel, so an agent can route without opening either schema.

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 explicit when-to-use cases (live catch, known roughly where the ship is, guaranteed last-known position), names the alternatives, and states a hard when-not (Persian Gulf, Hormuz, Gulf of Oman, Red Sea) with the correct sibling to use instead.

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