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

The destructiveHint=true annotation already signals that deletion is possible and irreversible, and the description stays consistent with that. It adds genuine behavioral detail the annotation lacks — that sending null for `flag` or `hullType` clears the stored value, and the null-vs-omit distinction. It does not cover optimistic-concurrency failure behavior, permission requirements, or what happens on a conflicting update.

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?

Well front-loaded — purpose first, then field semantics in compact sentences. The closing lines about distances being integer meters and durations integer seconds are boilerplate that does not correspond to any field in this schema, which is minor waste and slightly confusing given the length field is `loaCm`.

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?

The three-branch anyOf schema (create/update/delete) is complex, and the description maps cleanly onto it, but it never explains `expectedUpdatedAt` or the concurrency semantics behind it — a meaningful gap for the update branch. With no output schema, the agent also gets no hint about what a successful call returns.

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 baseline is 3, but the description earns above baseline by explaining what the schema cannot: null clears `flag`/`hullType` rather than leaving them untouched, the exact ISO 3166-1 alpha-2 form of the flag, and the 6-character case-sensitive ID format. The trailing notes on timestamp/distance/duration units are generic and mostly do not map to any field here.

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 set and resource: 'Create, update or delete one of the caller's boats.' An agent immediately knows this is the mutating counterpart to ship_read and that scope is limited to the caller's own boats. It stops short of naming the sibling read tool explicitly, so it is clear but not sibling-differentiating in the strongest sense.

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 by the verb set — use this for any boat mutation — but there is no explicit when-to-use guidance, no statement that ship_read should be used for retrieval, and no mention of the prerequisite of having an id or an expectedUpdatedAt value before updating. The agent must infer the workflow.

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