Skip to main content
Glama

Open Waters AIS

by io.openwaters
OverviewDiscussionsAdmin

Where a vessel has been

get_vessel_track
Read-onlyIdempotent

The positions heard from one vessel over a time range, oldest first, with speed, course, and navigational status. Positions implying an impossible speed for the vessel are left out. Use for where a ship was yesterday, when it left port, or its route today. Give the vessel's mmsi, or its imo with a feeder or partner token. A call covers up to a year. By default the track is simplified by shape: the positions that hold its path, with breaks where the vessel went unheard; interval_minutes asks for even spacing instead.

Input Schema

NameRequiredDescriptionDefault
toNoend, RFC 3339 UTC; default now
imoNothe vessel's IMO number, instead of mmsi; needs a feeder or partner token. Follows the one vessel the IMO names: its only MMSI, or the only one heard in the last 30 days
fromNostart, RFC 3339 UTC; default 24 hours before to. A call covers up to 366 days
mmsiNothe vessel's MMSI; give mmsi or imo. Use search_vessels_by_name first when you only have a name
limitNopositions to return: default 50, maximum 200; when more match, the newest are kept
interval_minutesNoat most one position per this many minutes, evenly spaced; by default the track is simplified by shape instead, keeping the positions that hold its path. Anonymous and personal calls reaching past 48 hours are rounded up to whole minutes

Output Schema

NameRequiredDescriptionDefault
toYes
fromYesstart of the range covered
mmsiYes
nameNo
breaksNosimplified, always present and empty when the vessel was heard throughout: indexes of positions that start a stretch after it went unheard; draw no line into them
positionsYesoldest first
truncatedYestrue when positions were left out: simplified, the tolerance rose past 15 m to fit the limit, or the range held more than 50,000 positions and the oldest were not read; by interval, the newest were kept, so set from later or raise interval_minutes
interval_sYesat most one position per this many seconds; 0 is every position heard. Simplified, the resolution the positions were read at
simplifiedYestrue when the track was simplified by shape: the positions that hold its path, not evenly spaced
attributionYescredit line per source kind in the positions, to show with the data
tolerance_mNosimplified: every position left out lay within this many meters of the line through the ones kept

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changed
    • addedInput schema / properties / imo
      Added value: +{
+  "description": "the vessel's IMO number, instead of mmsi; needs a feeder or partner token. Follows the one vessel the IMO names: its only MMSI, or the only one heard in the last 30 days",
+  "maximum": 4294967295,
+  "minimum": 0,
+  "type": "integer"
+}
    • changedInput schema / properties / mmsi / description
      Previous value: -"the vessel's MMSI; use search_vessels_by_name first when you only have a name"New value: +"the vessel's MMSI; give mmsi or imo. Use search_vessels_by_name first when you only have a name"
    • removedInput schema / required
      Removed value: -[
-  "mmsi"
-]
  2. Changed7 schema fields changed
    • changedInput schema / properties / interval_minutes / description
      Previous value: -"at most one position per this many minutes; by default the limit is spread over the range at a round spacing, reported as interval_s. Anonymous and personal calls reaching past 48 hours are rounded up to whole minutes"New value: +"at most one position per this many minutes, evenly spaced; by default the track is simplified by shape instead, keeping the positions that hold its path. Anonymous and personal calls reaching past 48 hours are rounded up to whole minutes"
    • addedOutput schema / properties / breaks
      Added value: +{
+  "description": "simplified, always present and empty when the vessel was heard throughout: indexes of positions that start a stretch after it went unheard; draw no line into them",
+  "items": {
+    "type": "integer"
+  },
+  "type": [
+    "null",
+    "array"
+  ]
+}
    • changedOutput schema / properties / interval_s / description
      Previous value: -"at most one position per this many seconds; 0 is every position heard"New value: +"at most one position per this many seconds; 0 is every position heard. Simplified, the resolution the positions were read at"
    • addedOutput schema / properties / simplified
      Added value: +{
+  "description": "true when the track was simplified by shape: the positions that hold its path, not evenly spaced",
+  "type": "boolean"
+}
    • addedOutput schema / properties / tolerance_m
      Added value: +{
+  "description": "simplified: every position left out lay within this many meters of the line through the ones kept",
+  "type": [
+    "null",
+    "number"
+  ]
+}
    • changedOutput schema / properties / truncated / description
      Previous value: -"true when more positions matched than were returned; the newest were kept, so set from later or raise interval_minutes"New value: +"true when positions were left out: simplified, the tolerance rose past 15 m to fit the limit, or the range held more than 50,000 positions and the oldest were not read; by interval, the newest were kept, so set from later or raise interval_minutes"
    • changedOutput schema / required
      Previous value: -[
-  "mmsi",
-  "from",
-  "to",
-  "interval_s",
-  "positions",
-  "truncated",
-  "attribution"
-]New value: +[
+  "mmsi",
+  "from",
+  "to",
+  "interval_s",
+  "simplified",
+  "positions",
+  "truncated",
+  "attribution"
+]
  3. Changed3 schema fields changed
    • changedInput schema / properties / from / description
      Previous value: -"start, RFC 3339 UTC; default 24 hours before to. Anonymous and personal calls reach back 48 hours; feeder and commercial tokens reach the archive, up to 366 days per call"New value: +"start, RFC 3339 UTC; default 24 hours before to. A call covers up to 366 days"
    • changedInput schema / properties / interval_minutes / description
      Previous value: -"at most one position per this many minutes; by default the limit is spread over the range at a round spacing, reported as interval_s"New value: +"at most one position per this many minutes; by default the limit is spread over the range at a round spacing, reported as interval_s. Anonymous and personal calls reaching past 48 hours are rounded up to whole minutes"
    • changedOutput schema / properties / from / description
      Previous value: -"start of the range covered, after clamping to what the caller can reach: the last 48 hours, or the archive for feeder and commercial tokens"New value: +"start of the range covered"
  4. Changed1 schema field changed
    • changedInput schema / properties / from / description
      Previous value: -"start, RFC 3339 UTC; default 24 hours before to. Anonymous and personal calls reach back 48 hours; feeder and commercial tokens reach the archive, up to 7 days per call"New value: +"start, RFC 3339 UTC; default 24 hours before to. Anonymous and personal calls reach back 48 hours; feeder and commercial tokens reach the archive, up to 366 days per call"
  5. Changed5 schema fields changed
    • changedInput schema / properties / from / description
      Previous value: -"start, RFC 3339 UTC; default 24 hours before to. Positions reach back 48 hours"New value: +"start, RFC 3339 UTC; default 24 hours before to. Anonymous and personal calls reach back 48 hours; feeder and commercial tokens reach the archive, up to 7 days per call"
    • changedInput schema / properties / interval_minutes / description
      Previous value: -"at most one position per this many minutes; by default the positions are spread evenly over the range"New value: +"at most one position per this many minutes; by default the limit is spread over the range at a round spacing, reported as interval_s"
    • changedOutput schema / properties / from / description
      Previous value: -"start of the range covered, after clamping to the last 48 hours"New value: +"start of the range covered, after clamping to what the caller can reach: the last 48 hours, or the archive for feeder and commercial tokens"
    • addedOutput schema / properties / interval_s
      Added value: +{
+  "description": "at most one position per this many seconds; 0 is every position heard",
+  "type": "integer"
+}
    • changedOutput schema / required
      Previous value: -[
-  "mmsi",
-  "from",
-  "to",
-  "positions",
-  "truncated",
-  "attribution"
-]New value: +[
+  "mmsi",
+  "from",
+  "to",
+  "interval_s",
+  "positions",
+  "truncated",
+  "attribution"
+]
  6. Added

TDQS

A4.6/5.0
Behavior5/5

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

Annotations cover safety (readOnly, idempotent, closed-world), but the description adds substantive behavior beyond them: impossible-speed positions are filtered out, the default track is shape-simplified with breaks where the vessel was unheard, interval_minutes switches to even spacing, and a call spans up to a year. This is exactly the kind of filtering and default-behavior disclosure an agent needs.

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 what the tool returns and its ordering, then use cases, then identifier requirements and defaults. Four dense sentences carry a lot, though the interval_minutes clause partially duplicates schema text and could be trimmed.

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 an output schema, 100% parameter coverage, and annotations present, the description only needs to supply behavioral context — and it does: filtering rules, default simplification strategy, ordering, and time-span limits. An agent can invoke this tool correctly without opening anything else.

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 nonetheless adds meaning by pairing mmsi/imo with the feeder-or-partner token requirement and framing the year-long call limit. It reinforces rather than merely restates the schema, but does not add syntax or edge-case detail beyond it.

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?

The description states a specific resource (positions heard from one vessel over a time range) with concrete output attributes (speed, course, navigational status) and ordering (oldest first). This is unmistakably distinct from siblings like find_vessels_in_area or search_vessels_by_name, which locate vessels rather than replay one vessel's history.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

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

Gives clear when-to-use contexts ('where a ship was yesterday, when it left port, or its route today') and prerequisites ('give the vessel's mmsi, or its imo with a feeder or partner token'). It does not explicitly state when NOT to use it or name a sibling alternative in the description text (the schema alone points to search_vessels_by_name), so it falls just short of full routing guidance.

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

All Open Waters AIS 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