Where Boats Anchor

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

Annotations already establish that this is a read-only, idempotent, non-destructive lookup, and the description adds substantial behavioral detail: result ordering, per-place distance/direction, nights-in-wind counts, and the special ranking rule for tonight. It does not contradict the annotations, but the explanation is dense and some counting rules are hard to follow.

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 purpose is front-loaded, but the body is long, run-on, and repetitive, especially around tonight, compass points, and how nights are counted. Several sentences require re-reading, which hurts usability for an agent deciding how to call the tool.

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?

Given six parameters, a required lat/lon pair, and an output schema, the description supplies enough to choose between tonight mode and wind mode and to understand the result ordering. Since an output schema exists, some of the return-value explanation is more than strictly necessary, but nothing critical appears 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 100%, so all six parameters are documented in the schema. The description still adds meaning beyond the schema by explaining wind_from/wind_kn interaction and how wind speeds are bucketed into compass points at 10 or 20 kt thresholds.

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: it lists nearby places where boats stopped, overnight or by day, under either tonight's forecast or a supplied wind. That is clearer than the title alone, though it does not explicitly distinguish itself from siblings such as get_climatology or get_bay_evidence.

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 mode-selection guidance: omit wind_from and wind_kn for tonight's forecast, and supply a wind only when asking about that wind. It also states that wind_kn requires wind_from. It stops short of explaining when to choose this tool over its siblings.

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 readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavioral facts beyond that: ambiguous names return candidates rather than a guess, small-sample cells under 3 boats are returned as null, and the response carries tonight's forecast. These are the kind of data-shape caveats annotations cannot express.

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 the purpose, but the body is a dense run-on that repeats itself ('Its nights. Its nights by the eight compass points...') and enumerates return fields at length even though an output schema exists. The information is useful, but the phrasing is tangled and over-long.

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?

Given a 3-param, zero-required tool with an output schema, the description covers identification paths, ambiguity handling, and data caveats thoroughly. It arguably over-explains return content that the output schema already carries, but nothing an agent needs in order to call it 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 100%, so baseline is 3, but the description adds the interaction logic the schema cannot: name alone is ambiguous, name plus near ranks candidates by proximity, and bay_id is the unambiguous path used by find_anchorages/list. That clarifies how the three params combine rather than restating them.

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 title and opening line establish a specific verb+resource: retrieve recorded boat behavior at a single place (anchorage/bay). The body enumerates exactly which datasets come back (nights, wind rose by compass point and speed band, boats by length/type, day stops, swell direction, nearby places, tonight's forecast), so an agent knows precisely what it gets. It does not explicitly contrast with sibling get_climatology, so it stops just short of a 5.

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 the identifying inputs ('Give bay_id, or name with near ... to rank places of one name') and warns that multiple places of one name come back as candidates, which is real usage context. However, there is no explicit when-to-use-this-instead-of-X guidance against find_anchorages or get_climatology, so the routing is left implicit.

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/non-destructive, so the bar is lower, and the description still adds a genuinely non-obvious trait: the first call for an area may return 'preparing' and become 'ready' a few minutes later, implying polling. It also discloses the ten-year aggregation window and the geographic scope ('the area round the place'). It stops short of saying how long results are cached or whether 'preparing' responses consume quota.

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 sentence stacking five distinct statistics, which is hard to parse and front-loads the payload rather than the action. The phrase 'as its page shows it' is vague filler that does not help an agent decide or invoke. The async caveat at the end is well placed, but the body could be a short list.

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?

An output schema exists, so most of the long enumeration of return values is redundant effort, while the one thing that is not in structured data — the preparing/ready lifecycle and whether to re-call — is mentioned but not elaborated (no retry interval, no indication of how long results persist). With 100% schema coverage and a single optional parameter, the definition is serviceable but spends its words in the wrong place.

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%, with both month and bay_id fully documented including the default-to-every-month behavior and the find_anchorages provenance of bay_id. The description adds nothing about parameter syntax or how selecting one month interacts with the ten-year aggregation, so the baseline 3 applies.

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 the resource (wind climatology at a place) and enumerates the specific statistics returned: monthly counts of nights reaching 20 kt and 30 kt, per-year min/max, prevailing directions, and strongest gust over ten years. It is unmistakably a read of historical wind statistics rather than an anchorage search, though it never names the sibling tools it differs from.

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 statement of when to call this versus get_bay_evidence or find_anchorages, and no prerequisites or exclusions. The only actionable guidance is the async note ('first call can answer preparing, then ready a few minutes later'), which tells the agent to retry but not when this tool is the right choice.

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 readOnlyHint, idempotentHint, and openWorldHint=false, so the safety profile is covered. The description adds real behavioral value beyond that: result shape per mode, that each entry carries a place count, and that each includes the address of its directory page.

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?

Three tight, front-loaded sentences with no filler; the default-vs-filtered distinction is stated before the return detail. The opening phrase 'places where boats stayed the night' is slightly indirect but earns its place as domain framing.

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 single optional-parameter read tool with full schema coverage and an output schema, the description covers both call modes and what each result entry contains. Pagination or count freshness are unmentioned, but 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 100% and the schema itself already explains the slug/ISO format and the 'every country when left out' default. The description restates this behavior without adding format examples or edge-case handling beyond the schema, so baseline 3 applies.

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 concrete resource (the site's directory of places/countries/regions/cruising areas) and states what is returned in each mode. It is clearly a geographic directory listing, distinguishable from find_anchorages or get_climatology, though sibling differentiation is only implicit rather than stated.

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 describes the two call modes — omit `country` for the country list, supply it for regions/cruising areas — which gives practical guidance on parameterization. However, it never says when to prefer this tool over find_anchorages or get_bay_evidence, so tool-selection guidance is only implied.

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