Live ship positions, vessel history and port calls from AIS. Read-only, live tools need no key.
Scored across 9 tools
Most tools have clearly distinct purposes (port lookup, vessel search, area queries, port calls by port vs by vessel, track history). The only mild overlap is between get_vessel's recent track and vessel_track's archive query, and between vessels_in_area and vessels_near, but descriptions clarify the differences.
All names use snake_case, but the grammatical pattern is mixed: three tools are verb-first (find_port, get_vessel, search_vessels) while six are noun-first (data_status, port_calls, vessel_port_calls, vessels_in_area, vessels_near, vessel_track). The set is readable but not consistently verb_noun.
Nine tools is well-scoped for an AIS vessel tracking API, covering status, search, detail, area, and history without redundancy.
The surface covers the core read-only lifecycle: service status, port reference, vessel search/detail, port calls by port and by vessel, area/nearby search, and track history. Minor gaps exist (e.g., no get_port_by_id to resolve a port_id into details, though find_port can search by name).
How many ships are live now (live_ships_private: how many of them are private vessels, counted only), how many are known from the last 7 days, the date range of the history archive per source with available_until (the latest time vessel_track can return for that source on plans without live data), and the service status: ok or degraded, with reason codes in reasons.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds real behavioral context beyond that: what live_ships_private counts (private vessels only, counted not listed), the 7-day lookback, what available_until means for vessel_track on live-less plans, and the degraded/reasons failure model.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
It is a single very long sentence with nested parentheticals, cramming four distinct concepts (live counts, 7-day counts, archive ranges, service status) into one clause chain. Information density is high, but the structure makes it harder to parse than a short bulleted breakdown would be.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no parameters, no output schema, and full annotation coverage of the safety profile, the description carries the return-value burden and does so credibly, enumerating the key response fields. Some field names (e.g. the 7-day known-vessel count) remain unnamed, so an agent cannot map every value to an exact key.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so per the rubric the baseline is 4. The description correctly implies no arguments are needed and instead spends its words explaining the response fields.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific resource (coverage/freshness status) and enumerates the exact information returned: live ship counts, 7-day known vessels, per-source archive date range, available_until, and ok/degraded service status with reason codes. It is clearly distinguishable from the vessel-querying siblings, though it never explicitly frames itself as the metadata/health endpoint.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied rather than stated: an agent can infer this is a pre-flight check before querying vessel data, and available_until is tied to vessel_track's behavior on plans without live data. However, there is no explicit 'use this when...' or exclusion guidance, and no sibling tool is named as an alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find ports by name (or part of it), UN/LOCODE (e.g. NLRTM) or two-letter country code (e.g. NL) in the port reference (World Port Index and UN/LOCODE ports): id (for port_calls), name, country, UN/LOCODE, position, harbor size (World Port Index ports only) and the radius of the port area used to detect port calls. At most 20 ports, larger harbors first. No API key needed.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | No | Port name | |
| locode | No | UN/LOCODE | |
| country | No | ISO 3166-1 alpha-2 country code |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, idempotent, non-destructive, closed-world behavior. The description adds genuinely new traits: a hard cap of 20 results, ordering by harbor size (larger first), harbor size being World Port Index-only, and no API key requirement. Return-field disclosure is also present.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The find verb and search keys are front-loaded, and the result cap plus ordering are stated cleanly in their own short sentences. The middle list of return fields is dense but each item is load-bearing, so little is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description carries the return-shape burden and does enumerate the fields (id, name, country, UN/LOCODE, position, harbor size, radius). Combined with the result cap and ordering, an agent has enough to call and interpret it, though auth/pagination specifics are unaddressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 75%, so the schema handles much of the parameter documentation. The description still adds value by clarifying that query permits partial matches ('or part of it') and by giving concrete UN/LOCODE and country-code examples that the schema lacks.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (Find) and resource (ports) and enumerates the three search keys (name/partial name, UN/LOCODE, country code). It also names the backing references (World Port Index and UN/LOCODE ports), which no sibling tool shares, so an agent can distinguish it immediately.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It clearly conveys the search modes and hints that the returned id feeds port_calls, which implies usage context. However, it never explicitly states when to prefer find_port over siblings like port_calls or vessels_in_area, so routing is left partly to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Everything known about one ship now: identity (name, IMO, call sign, flag, type, size), last position, speed, course, heading, navigational status, destination (port codes decoded) and ETA as given by the crew, how long ago it was heard, its track over the last 40 minutes, and the data sources to credit. flag (ISO code) and flag_country come from the MMSI: the flag of the radio licence, usually but not always the registry flag. dwt_estimate is an estimate from the AIS dimensions (tonnes, size class such as Panamax or VLCC, hull, draught used), not a registry value; null for tugs, pleasure craft and other types where deadweight does not apply.
| Name | Required | Description | Default |
|---|---|---|---|
| mmsi | Yes | 9-digit MMSI |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive and closed-world, so safety is covered. The description goes well beyond them by disclosing data provenance and caveats: flag derived from MMSI (radio-licence flag, not always registry flag), dwt_estimate being an AIS-derived approximation with explicit null cases, decoded port codes and crew-supplied ETA. That is genuine interpretative context the schema cannot carry.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The most important framing ('Everything known about one ship now') is front-loaded, and every clause is substantively useful given there is no output schema. The middle sentence is a dense comma-list that is slightly hard to scan, but nothing is filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description carries the full return-value burden and discharges it well, enumerating identity, position, motion, destination, track window, sources and field caveats. The gaps are usage routing against siblings and error behaviour on an unknown MMSI, which keeps it short of a 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the single 'mmsi' parameter (9-digit, bounded 1–999999999), so the schema already does the heavy lifting. The description adds only indirect meaning via the MMSI-derived flag note, which explains a returned field rather than the input format.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Opens with a specific verb+resource+scope — 'Everything known about one ship now' — which is far more informative than the tautological title. However, it does not distinguish itself from siblings it clearly overlaps with: 'track over the last 40 minutes' collides with vessel_track, and the single-ship framing is never contrasted against search_vessels or vessels_near.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit when-to-use, when-not-to-use, or named alternative anywhere in the description. An agent must infer from the MMSI parameter that this is the single-vessel lookup, but the description never routes it against search_vessels, vessel_track or vessels_near, which are the obvious competing calls.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Ships that called at one port between two times (UTC, ISO 8601), from the AIS Trail archive: ship (with its flag from the MMSI), arrival, departure, draught on arrival and departure, cargo estimate, previous and next port. Get the port_id from find_port. event: any (in port at any time in the range, default), arrival or departure. Needs an AIS Trail API key sent by the MCP client as the HTTP header 'Authorization: Bearer ap_live_…'. At most 100 port calls per call and at most 366 days; the plan's rules and credits (1 per port call returned) apply as for vessel_port_calls.
| Name | Required | Description | Default |
|---|---|---|---|
| to | Yes | End, e.g. 2026-09-02T00:00:00Z | |
| from | Yes | Start, e.g. 2026-09-01T00:00:00Z | |
| event | No | any | |
| port_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnly/idempotent/openWorld/non-destructive), the description discloses material operational traits: an AIS Trail API key must be sent as an 'Authorization: Bearer ap_live_…' header, a 100-port-call cap, a 366-day range cap, and a cost of 1 credit per port call returned. These are exactly the facts an agent needs before invoking.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
It is a single dense paragraph that front-loads the resource and scope before moving to event, auth, and limits. Nearly every clause carries information, though the return-field enumeration and limits could be split for faster scanning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description correctly enumerates the return payload; with 50% parameter coverage it fills the enum and port_id gaps; and it covers auth, caps, and cost. For a read-only 4-parameter tool, 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.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50%, so the description must compensate and it largely does: 'event: any (in port at any time in the range, default), arrival or departure' explains the enum semantics rather than just repeating the labels, and it tells the agent where port_id comes from. from/to formats are left to the schema, leaving a small gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb+resource ('Ships that called at one port between two times') and enumerates the returned fields (ship with flag, arrival, departure, draught, cargo estimate, previous/next port) plus the data source ('AIS Trail archive'). It also routes the agent to a sibling ('Get the port_id from find_port') and relates itself to vessel_port_calls, so it is distinguishable without opening schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear context: obtain port_id from find_port, choose event with its default, and notes the credit rules 'apply as for vessel_port_calls'. It does not explicitly say when to prefer port_calls over vessel_port_calls or vessels_in_area, so there is no full exclusion guidance, but the intended usage is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find ships by name (or part of it), MMSI (9 digits) or IMO number (7 digits). Returns live ships first, then ships out of range with their last known position (up to 7 days). List results are compact rows (mmsi, name, category, flag (ISO code from the MMSI), lat, lon, speed_kn, course_deg, length_m, destination, age_s, status, source); call get_vessel for full details of one ship. Private vessels (pleasure craft, sailing vessels and Class B transponders without a valid IMO number) are never listed or looked up individually; area and nearby results report how many were left out (private_vessels).
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | Yes | Ship name, MMSI (9 digits) or IMO (7 digits) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover safety (readOnlyHint, idempotentHint, destructiveHint false), and the description adds substantial extra behavior: live vessels ordered before out-of-range ones with positions up to 7 days old (age_s), the compact row shape, and the policy that private craft are never returned while area/nearby results roll them into a private_vessels count. That is unusually rich disclosure for a search tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the lookup keys, then result ordering, then row shape, then exclusions — a sensible priority order. It is a long single block of text, but nearly every clause carries distinct information; only the parenthetical row-field list is slightly list-heavy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description does the work of enumerating the returned fields and the ordering semantics, and it covers the private-vessel edge case that would otherwise surprise an agent. Gaps remain around the limit parameter and whether results are truncated when the query matches many ships.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50%: query is documented in both places, but limit (default 10, max 20) is never mentioned in the description, so the cap and default behavior are left entirely to the schema. The description restates the query format (name part, 9-digit MMSI, 7-digit IMO) rather than adding new syntax guidance, so this lands at the baseline for partial coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb (find) plus resource (ships) and the three lookup keys (name/partial name, 9-digit MMSI, 7-digit IMO). It explicitly routes to get_vessel for full details, which cleanly separates it from the sibling that returns one full record.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It states what the tool is for and names the alternative (get_vessel) for the full-detail case, and it declares the exclusion rule for private vessels. It never contrasts itself with the other discovery siblings (vessels_in_area, vessels_near, vessel_track), so the agent must infer that geospatial lookup belongs elsewhere.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Port calls of a ship between two times (UTC, ISO 8601), from the AIS Trail archive: port, arrival, departure, draught on arrival and departure, cargo estimate (loaded, ballast or unchanged, from the draught change), previous and next port. Give mmsi or imo. A port call starts when the ship stops for at least 15 minutes inside a port area and ends when it leaves; departure is null while it is still in port. Needs an AIS Trail API key sent by the MCP client as the HTTP header 'Authorization: Bearer ap_live_…'. At most 100 port calls per call and at most 366 days; the plan's history depth, credits (1 per port call returned), rate limit and 24-hour delay (on plans without live data) apply.
| Name | Required | Description | Default |
|---|---|---|---|
| to | Yes | End, e.g. 2026-10-01T00:00:00Z | |
| imo | No | ||
| from | Yes | Start, e.g. 2026-09-01T00:00:00Z | |
| mmsi | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the readOnly/idempotent annotations: it discloses the required auth header format, the 100-port-call and 366-day caps, per-call credit cost, rate limits, plan history depth, and 24-hour delay on non-live plans. It also defines the domain rule for what constitutes a port call (15-minute stop) and that departure is null while in port.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Purpose and return fields are front-loaded, and nearly every clause earns its place (auth, limits, edge cases). It is a dense run-on paragraph that could be split into structured bullets for scannability, but nothing is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description correctly enumerates return fields, plus auth, rate limits, page caps, history depth and the null-departure edge case. An agent has everything needed to call it correctly and interpret the result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 50% schema coverage (imo/mmsi undocumented in schema), the description compensates by explaining that a ship is identified via 'mmsi or imo' and that times are UTC/ISO 8601. It adds the identity semantics the schema lacks, though it doesn't clarify that the two identifiers are alternatives or how conflicts are resolved.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('Port calls of a ship between two times') and enumerates the returned fields (port, arrival, departure, draught, cargo estimate, prev/next port), which distinguishes it from the sibling 'port_calls' by scoping to a single identified ship. An agent can tell exactly what this returns.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Names the required ship identifier ('Give mmsi or imo') and defines the time-window inputs, giving implied usage, but there is no explicit statement of when to prefer this over the sibling 'port_calls', nor any exclusions. Usage is inferable but not routed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Ships heard in the last hour inside a box (at most 5° on each side), largest first. List results are compact rows (mmsi, name, category, flag (ISO code from the MMSI), lat, lon, speed_kn, course_deg, length_m, destination, age_s, status, source); call get_vessel for full details of one ship. Private vessels (pleasure craft, sailing vessels and Class B transponders without a valid IMO number) are never listed or looked up individually; area and nearby results report how many were left out (private_vessels).
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| max_lat | Yes | ||
| max_lon | Yes | ||
| min_lat | Yes | ||
| min_lon | Yes | ||
| ship_type | No | Optional type filter |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly/idempotent annotations, it discloses the 1-hour observation window, the 5° box-size limit, sort order, and a privacy rule with an observable side effect (private vessels never listed, counted in private_vessels). These are behavior traits an agent could not infer from the schema or annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with purpose, scope and ordering before the result-row inventory and the get_vessel pointer. The embedded field list is dense but earns its place given there is no output schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description carries the return-shape burden and does so by listing result-row fields, and it explains exclusion semantics. It omits pagination/limit behavior and the meaning of the ship_type categories, which are minor residual gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is low (17%), but the description clarifies the geographic parameters by stating the box constraint ('at most 5° on each side'), which is not in the schema. It says nothing about limit semantics or the ship_type filter, so it only partially compensates.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource ('Ships heard in the last hour inside a box'), plus scope (last hour, max 5° per side) and ordering (largest first). It is clearly distinguishable from siblings like vessels_near and search_vessels without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly routes deep-dive calls to get_vessel ('call get_vessel for full details of one ship'), which is real alternative guidance. It does not, however, explain when to prefer this tool over vessels_near or search_vessels, so the guidance is clear but not exhaustive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Ships heard in the last hour within a radius (at most 50 nautical miles) of a point or of another ship, nearest first. List results are compact rows (mmsi, name, category, flag (ISO code from the MMSI), lat, lon, speed_kn, course_deg, length_m, destination, age_s, status, source); call get_vessel for full details of one ship. Private vessels (pleasure craft, sailing vessels and Class B transponders without a valid IMO number) are never listed or looked up individually; area and nearby results report how many were left out (private_vessels).
| Name | Required | Description | Default |
|---|---|---|---|
| lat | No | ||
| lon | No | ||
| mmsi | No | Use this ship's position as the centre instead of lat/lon | |
| limit | No | ||
| radius_nm | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld=false), and the description adds genuinely non-structured behavior: a one-hour recency window, a hard 50 nm radius cap, nearest-first ordering, the exact compact row fields returned, and the private-vessel exclusion policy with the private_vessels omission count.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two dense sentences, front-loaded with the core behavior (recency, radius, ordering) before the row shape and the private-vessel caveat. The field enumeration is long but earns its place by describing the return payload absent an output schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterized read tool with no output schema and sparse schema descriptions, the description supplies the filtering semantics, ordering, return fields, and privacy policy. Nothing an agent needs to call and interpret this correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 20% (mmsi is the sole documented param), so the description must compensate. It clarifies the two mutually exclusive centering modes (point via lat/lon vs another ship via mmsi) and restates the radius bound, though it never explains limit or the default radius of 5 nm.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb/resource ('Ships heard in the last hour within a radius ... of a point or of another ship') plus scope (50 nm cap), ordering (nearest first), and a named sibling for a different task (get_vessel). An agent can distinguish this from vessels_in_area/search_vessels by the radius-of-point/ship framing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly routes the agent: 'call get_vessel for full details of one ship,' and the radius framing implies the nearby-lookup use case. It stops short of contrasting with siblings like vessels_in_area (area vs radius) or search_vessels, so no exclusions are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Where a ship has been between two times (UTC, ISO 8601), from the AIS Trail archive. Needs an AIS Trail API key sent by the MCP client as the HTTP header 'Authorization: Bearer ap_live_…' (keys at https://aistrail.com); clients that cannot add headers (OAuth-only web connectors) cannot use it yet. Resolution: raw (up to 24 h per call), 1m (up to 7 days) or 1h (up to 366 days); at most 200 points per call, as rows of [time, lat, lon, speed_kn, course_deg]. The plan's history depth, credits (as on the track endpoint: 1 per vessel-day) and rate limit apply, and the 24-hour delay on recent data on plans without live data. sources_through gives, per source, the time up to which the archive holds its data; pending_days lists days in the range a source has not delivered yet, so no points on those days does not mean the ship was absent.
| Name | Required | Description | Default |
|---|---|---|---|
| to | Yes | End, e.g. 2026-10-02T00:00:00Z | |
| from | Yes | Start, e.g. 2026-10-01T00:00:00Z | |
| mmsi | Yes | ||
| resolution | No | 1m |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only, idempotent, non-destructive and open-world traits, yet the description adds substantial operational context beyond them: header-based auth, per-resolution time caps, a 200-point-per-call ceiling, credit cost of 1 per vessel-day, plan rate limits, and a 24-hour delay on recent data for plans without live data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads purpose, then auth, then resolution/limits, then result semantics and archive caveats in a single dense paragraph. Every clause carries actionable information, though the run-on length slightly hurts scannability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description still explains the response shape (rows of time, lat, lon, speed_kn, course_deg) and the two metadata fields sources_through and pending_days, including the key caveat that missing days may reflect non-delivery rather than absence. Nothing essential for correct invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50% (mmsi and the resolution enum carry no descriptions), and the description compensates by explaining what each resolution means and its maximum span (raw up to 24 h, 1m up to 7 days, 1h up to 366 days). It also defines the returned row tuple, though it never clarifies mmsi or reinforces the from/to semantics beyond the schema examples.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('where a ship has been between two times') plus the data provenance (AIS Trail archive) and time basis (UTC ISO 8601). This clearly separates it from get_vessel (current/static state) and vessel_port_calls without the reader opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit preconditions and an exclusion: an AIS Trail API key must be sent as an Authorization header, and OAuth-only web connectors cannot use it yet. It does not name a sibling alternative for agents that lack a key (e.g. get_vessel for last known position), so it stops 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.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
data_statusfind_portget_vesselport_callssearch_vesselsvessel_port_callsvessel_trackvessels_in_areavessels_nearLive AIS vessel positions by MMSI, name, area, or radius, plus coverage. No sign-in, no key.
Vessel Tracking — live worldwide ship positions from AIS.
Live AIS vessel tracking for the Baltic Sea and Gulf of Finland via Fintraffic's open Digitraffic
Maritime intelligence: vessels, tracks, port calls, company fleets and sanctions screening, sourced.
Add one secure layer between your agents and this server.