Skip to main content
Glama

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.

Example tool call

This call uses example arguments supplied in the tool’s input schema.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "mmsi": [
        "219034351"
      ]
    },
    "name": "live_ship_position"
  }
}

Input 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 / properties / window_seconds / description
      Previous value: -"How 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."New value: +"How 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."
  2. 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
      +  }
      +]
  3. First observed

TDQS

A4.3/5.0
Behavior3/5

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

Annotations already declare readOnly, idempotent, open-world, non-destructive, so the safety profile is covered. The description goes further in a genuinely useful way by disclosing the best-effort broadcast model, the realistic per-call miss rate, and the partial terrestrial receiver coverage. It stops short of saying whether a partial/failed result is signaled as an error versus an empty list, which is the missing piece for an agent deciding how to react.

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 answer to the natural question, then failure modes, then alternatives, then coverage limits. Dense but almost every sentence carries routing or expectation-setting weight; only the aphoristic "Measured behaviour, not a caveat for form" is expendable.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema, but the description enumerates the returned fields (position, speed, course, navigational status, destination) and thoroughly frames the empty-result case, which is the main risk for this tool. The only residual gap is how empty or partial results are surfaced in the response envelope.

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, and the description reinforces the MMSI-as-vessel-identifier meaning and the window-to-hit-rate tradeoff. The window advice largely duplicates the schema's own window_seconds text, so it adds little beyond the baseline.

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-and-resource framing ("Where is a specific ship right now, live AIS position ... by MMSI number") and immediately separates itself from live_ships_in_area and vesselfinder_vessel. An agent can route between live lookup and area search 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 Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit when-to-use paths: longer window_seconds when odds are poor, live_ships_in_area when the approximate location is known, vesselfinder_vessel for a guaranteed last-known position, chokepoint_status for Hormuz/Suez transit counts. It also names when NOT to use it (Persian Gulf, Strait of Hormuz, Gulf of Oman, Red Sea) with a reason and a redirect.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.