Skip to main content
Glama
VesselAPI MCP Server

VesselAPI MCP Server

get_vessel_position

Retrieve a vessel's stored position (latitude, longitude, speed, heading, timestamp) to check its location and whether the fix may be outdated.

Instructions

Get the latest stored position of a vessel (latitude, longitude, speed, heading, timestamp). Check the timestamp: the fix may be hours or days old, especially for a vessel away from the coast. The response also carries the vessel's particulars, the destination and ETA it last reported, and a check against its previous position (minutes and distance between that report and this one, implied speed and course, whether the identifiers match). minutes_since_previous is not the age of this position; read vesselPosition.timestamp for that. A separate get_vessel_eta call is needed only when vesselEta is missing.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "vesselId": "<vesselId>"
    },
    "name": "get_vessel_position"
  }
}

Input Schema

NameRequiredDescriptionDefault
satNoDeprecated: the satellite fallback is withdrawn in its current form. From the cutoff date this option is accepted and ignored, and no credit is charged. Until then: fall back to a satellite position when no recent terrestrial one exists. Draws on a prepaid satellite credit balance: one credit when a satellite fix is returned, never twice for the same fix on this account, and nothing when a terrestrial position is returned. The result says whether a credit was charged. Use it only when a stored position is insufficient.
idTypeNoIdentifier type: imo (default) or mmsi
vesselIdYesVessel identifier (IMO number by default)
satMaxAgeMinutesNoOnly with sat: how old a stored position may be before a satellite lookup is made, 15 to 4800 minutes. Defaults to 60. Paid plans only. Deprecated: the satellite fallback is withdrawn in its current form. From the cutoff date this option is accepted and ignored, and no credit is charged.
satLookbackMinutesNoOnly with sat: how old a satellite position may be and still be returned, 60 to 4800 minutes. Defaults to 180. Deprecated: the satellite fallback is withdrawn in its current form. From the cutoff date this option is accepted and ignored, and no credit is charged.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changedv2.2.1
    • changedInput schema / properties / sat / description
      Previous value: -"Fall back to a satellite position when no recent terrestrial one exists. Draws on a prepaid satellite credit balance: one credit when a satellite fix is returned, never twice for the same fix on this account, and nothing when a terrestrial position is returned. The result says whether a credit was charged. Use it only when a stored position is insufficient."New value: +"Deprecated: the satellite fallback is withdrawn in its current form. From the cutoff date this option is accepted and ignored, and no credit is charged. Until then: fall back to a satellite position when no recent terrestrial one exists. Draws on a prepaid satellite credit balance: one credit when a satellite fix is returned, never twice for the same fix on this account, and nothing when a terrestrial position is returned. The result says whether a credit was charged. Use it only when a stored position is insufficient."
    • changedInput schema / properties / satLookbackMinutes / description
      Previous value: -"Only with sat: how old a satellite position may be and still be returned, 60 to 4800 minutes. Defaults to 180."New value: +"Only with sat: how old a satellite position may be and still be returned, 60 to 4800 minutes. Defaults to 180. Deprecated: the satellite fallback is withdrawn in its current form. From the cutoff date this option is accepted and ignored, and no credit is charged."
    • changedInput schema / properties / satMaxAgeMinutes / description
      Previous value: -"Only with sat: how old a stored position may be before a satellite lookup is made, 15 to 4800 minutes. Defaults to 60. Paid plans only."New value: +"Only with sat: how old a stored position may be before a satellite lookup is made, 15 to 4800 minutes. Defaults to 60. Paid plans only. Deprecated: the satellite fallback is withdrawn in its current form. From the cutoff date this option is accepted and ignored, and no credit is charged."
  2. Changed4 schema fields changedv2.2.0
    • removedInput schema / additionalProperties
      Removed value: -false
    • changedInput schema / properties / sat / description
      Previous value: -"Fall back to a satellite position when no recent terrestrial one exists. Charged per call against a prepaid balance, so use it only when a stored position is genuinely insufficient."New value: +"Fall back to a satellite position when no recent terrestrial one exists. Draws on a prepaid satellite credit balance: one credit when a satellite fix is returned, never twice for the same fix on this account, and nothing when a terrestrial position is returned. The result says whether a credit was charged. Use it only when a stored position is insufficient."
    • addedInput schema / properties / satLookbackMinutes
      Added value: +{
      +  "description": "Only with sat: how old a satellite position may be and still be returned, 60 to 4800 minutes. Defaults to 180.",
      +  "maximum": 4800,
      +  "minimum": 60,
      +  "type": "integer"
      +}
    • addedInput schema / properties / satMaxAgeMinutes
      Added value: +{
      +  "description": "Only with sat: how old a stored position may be before a satellite lookup is made, 15 to 4800 minutes. Defaults to 60. Paid plans only.",
      +  "maximum": 4800,
      +  "minimum": 15,
      +  "type": "integer"
      +}
  3. Changed3 schema fields changedv2.0.0
    • changedInput schema / properties / idType / description
      Previous value: -"Identifier type: imo (default), mmsi, or vesselId"New value: +"Identifier type: imo (default) or mmsi"
    • addedInput schema / properties / idType / enum
      Added value: +[
      +  "imo",
      +  "mmsi"
      +]
    • addedInput schema / properties / sat
      Added value: +{
      +  "description": "Fall back to a satellite position when no recent terrestrial one exists. Charged per call against a prepaid balance, so use it only when a stored position is genuinely insufficient.",
      +  "type": "boolean"
      +}
  4. Addedv1.3.0

TDQS

A4.1/5.0
Behavior4/5

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

With no annotations supplied, the description carries the burden and does disclose meaningful behavior: data can be stale by hours or days, especially offshore, and the response includes a previous-position comparison plus vessel particulars. It does not cover auth/permission requirements, rate limits, or the deprecated satellite-credit path that dominates the schema.

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 action and return fields, then the staleness caveat, then the ETA alternative. The middle sentence listing the previous-position comparison fields is dense but earns its place by pre-empting misreading of minutes_since_previous.

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 exists, and the description compensates by describing the returned position fields, vessel particulars, reported destination/ETA, and the previous-position comparison. The main gap is silence on the satellite-credit behavior, though that is fully covered in the parameter schema descriptions.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so parameter meaning is already fully documented in the schema, including the deprecated sat options. The description adds no parameter-level detail beyond the implicit notion that the default call returns a stored rather than satellite fix; baseline 3 applies.

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 ('Get the latest stored position of a vessel') and enumerates the payload fields (latitude, longitude, speed, heading, timestamp). The word 'stored' implicitly separates it from live/satellite lookups and from sibling tools like get_vessel and get_vessel_eta.

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 usage context: read vesselPosition.timestamp because the fix may be hours or days old, and minutes_since_previous is not the age. It also routes to an alternative explicitly ('A separate get_vessel_eta call is needed only when vesselEta is missing'). It does not mention when to prefer get_vessel_positions_batch for multiple vessels, so not a full 5.

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