Skip to main content
Glama
Sign In

AIS Trail

by com.aistrail
OverviewDiscussionsAdmin

Ship events (API key)

vessel_events
Read-onlyIdempotent

Events of a ship between two times (UTC, ISO 8601), computed from the AIS Trail archive. from and to are optional: without to, now (24 hours ago on plans without live data); without from, 7 days before to (on Free, no earlier than the oldest day the plan includes), as on the REST endpoint. Give mmsi or imo (with imo, every MMSI that reported that IMO number in the range). Types: ENTER_ZONE and EXIT_ZONE (arrival at and departure from a port or anchorage; port_id for port_calls, zone port or anchorage), STATE_CHANGED (MOVING, NOT_MOVING, LONG_STOP), NAME_CHANGED, IMO_CHANGED, CALLSIGN_CHANGED, DESTINATION_CHANGED and DRAUGHT_CHANGED (old and new value); only when asked by name or with types ['all']: AIS_GAP (long AIS silence while under way; old_value hours, new_value nautical miles), ENCOUNTER (slow close approach to another ship outside port areas, a candidate ship-to-ship transfer; new_value the other ship's MMSI), FLAG_CHANGED (the IMO number reappears under an MMSI with another flag) and POSITION_JUMP (a physically impossible position jump). Rows: [time, event, old_value, new_value, lat, lon, mmsi, port_id, zone, sanctions, detail]; detail says more about behaviour events. The sanctions column gives the codes of the sanctions lists (OFAC, UK, EU) that name the ship's IMO number; informational only, not a compliance determination. Needs an AIS Trail API key sent by the MCP client as the HTTP header 'Authorization: Bearer ap_live_…'. At most 200 events per call and at most 31 days; the plan's history depth, credits (1 per event returned), rate limit and 24-hour delay (on plans without live data) apply.

Input Schema

NameRequiredDescriptionDefault
toNoEnd, e.g. 2026-10-08T00:00:00Z; default: now (24 hours ago on plans without live data)
imoNo7-digit IMO number; covers every MMSI that reported it in the range. Give mmsi or imo
fromNoStart, e.g. 2026-10-01T00:00:00Z; default: 7 days before to (on Free, no earlier than the oldest day the plan includes)
mmsiNo9-digit MMSI of the ship; give mmsi or imo
typesNoEvent types; default: every type except AIS_GAP, ENCOUNTER, FLAG_CHANGED, POSITION_JUMP. ['all'] for every type.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changed
    • addedInput schema / properties / imo / description
      Added value: +"7-digit IMO number; covers every MMSI that reported it in the range. Give mmsi or imo"
    • addedInput schema / properties / mmsi / description
      Added value: +"9-digit MMSI of the ship; give mmsi or imo"
  2. Changed3 schema fields changed
    • changedInput schema / properties / from / description
      Previous value: -"Start, e.g. 2026-10-01T00:00:00Z"New value: +"Start, e.g. 2026-10-01T00:00:00Z; default: 7 days before to (on Free, no earlier than the oldest day the plan includes)"
    • changedInput schema / properties / to / description
      Previous value: -"End, e.g. 2026-10-08T00:00:00Z"New value: +"End, e.g. 2026-10-08T00:00:00Z; default: now (24 hours ago on plans without live data)"
    • changedInput schema / required
      Previous value: -[
-  "from",
-  "to"
-]New value: +[]
  3. Added

TDQS

A4.3/5.0
Behavior5/5

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

Adds substantial context beyond the annotations: 200-event and 31-day hard caps, 1 credit per event returned, rate limits, plan history depth, the 24-hour delay on non-live plans, and the required 'Authorization: Bearer ap_live_…' header. It also warns that the sanctions column is informational only and not a compliance determination, which is exactly the kind of caveat an agent could otherwise misapply.

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?

Purpose is front-loaded and nearly every sentence carries operational information. The single dense paragraph, especially the event-type enumeration, is harder to scan than it needs to be, but nothing is padding.

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 supplies the exact row shape [time, event, old_value, new_value, lat, lon, mmsi, port_id, zone, sanctions, detail] and explains per-type old_value/new_value semantics. Combined with auth, limits, and defaulting behavior, an agent has everything needed to call 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 coverage is already 100%, so the schema documents ranges and defaults, but the description goes further: it explains what each event type means (e.g. ENCOUNTER as a candidate ship-to-ship transfer, AIS_GAP with hours/miles in old_value/new_value), how imo expands to every reporting MMSI, and the row layout for results. Value added is real, though it restates some defaults already in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Events of a ship between two times') and grounds it in the AIS Trail archive, plus a full enumeration of event types that makes it clearly distinct from track-position tools. It never names a sibling tool explicitly, so an agent must infer the boundary with vessel_track or port_calls rather than being told.

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 concrete operational guidance: give mmsi or imo, defaults for from/to, and the rule that heavy event types (AIS_GAP, ENCOUNTER, FLAG_CHANGED, POSITION_JUMP) are returned only when requested by name or via ['all']. However, it gives no explicit when-to-use-this-vs-alternative statement for the sibling tools that also return ship/port data.

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

All AIS Trail 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