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

Annotations already declare a safe, idempotent, read-only, open-world operation, and the description goes well beyond that: it discloses that long tracks are evenly thinned to max_points while the credit charge still covers the full range, that coverage is limited to sources that may be passed on, and that depth is capped at 90/365 days by plan tier. It also states the auth requirement (a paid Data API Plus/Pro/Scale or paid Watch plan) and the exact cost model of 1 credit per vessel-day with positions, which are precisely the facts an agent needs before committing a paid call.

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 front-loaded with what the tool returns and how to scope the window, then layers cost and plan constraints. The fragment "Reach back: 90 days on Plus, 365 on Pro and Scale" is slightly clipped, but no sentence 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 and a 5-parameter read tool, the description covers the important unknowns: ordering, thinning behavior, coverage limits, credit cost, and plan gating. The only gap is that it never characterizes the shape of an individual position record (e.g. timestamp/lat/lon), which an agent may want when chaining calls.

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 meaning on top: it clarifies the hours-vs-from/to relationship, gives the 72-hour default for hours, and explains the semantic consequence of max_points (even thinning for readability) rather than just its range. Only the mmsi parameter receives no added context, which the schema already handles.

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?

"One vessel's recorded positions, oldest first" names the resource (position history for a single MMSI) and the ordering, which cleanly separates it from static lookups like get_vessel, summaries like vessel_activity, and aggregates like vessel_port_calls. An agent can tell what it will get back without opening the 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?

The description explains the two mutually exclusive ways to bound the query (hours back from now, or a from/to window) and states the hours default of 72, which is genuine usage guidance. However, it never says when to pick this tool over neighboring track-like tools such as vessel_activity or vessel_port_calls, so the agent must infer the choice from names alone.

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