Skip to main content
Glama

Search vessels by name

search_vessels_by_name
Read-onlyIdempotent

Vessels whose name contains the text, case-insensitive, among every vessel the network has heard, each with its MMSI and last known position when available. An optional bounding box narrows the search. With a feeder or partner token, text of the form IMO 9241061 finds the vessels reporting that IMO number, and a bare seven-digit number finds them ahead of the name matches.

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": {
      "name": "<name>"
    },
    "name": "search_vessels_by_name"
  }
}

Input Schema

NameRequiredDescriptionDefault
bboxNoonly vessels whose last position is inside this box
flagNoonly vessels flying this flag: ISO 3166-1 alpha-2, e.g. NO, FI, MH
nameYestext to find in the vessel name, at least 2 characters, case-insensitive; with a feeder or partner token, IMO followed by an IMO number finds that IMO
limitNorows to return: default 50, maximum 200

Output Schema

NameRequiredDescriptionDefault
totalYesvessels matched before the limit was applied
vesselsYes
truncatedYestrue when rows were left out: total exceeds the rows returned, or an IMO number is reported by more than the 10 vessels returned for it
attributionYesattribution required when displaying the rows, by source kind
unknown_imoNorequested IMO numbers matching no vessel the network has heard
unknown_mmsiNorequested MMSIs matching no vessel the network has heard

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changed
    • changedOutput schema / properties / attribution / description
      Previous value: -"credit line per source kind in the rows, to show with the data"New value: +"attribution required when displaying the rows, by source kind"
    • changedOutput schema / properties / truncated / description
      Previous value: -"true when rows were left out: total exceeds the rows returned, so narrow the query or raise limit, or an IMO number is reported by more than the 10 vessels returned for it"New value: +"true when rows were left out: total exceeds the rows returned, or an IMO number is reported by more than the 10 vessels returned for it"
    • changedOutput schema / properties / vessels / items / properties / eta / description
      Previous value: -"estimated arrival as sent, MM-DD HH:MM UTC or MM-DD; AIS carries no year, so read it as the next occurrence"New value: +"estimated arrival as sent, MM-DD HH:MM UTC or MM-DD, for the next expected arrival. AIS omits the year"
  2. Changed4 schema fields changed
    • changedOutput schema / properties / vessels / items / properties / beam / description
      Previous value: -"beam, metres"New value: +"beam, metres; never for gear"
    • changedOutput schema / properties / vessels / items / properties / draught / description
      Previous value: -"maximum static draught, metres"New value: +"maximum static draught, metres; never for gear"
    • changedOutput schema / properties / vessels / items / properties / heading / description
      Previous value: -"true heading, degrees"New value: +"true heading, degrees, 0 to 359; never for gear"
    • changedOutput schema / properties / vessels / items / properties / length / description
      Previous value: -"overall length, metres"New value: +"overall length, metres; never for gear, whose size is a placeholder"
  3. Changed2 schema fields changed
    • changedOutput schema / properties / vessels / items / properties / flag / description
      Previous value: -"ISO 3166-1 alpha-2 code of the flag state, from the MMSI's maritime identification digits"New value: +"ISO 3166-1 alpha-2 code of the flag state, from the MMSI's maritime identification digits; never set for gear"
    • changedOutput schema / properties / vessels / items / properties / kind / description
      Previous value: -"vessel, aton (aid to navigation), base (base station), or sar (search and rescue aircraft)"New value: +"vessel, aton (aid to navigation), base (base station), sar (search and rescue aircraft or active distress beacon: AIS-SART, man-overboard, EPIRB-AIS), or gear (fishing gear, usually a net buoy, which has no flag)"
  4. Changed2 schema fields changed
    • changedInput schema / properties / name / description
      Previous value: -"text to find in the vessel name, at least 2 characters, case-insensitive"New value: +"text to find in the vessel name, at least 2 characters, case-insensitive; with a feeder or partner token, IMO followed by an IMO number finds that IMO"
    • changedOutput schema / properties / truncated / description
      Previous value: -"true when total exceeds the rows returned; narrow the query or raise limit"New value: +"true when rows were left out: total exceeds the rows returned, so narrow the query or raise limit, or an IMO number is reported by more than the 10 vessels returned for it"
  5. Changed1 schema field changed
    • changedOutput schema / properties / vessels / items / properties / sources / additionalProperties / properties / url / description
      Previous value: -"the source's own page for this vessel"New value: +"the source's page for this vessel, or its public search when the source keeps no per-vessel pages"
  6. Changed1 schema field changed
    • addedOutput schema / properties / vessels / items / properties / particulars / properties / callsign
      Added value: +{
      +  "description": "call sign as registered; the callsign in the vessel's own properties is the one AIS reports",
      +  "type": "string"
      +}
  7. Changed5 schema fields changed
    • addedOutput schema / properties / vessels / items / properties / particulars
      Added value: +{
      +  "additionalProperties": false,
      +  "description": "particulars as registered, merged from the enrichment sources into one vocabulary (get_vessels)",
      +  "properties": {
      +    "beam": {
      +      "description": "beam as registered, metres",
      +      "type": "number"
      +    },
      +    "builder": {
      +      "description": "shipyard or builder",
      +      "type": "string"
      +    },
      +    "commons_category": {
      +      "description": "the category of the ship's photos on Wikimedia Commons",
      +      "type": "string"
      +    },
      +    "deadweight": {
      +      "description": "deadweight, tonnes",
      +      "type": "integer"
      +    },
      +    "depth": {
      +      "description": "registered depth, metres",
      +      "type": "number"
      +    },
      +    "draught": {
      +      "description": "design draught, metres; AIS reports the draught on the current voyage",
      +      "type": "number"
      +    },
      +    "former_names": {
      +      "description": "names the vessel has carried before, oldest first",
      +      "items": {
      +        "type": "string"
      +      },
      +      "type": [
      +        "null",
      +        "array"
      +      ]
      +    },
      +    "gross_tonnage": {
      +      "type": "integer"
      +    },
      +    "home_port": {
      +      "description": "port of registry",
      +      "type": "string"
      +    },
      +    "identification": {
      +      "description": "the flag state's number for the vessel: a documented vessel's official number, else its state registration",
      +      "type": "string"
      +    },
      +    "image": {
      +      "description": "the Commons page of a photo of the ship, which shows its license and credit",
      +      "type": "string"
      +    },
      +    "length": {
      +      "description": "length as registered, metres; may differ from the AIS length",
      +      "type": "number"
      +    },
      +    "net_tonnage": {
      +      "type": "integer"
      +    },
      +    "operator": {
      +      "type": "string"
      +    },
      +    "owner": {
      +      "type": "string"
      +    },
      +    "registered_name": {
      +      "description": "name as documented with the flag state, when it differs from what AIS reports",
      +      "type": "string"
      +    },
      +    "registry": {
      +      "description": "country of registry, in English",
      +      "type": "string"
      +    },
      +    "service": {
      +      "description": "flag-state service type, e.g. Towing Vessel, Passenger (Inspected), Recreational",
      +      "type": "string"
      +    },
      +    "ship_type": {
      +      "description": "kind of ship, e.g. bulk carrier, container ship, ferry",
      +      "type": "string"
      +    },
      +    "status": {
      +      "description": "flag-state status, e.g. Active, Laid Up",
      +      "type": "string"
      +    },
      +    "tonnage_measure": {
      +      "description": "how a tonnage from the flag state was measured: Convention (the international system), Regulatory (the older US system, in register tons), or Simplified (small vessels)",
      +      "type": "string"
      +    },
      +    "wikipedia": {
      +      "description": "the ship's English Wikipedia article",
      +      "type": "string"
      +    },
      +    "yard_number": {
      +      "description": "the builder's hull number",
      +      "type": "string"
      +    },
      +    "year_built": {
      +      "type": "integer"
      +    }
      +  },
      +  "type": [
      +    "null",
      +    "object"
      +  ]
      +}
    • addedOutput schema / properties / vessels / items / properties / provenance
      Added value: +{
      +  "additionalProperties": {
      +    "type": "string"
      +  },
      +  "description": "the source of each particulars field, by the field's name; values are keys of sources (get_vessels)",
      +  "type": "object"
      +}
    • addedOutput schema / properties / vessels / items / properties / sources
      Added value: +{
      +  "additionalProperties": {
      +    "additionalProperties": false,
      +    "properties": {
      +      "credit": {
      +        "description": "display credit for the source",
      +        "type": "string"
      +      },
      +      "license": {
      +        "type": "string"
      +      },
      +      "url": {
      +        "description": "the source's own page for this vessel",
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "credit",
      +      "license"
      +    ],
      +    "type": "object"
      +  },
      +  "description": "each contributing source's credit, license, and its own page for this vessel (get_vessels)",
      +  "type": "object"
      +}
    • removedOutput schema / properties / vessels / items / properties / uscg
      Removed value: -{
      -  "additionalProperties": false,
      -  "description": "particulars as documented with the US Coast Guard, for a US-flag vessel whose call sign and name match a vessel in its PSIX database (get_vessels)",
      -  "properties": {
      -    "beam": {
      -      "description": "registered breadth, metres",
      -      "type": "number"
      -    },
      -    "depth": {
      -      "description": "registered depth, metres",
      -      "type": "number"
      -    },
      -    "gross_tonnage": {
      -      "type": "integer"
      -    },
      -    "id": {
      -      "description": "the vessel's ID in PSIX",
      -      "type": "integer"
      -    },
      -    "identification": {
      -      "description": "the official number of a documented vessel, else its state registration",
      -      "type": "string"
      -    },
      -    "length": {
      -      "description": "registered length, metres",
      -      "type": "number"
      -    },
      -    "license": {
      -      "description": "public domain (U.S. government work), no credit required",
      -      "type": "string"
      -    },
      -    "name": {
      -      "description": "name as documented with the Coast Guard",
      -      "type": "string"
      -    },
      -    "net_tonnage": {
      -      "type": "integer"
      -    },
      -    "service": {
      -      "description": "service type, e.g. Towing Vessel, Passenger (Inspected), Commercial Fishing Vessel, Recreational",
      -      "type": "string"
      -    },
      -    "status": {
      -      "description": "Coast Guard status, e.g. Active, Laid Up",
      -      "type": "string"
      -    },
      -    "tonnage_measure": {
      -      "description": "how the tonnage was measured: Convention (the international system), Regulatory (the older US system, in register tons), or Simplified (small vessels)",
      -      "type": "string"
      -    },
      -    "year_built": {
      -      "type": "integer"
      -    }
      -  },
      -  "required": [
      -    "id",
      -    "license",
      -    "name"
      -  ],
      -  "type": [
      -    "null",
      -    "object"
      -  ]
      -}
    • removedOutput schema / properties / vessels / items / properties / wikidata
      Removed value: -{
      -  "additionalProperties": false,
      -  "description": "particulars as registered, from the vessel's Wikidata item found by its IMO number (get_vessels)",
      -  "properties": {
      -    "beam": {
      -      "description": "beam as registered, metres",
      -      "type": "number"
      -    },
      -    "builder": {
      -      "description": "shipyard or builder",
      -      "type": "string"
      -    },
      -    "commons_category": {
      -      "description": "the category of the ship's photos on Wikimedia Commons",
      -      "type": "string"
      -    },
      -    "deadweight": {
      -      "description": "deadweight, tonnes",
      -      "type": "integer"
      -    },
      -    "draught": {
      -      "description": "design draught, metres; AIS reports the draught on the current voyage",
      -      "type": "number"
      -    },
      -    "former_names": {
      -      "description": "names the vessel has carried before, oldest first",
      -      "items": {
      -        "type": "string"
      -      },
      -      "type": [
      -        "null",
      -        "array"
      -      ]
      -    },
      -    "gross_tonnage": {
      -      "type": "integer"
      -    },
      -    "home_port": {
      -      "description": "port of registry",
      -      "type": "string"
      -    },
      -    "id": {
      -      "description": "Wikidata item ID",
      -      "type": "string"
      -    },
      -    "image": {
      -      "description": "the Commons page of a photo of the ship, which shows its license and credit",
      -      "type": "string"
      -    },
      -    "length": {
      -      "description": "length as registered, metres; may differ from the AIS length",
      -      "type": "number"
      -    },
      -    "license": {
      -      "description": "CC0-1.0: public domain, no credit required; the photos image and commons_category lead to carry their own licenses",
      -      "type": "string"
      -    },
      -    "operator": {
      -      "type": "string"
      -    },
      -    "owner": {
      -      "type": "string"
      -    },
      -    "registry": {
      -      "description": "country of registry, in English",
      -      "type": "string"
      -    },
      -    "ship_type": {
      -      "description": "kind of ship, e.g. bulk carrier, container ship, oil tanker, ferry",
      -      "type": "string"
      -    },
      -    "url": {
      -      "description": "the item's page on Wikidata",
      -      "type": "string"
      -    },
      -    "wikipedia": {
      -      "description": "the ship's English Wikipedia article",
      -      "type": "string"
      -    },
      -    "yard_number": {
      -      "description": "the builder's hull number",
      -      "type": "string"
      -    },
      -    "year_built": {
      -      "description": "year the vessel entered service",
      -      "type": "integer"
      -    }
      -  },
      -  "required": [
      -    "id",
      -    "url",
      -    "license"
      -  ],
      -  "type": [
      -    "null",
      -    "object"
      -  ]
      -}
  8. Changed2 schema fields changed
    • addedOutput schema / properties / vessels / items / properties / uscg
      Added value: +{
      +  "additionalProperties": false,
      +  "description": "particulars as documented with the US Coast Guard, for a US-flag vessel whose call sign and name match a vessel in its PSIX database (get_vessels)",
      +  "properties": {
      +    "beam": {
      +      "description": "registered breadth, metres",
      +      "type": "number"
      +    },
      +    "depth": {
      +      "description": "registered depth, metres",
      +      "type": "number"
      +    },
      +    "gross_tonnage": {
      +      "type": "integer"
      +    },
      +    "id": {
      +      "description": "the vessel's ID in PSIX",
      +      "type": "integer"
      +    },
      +    "identification": {
      +      "description": "the official number of a documented vessel, else its state registration",
      +      "type": "string"
      +    },
      +    "length": {
      +      "description": "registered length, metres",
      +      "type": "number"
      +    },
      +    "license": {
      +      "description": "public domain (U.S. government work), no credit required",
      +      "type": "string"
      +    },
      +    "name": {
      +      "description": "name as documented with the Coast Guard",
      +      "type": "string"
      +    },
      +    "net_tonnage": {
      +      "type": "integer"
      +    },
      +    "service": {
      +      "description": "service type, e.g. Towing Vessel, Passenger (Inspected), Commercial Fishing Vessel, Recreational",
      +      "type": "string"
      +    },
      +    "status": {
      +      "description": "Coast Guard status, e.g. Active, Laid Up",
      +      "type": "string"
      +    },
      +    "tonnage_measure": {
      +      "description": "how the tonnage was measured: Convention (the international system), Regulatory (the older US system, in register tons), or Simplified (small vessels)",
      +      "type": "string"
      +    },
      +    "year_built": {
      +      "type": "integer"
      +    }
      +  },
      +  "required": [
      +    "id",
      +    "license",
      +    "name"
      +  ],
      +  "type": [
      +    "null",
      +    "object"
      +  ]
      +}
    • addedOutput schema / properties / vessels / items / properties / wikidata
      Added value: +{
      +  "additionalProperties": false,
      +  "description": "particulars as registered, from the vessel's Wikidata item found by its IMO number (get_vessels)",
      +  "properties": {
      +    "beam": {
      +      "description": "beam as registered, metres",
      +      "type": "number"
      +    },
      +    "builder": {
      +      "description": "shipyard or builder",
      +      "type": "string"
      +    },
      +    "commons_category": {
      +      "description": "the category of the ship's photos on Wikimedia Commons",
      +      "type": "string"
      +    },
      +    "deadweight": {
      +      "description": "deadweight, tonnes",
      +      "type": "integer"
      +    },
      +    "draught": {
      +      "description": "design draught, metres; AIS reports the draught on the current voyage",
      +      "type": "number"
      +    },
      +    "former_names": {
      +      "description": "names the vessel has carried before, oldest first",
      +      "items": {
      +        "type": "string"
      +      },
      +      "type": [
      +        "null",
      +        "array"
      +      ]
      +    },
      +    "gross_tonnage": {
      +      "type": "integer"
      +    },
      +    "home_port": {
      +      "description": "port of registry",
      +      "type": "string"
      +    },
      +    "id": {
      +      "description": "Wikidata item ID",
      +      "type": "string"
      +    },
      +    "image": {
      +      "description": "the Commons page of a photo of the ship, which shows its license and credit",
      +      "type": "string"
      +    },
      +    "length": {
      +      "description": "length as registered, metres; may differ from the AIS length",
      +      "type": "number"
      +    },
      +    "license": {
      +      "description": "CC0-1.0: public domain, no credit required; the photos image and commons_category lead to carry their own licenses",
      +      "type": "string"
      +    },
      +    "operator": {
      +      "type": "string"
      +    },
      +    "owner": {
      +      "type": "string"
      +    },
      +    "registry": {
      +      "description": "country of registry, in English",
      +      "type": "string"
      +    },
      +    "ship_type": {
      +      "description": "kind of ship, e.g. bulk carrier, container ship, oil tanker, ferry",
      +      "type": "string"
      +    },
      +    "url": {
      +      "description": "the item's page on Wikidata",
      +      "type": "string"
      +    },
      +    "wikipedia": {
      +      "description": "the ship's English Wikipedia article",
      +      "type": "string"
      +    },
      +    "yard_number": {
      +      "description": "the builder's hull number",
      +      "type": "string"
      +    },
      +    "year_built": {
      +      "description": "year the vessel entered service",
      +      "type": "integer"
      +    }
      +  },
      +  "required": [
      +    "id",
      +    "url",
      +    "license"
      +  ],
      +  "type": [
      +    "null",
      +    "object"
      +  ]
      +}
  9. Changed2 schema fields changed
    • changedOutput schema / properties / unknown_imo / description
      Previous value: -"requested IMO numbers matching no vessel heard in the last 30 minutes"New value: +"requested IMO numbers matching no vessel the network has heard"
    • changedOutput schema / properties / unknown_mmsi / description
      Previous value: -"requested MMSIs not heard in the last 30 minutes"New value: +"requested MMSIs matching no vessel the network has heard"
  10. Changed10 schema fields changed
    • addedInput schema / properties / flag
      Added value: +{
      +  "description": "only vessels flying this flag: ISO 3166-1 alpha-2, e.g. NO, FI, MH",
      +  "type": "string"
      +}
    • addedOutput schema / properties / unknown_imo
      Added value: +{
      +  "description": "requested IMO numbers matching no vessel heard in the last 30 minutes",
      +  "items": {
      +    "maximum": 4294967295,
      +    "minimum": 0,
      +    "type": "integer"
      +  },
      +  "type": [
      +    "null",
      +    "array"
      +  ]
      +}
    • addedOutput schema / properties / vessels / items / properties / beam
      Added value: +{
      +  "description": "beam, metres",
      +  "maximum": 65535,
      +  "minimum": 0,
      +  "type": [
      +    "null",
      +    "integer"
      +  ]
      +}
    • addedOutput schema / properties / vessels / items / properties / callsign
      Added value: +{
      +  "type": "string"
      +}
    • addedOutput schema / properties / vessels / items / properties / destination
      Added value: +{
      +  "description": "destination as typed by the crew: a port name, a UN/LOCODE, or nothing useful",
      +  "type": "string"
      +}
    • addedOutput schema / properties / vessels / items / properties / draught
      Added value: +{
      +  "description": "maximum static draught, metres",
      +  "type": [
      +    "null",
      +    "number"
      +  ]
      +}
    • addedOutput schema / properties / vessels / items / properties / eta
      Added value: +{
      +  "description": "estimated arrival as sent, MM-DD HH:MM UTC or MM-DD; AIS carries no year, so read it as the next occurrence",
      +  "type": "string"
      +}
    • addedOutput schema / properties / vessels / items / properties / flag
      Added value: +{
      +  "description": "ISO 3166-1 alpha-2 code of the flag state, from the MMSI's maritime identification digits",
      +  "type": "string"
      +}
    • addedOutput schema / properties / vessels / items / properties / imo
      Added value: +{
      +  "description": "IMO number, once the vessel's static data has been heard",
      +  "maximum": 4294967295,
      +  "minimum": 0,
      +  "type": "integer"
      +}
    • addedOutput schema / properties / vessels / items / properties / length
      Added value: +{
      +  "description": "overall length, metres",
      +  "maximum": 65535,
      +  "minimum": 0,
      +  "type": [
      +    "null",
      +    "integer"
      +  ]
      +}
  11. First observed

TDQS

A3.9/5.0
Behavior4/5

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds real behavioral detail beyond them: results include MMSI and last known position 'when available', the IMO interpretation only applies with a feeder or partner token, and bare seven-digit numbers rank ahead of name matches. It does not state whether results are truncated, but limit is in 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?

Two sentences, front-loaded with what a hit looks like, then the bbox narrowing, then the token-specific lookup forms. Dense but every clause carries information; the long second sentence is the only structural weak point.

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 present, the description needn't document return shape, yet it still summarizes the key fields. Annotations, full schema coverage, and the token-dependent lookup caveats together leave nothing an agent needs missing in order to call this 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 100%, so the baseline is 3 and the schema already documents bbox edges, flag format, and the limit default/max. The description still contributes meaning the schema does not: a seven-digit bare number matches ahead of name matches, and the IMO form is gated on token type. Minor duplication of the IMO rule keeps it from a 5.

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?

The description names the resource (vessels), the matching rule (name contains text, case-insensitive), and the scope (every vessel the network has heard), plus what each result carries (MMSI, last known position). It implicitly separates itself from area-based siblings by describing bbox as an optional narrowing rather than the primary criterion, though it never names an alternative tool outright.

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

Usage Guidelines3/5

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

It gives useful conditional guidance for the bbox narrowing and for the token-dependent IMO/numeric lookup forms. What it lacks is explicit routing: it never says when to prefer find_vessels_in_area, find_vessels_near, or get_vessels over this tool, leaving that inference to the agent.

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.