AIS Trail

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.

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

Annotations already declare readOnly, idempotent, closed-world and non-destructive, so the bar is lower; the description still adds real context: a hard 20-result cap, deterministic ordering ('larger harbors first'), no API key requirement, and the caveat that harbor size only exists for World Port Index ports. It does not say what an empty result looks like, but the operational profile is well covered.

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 accepted query modes are front-loaded in the first clause, followed by the return fields, then two short constraint sentences. It is dense but every clause carries information; the only mild cost is a long comma-laden first sentence that takes effort to parse.

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 burden of describing returns and does so by enumerating every field, plus the port-area radius used for port-call detection. Combined with the result cap and ordering, an agent has everything needed to call this reference-lookup tool 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 100%, so the baseline is 3; the description earns above that by clarifying that 'query' matches on part of a name, giving format examples for locode and country, and reinforcing the 20-item ceiling that pairs with the limit parameter. It stops short of explaining precedence when multiple filters are supplied together.

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 accepted lookup modes with concrete examples (FIHEL, FI). It also lists exactly what comes back (id, name, country, UN/LOCODE, position, harbor size, port-area radius), so an agent can distinguish it from vessel-oriented siblings like get_vessel or port_calls at a glance.

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 implicitly defines when the tool is appropriate by spelling out the three valid query forms, and the note that id is 'for port_calls' hints at the downstream sibling relationship. But there is no explicit 'use this instead of X' or exclusion guidance against port_calls or vessels_near, leaving the routing 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.

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

Beyond the readOnly/idempotent annotations, it discloses meaningful behavioral context: the response includes 'how long ago it was heard' (freshness), a 40-minute track window, and 'the data sources to credit'. It also flags two substantive caveats — flag is the radio-licence flag from the MMSI and may differ from the registry flag, and dwt_estimate is derived from AIS dimensions and is null for tugs and pleasure craft.

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 returned-field inventory, then caveats, then the alternative. It is dense and long, but with no output schema each clause is doing real work; only the field enumeration borders on sprawling.

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?

There is no output schema, and the description compensates fully by describing return contents, freshness semantics, provenance, and the limits of two derived fields, plus a routing note. An agent has everything needed to call it 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?

Schema coverage is 100% for the single mmsi parameter, so the schema already carries the burden and baseline is 3. The description adds some meaning by explaining what the MMSI encodes (radio licence flag) and what is derived from it, but it adds nothing about the parameter's format or constraints.

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 enumerates exactly what 'get_vessel' returns for a single ship: identity, position, motion, navigational status, destination, ETA, freshness, a 40-minute track, and provenance. It is unmistakably a single-vessel detail lookup, and it explicitly separates itself from lookup_vessels for archive/sanctions data.

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 a concrete routing rule: 'For archive records and sanctions flags, use lookup_vessels (API key)', implying this tool serves live/current snapshots. It does not distinguish against other close siblings like vessel_track or vessels_near, 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.

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

Annotations already declare the read-only, idempotent, open-world, non-destructive profile, and the description layers on genuinely new operational context: required 'Authorization: Bearer ap_live_…' header, credit cost (1 per ship returned, free for misses), the plan's source set and 24-hour delay, and the explicit limits of the sanctions matching. This is well beyond what the structured fields convey.

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 inputs are front-loaded in the opening clause, and the later sentences (sanctions caveat, auth, credits, delay) all carry decision-relevant information rather than filler. It is a single dense block that would read better broken into lines, but 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 so thoroughly: enumerates identity/particular fields, sanctions fields (list, programmes, date listed), and the found-false sentinel. Auth, cost, and data-freshness caveats complete the picture for a 2-parameter tool.

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 100%, so the baseline is 3, but the description adds real semantics: the 20-item cap applies to mmsi and imo combined, and 'an IMO number resolves to the MMSI that reported it last' explains resolution behavior the schema cannot express.

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 (lookup) plus resource (ships/vessels) and pins down the input mode: batch of up to 20 by mmsi and/or imo lists from the AIS Trail archive. That scope statement is enough to distinguish it from single-vessel or name-based siblings, though it never names those siblings explicitly.

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: the batch-of-20, identifier-list framing tells an agent this is for bulk identity resolution rather than search or tracking, and the 'found false' note covers the miss case. There is no explicit when-to-use/when-not or named alternative (e.g. search_vessels for name lookup, get_vessel for a single ship).

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

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

Goes well past the readOnly/idempotent annotations: discloses the required API key and exact header format, the 100-call and 366-day caps, the 1-credit-per-port-call cost model, and explicitly frames the sanctions column as informational rather than a compliance determination. These are the operational constraints an agent would otherwise trip over.

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?

A single dense paragraph that front-loads the resource and scope, then moves to routing, filters, caveats, and limits in a sensible order. It is long-ish but nearly every clause carries a constraint an agent needs; the sanctions sentence and the vessel_port_calls billing pointer could be tightened.

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?

No output schema exists, and the description compensates by listing the returned columns including the sanctions codes and their caveat. Auth, pagination-style caps, date-range limits, and credit cost are all covered, leaving nothing material unstated for a read-only lookup.

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 100%, so the baseline is 3; the description still adds value by stating times are UTC ISO 8601 and by reinforcing that port_id comes from find_port and that event defaults to 'any' with its in-port-anytime semantics. It does not add anything for the from/to boundary inclusivity, but coverage is otherwise solid.

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 and resource ('Ships that called at one port between two times') and enumerates the returned fields (ship/flag, arrival, departure, draught, cargo estimate, previous/next port). It distinguishes itself from fixed siblings by naming find_port for the port_id and pointing at vessel_port_calls for plan rules.

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 clear prerequisites ('Get the port_id from find_port') and defines the event selector's three modes with defaults, which is exactly what an agent needs to choose parameters. It does not explicitly state when to prefer this over a sibling like vessel_port_calls or vessel_events, only that billing follows vessel_port_calls.

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

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

Beyond the readOnly/idempotent annotations, the description discloses result ordering (live ships first, then out-of-range with last known position up to 7 days) and a privacy rule excluding private vessels/Class B without IMO, with a private_vessels count reported in other tools. These are non-obvious behavioral traits an agent could not infer from 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 the search capability and identifiers, then the return-row contract, then the sibling pointer. It is dense but every clause carries information; the long field enumeration is the only mildly heavy element.

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 fully carries the return contract: exact compact row fields include mmsi, name, flag ISO code derivation, speed/course units, age_s, status, source. Combined with the ordering and privacy rules, an agent has everything needed to interpret results.

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%, so both parameters are already documented. The description adds only marginal meaning—confirming partial-name matching, which the schema does not state—but says nothing about the limit parameter or its 1–20 cap. Baseline 3 is appropriate.

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 opens with a specific verb and resource ('Find ships') and names the exact identifier types accepted (name fragment, 9-digit MMSI, 7-digit IMO). It also explicitly routes detail lookups to a named sibling ('call get_vessel for full details'), distinguishing it from the broader lookup/nearby/area tools.

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 implies the right context (identifier-based lookup) and names the alternative for full records ('call get_vessel'). It does not explicitly exclude the other search-like siblings (lookup_vessels, vessels_near), so the agent must infer when identifier search beats area search.

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

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.

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.

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.

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.

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.

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.

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

Goes well beyond the readOnly/idempotent annotations: defines port-call semantics (starts when stopped inside a port area, ends on leaving), notes departure is null while in port, flags the sanctions column as informational only, and discloses credit cost, rate limits and the 24-hour delay on non-live plans.

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 core purpose and return fields, then constraints and auth in descending priority. It is a dense single paragraph; splitting the access/limit caveats into their own sentence would scan better, but no clause 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 fully compensates by listing every returned field (port, arrival, departure, draughts, cargo estimate, adjacent ports, sanctions) and covering auth, limits and known-unknown behaviors like the null departure.

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 100%, so the baseline is 3, but the description adds value by stating 'give mmsi or imo' — the schema marks neither as required, so this clarifies a real constraint the structured data leaves ambiguous, and confirms UTC/ISO 8601 for the time bounds.

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 ('Port calls of a ship between two times ... from the AIS Trail archive') and enumerates the returned fields, so the agent knows exactly what it gets. The archive/API-key framing plus the title's '(API key)' distinguishes it from the sibling port_calls variant.

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 clear operating context: supply mmsi or imo, a UTC ISO 8601 window, max 100 calls and 366 days, and that an AIS Trail API key is required via the Authorization header. It does not explicitly contrast with siblings like vessel_events or vessel_track, so an agent must infer which to prefer.

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

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

Annotations already cover the safe-read profile (readOnly, idempotent, non-destructive), and the description adds substantive behavior beyond them: a one-hour recency window, a maximum 5° box, largest-first ordering, and the non-obvious policy that private vessels are never returned but are counted in a private_vessels field. That exclusion rule is the kind of hidden behavior an agent could not infer from 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 the core scope, constraint and ordering before the detail list, with zero filler. The compact row field enumeration is long but justified because there is no output schema; it could still be tightened slightly.

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 six-parameter read tool with no output schema, the description supplies the return shape, the recency semantics, the bounding-box limit, the ranking, the private-vessel exclusion with its counter, and the escalation path to get_vessel. Only the failure mode for an oversized box is unstated, which is a minor gap.

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 100%, giving a baseline of 3, but the description contributes meaning the schema lacks: the 5° per-side cap on min/max lat/lon and the 'largest first' implication for the limit parameter. Only ship_type is left unmentioned.

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 resource (ships), a precise scope (heard in the last hour inside a bounding box), a hard constraint (box at most 5° per side) and an ordering (largest first). This clearly separates it from the radius-based vessels_near and the name-based lookup_vessels/search_vessels siblings.

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 to get_vessel when full detail on a single ship is needed, and the box-size cap tells the agent this tool is not usable for wide-area queries. It never names a competing sibling (e.g. vessels_near for radius searches) or states exclusions, so it falls short of a full when/when-not map.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description adds substantial behaviour: a one-hour recency window, a hard 50 nm cap, nearest-first ordering, and a documented privacy exclusion for private vessels with a private_vessels count returned. That privacy rule is a non-obvious constraint that would otherwise cause silent under-reporting.

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 scope, then the return shape, then the alternative, then the caveat — a sensible order. The parenthetical field enumeration is long but earns its place because there is no output schema; it is still dense enough that a skim could miss the privacy clause.

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 compensates by listing the compact row fields end to end, and it discloses both the truncation cap and the private-vessel exclusion count. An agent has everything needed to call this correctly and interpret the response.

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 100%, so lat/lon/mmsi/limit/radius_nm are all documented with the centre-or-ship choice and defaults. The description's radius cap restates the schema maximum rather than adding syntax or tie-breaking detail, so it stays at the baseline 3.

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 resource (ships) with precise scope: heard in the last hour, within a radius, centred on a point or another ship, nearest first. The radius framing cleanly distinguishes it from area-based siblings like vessels_in_area, and the get_vessel pointer handles the single-ship case.

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 to get_vessel when full details of one ship are needed, and the radius framing implies a proximity use case. It does not, however, contrast itself with the other nearby siblings (vessels_in_area, search_vessels, lookup_vessels), so the agent must infer that boundary.

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

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

Goes well beyond the readOnly/idempotent/openWorld annotations: it discloses the API-key requirement and exact header format, plan-dependent history depth, credit cost (1 per vessel-day), rate limiting, the 24-hour delay on recent data for plans without live data, a 200-point cap per call, and the row shape returned. It also explains that missing points may reflect undelivered source days via sources_through/pending_days rather than vessel absence — a genuinely important behavioral caveat.

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 core purpose, then constraints, then return semantics — a sensible order. The prose is dense with long parenthetical clauses (auth, resolution, credits) that could be split for scanability, but every sentence carries operative information.

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?

There is no output schema, and the description compensates fully by describing the returned row format ([time, lat, lon, speed_kn, course_deg]) and the sources_through/pending_days metadata. Auth, limits, cost, and data-freshness caveats are all covered, so 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 100%, so the baseline is 3; the description earns above that by adding the hard limits tied to each resolution value and the 200-point-per-call ceiling, which constrain how an agent should set the range and resolution. mmsi and from/to are left to the schema, which already documents them adequately.

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 source (AIS Trail archive). It is clearly distinguishable from siblings like vessel_events, port_calls, or get_vessel, which return events, port visits, or current/static data rather than a positional track.

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 concrete selection guidance for the resolution parameter (raw up to 24 h, 1m up to 7 days, 1h up to 366 days) and an explicit exclusion: clients that cannot add HTTP headers (OAuth-only web connectors) cannot use this tool. It does not name sibling tools as alternatives for narrower questions, so it stops short of a full when/when-not map.

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