Seamark

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

Annotations only declare readOnlyHint=true; the description goes well beyond that by disclosing the shared-trip access asymmetry, the meaning of statsSource, the provenance rule for weather fields, and the exact units/conventions (knots, meteorological degrees, Douglas sea state) of the returned data. This is rich behavioral context that structured fields do not 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?

Well front-loaded: purpose, then the access quirk, then data semantics. Every sentence carries information, but the trailing block of unit/format facts reads as a dense dump rather than a structured list, which slows scanning 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?

There is no output schema, so the description correctly takes on return-value explanation (field provenance, units, ID/timestamp formats) while also covering the access edge case for shared trips. Nothing needed to invoke or interpret the response 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 description coverage is 100% and the anyOf structure already encodes the action/tripId vs action/id split, so the baseline is 3. The description still adds meaning beyond it: the action values are illustrated ('list them, or get one by id'), the access rule is attached to the action choice, and ID semantics ('6-character case-sensitive') are spelled out even where the regex only implies 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?

States a specific verb and resource ('Read a trip's ordered legs') and immediately splits the two modes ('list them, or get one by id'), so an agent knows exactly what the tool returns. It also implicitly distinguishes itself from trip_read by describing the shared-trip case, which is where the two overlap.

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?

Provides an explicit when-to-use rule for get vs list, plus a when-NOT/alternative: on a trip shared with the caller, list will not return the legs and the agent should use trip_read's get instead. That is exactly the routing decision an agent needs and it is not derivable from the schema.

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 supply only destructiveHint=true, so the description carries the rest and does so in depth: track-backed legs reject updates touching computed fields, fetch_weather is the sole outbound network call with a 30/hour/user rate limit, it overwrites existing wind including hand-entered values, and weatherSource flips back to 'manual' on a hand edit but not on seaState. This is far richer than the annotation provides, and nothing contradicts destructiveHint.

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 action list is correctly front-loaded, but the body is a dense wall of very long sentences with stacked parentheticals (e.g. the speed-weighted circular-mean direction clause), some of which is more implementation detail than an agent needs to invoke the tool. Every fact is relevant, yet the packing 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?

For a five-action mutation tool with no output schema and no declarative annotations, the description covers side effects, error codes, format conventions, and reorder's full-permutation requirement. It does not explain the expectedUpdatedAt optimistic-concurrency parameter or what each action returns, leaving modest 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 coverage is 100%, so the baseline is 3, but the description adds genuinely non-schema meaning: windDirDeg is an integer 0-359 in meteorological convention (direction FROM), windSpeedKn is true wind speed, seaState is the Douglas degree 0-9, IDs are 6-character case-sensitive alphanumerics, timestamps are UTC ISO 8601, distances integer meters, durations integer seconds. These conventions cannot be inferred from constraints alone.

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 opening sentence names the resource (a trip's ordered legs) and enumerates every action verb supported: create, update, delete, reorder, and wind-fill via fetch_weather. The 'Change' framing and the mutation verbs clearly separate it from the sibling leg_read, so an agent can route 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?

Each action's intended use is spelled out, including the conditions that select fetch_weather versus hand-entry, and the failure modes (weather_no_position 422, weather_unavailable 503, stats_readonly). It stops short of an explicit 'use leg_read to view / use this tool only to mutate' contrast with siblings, but the mutation scope is unambiguous.

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=true, so safety is covered; the description adds real behavioral context beyond that: personal data is never shared across users, and it explains the semantic meaning of linkedAccount and the singleton isSelf flag. It stops short of describing pagination or ordering for the list mode.

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 the core purpose and the two modes in the first sentence, then adds field semantics. The trailing unit conventions (timestamps, distances, durations) are boilerplate that adds little for a tool with only an id parameter, so it is not fully waste-free.

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 return-value burden and does explain two key fields (linkedAccount, isSelf) plus the privacy boundary on birth date/passport. It does not enumerate the rest of the returned person attributes, leaving a modest gap for a read 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 meaning beyond the schema pattern: IDs are stated to be case-sensitive 6-character alphanumeric strings (the pattern alone does not convey case sensitivity), and it establishes unit/format conventions for the data returned.

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 ('Read the caller's private address book of people — crew and contacts') plus the two supported modes ('list them all, or get one by id'). It is clearly distinguishable from person_write and whoami 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?

The listing-vs-get-by-id split gives implied mode selection guidance, but there is no explicit when-to-use versus siblings like person_write, trip_read, or whoami, and no exclusions or prerequisites. Adequate but leaves routing to inference.

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 far beyond the lone destructiveHint annotation: it discloses invite rate limits (1/min per person, 3/hr per address, shared budget), the 409 invitation_no_trips precondition, idempotency of unlink_account/mark_self, that invite replaces prior invitations and advances updatedAt, and that unlink_account cancels pending invites. This is exactly the kind of hidden-behavior context that prevents wrong calls.

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 in the first sentence and every subsequent sentence carries substantive operational detail, but the dense single-block layout with heavy parentheticals and backtick tokens is harder to scan than it needs to be. No sentence is pure filler though.

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 an eight-action mutation tool with no output schema, the description is unusually complete: it explains invitation lifecycle, response contents (new updatedAt, list of opened trips), and error conditions. The notable gap is that delete's consequences (e.g., effect on crew lists of trips) are not described despite destructiveHint.

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 reported at 100%, so the baseline is 3, but the description adds real meaning: ID format (6-character case-sensitive alphanumeric), UTC ISO 8601 timestamps, that invite's email is remembered on the person's email field, that accept_invitation's token must match the caller's own address, and expectedUpdatedAt's role as a version token.

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 first sentence names a specific verb (Change) and resource (the caller's private address book of people — crew and contacts) and enumerates all eight supported actions, so the tool's scope is unambiguous. It is clearly differentiable from person_read.

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 disambiguates sub-actions well (invite vs accept_invitation, unlink_account vs mark_self) and notes the shared rate-limit budget with trip_write's announce, but it never states when to call this tool versus siblings like person_read. The guidance is implied rather than explicit.

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 only supply readOnlyHint=true, so the description carries the real behavioral burden and does: newest-first ordering, the unattributedTripsCount treatment of voyages where the caller is not crew, the caveat that figures are self-logged and unverified, ID format, and total aggregation scope. This is well beyond what the annotation declares.

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?

Everything is front-loaded and every clause earns its place, but it is delivered as one dense run-on paragraph mixing purpose, field semantics, filtering, and caveats. Slight structural grouping would improve scanability without cutting content.

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, so the description must describe the return shape and it does exhaustively: field-by-field (loaCm, ISO 3166-1 alpha-2 countries, sea areas in voyage order, distances in meters, durations in seconds), plus totals scope and ordering. Nothing needed to call or interpret the tool 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 0% and the description compensates fully for all three parameters: role accepts 'all'/'skipper'/'crew' and filters rows, while from/to are YYYY-MM-DD and bound rows inclusively by start date. The meaning the schema cannot express (inclusive, start-date-based, row filtering) is stated.

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+resource framing ('The caller's sailing résumé') and immediately scopes it against the sibling read tools: it is one row per voyage the caller sailed, not the general trip/track/leg readers. An agent can tell it apart from trip_read or stats 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 gives clear usage context ('the record a charter company asks for before handing over a boat') and explains what happens under each filter, but never explicitly names an alternative sibling (e.g. trip_read, stats) or states when NOT to use it. Context is clear; exclusions are absent.

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?

readOnlyHint=true already establishes the safety profile, so the bar is low, and the description still adds real context: the registry is caller-scoped ('the caller's boats'), IDs are 6-char case-sensitive alphanumerics, and unknown fields are null rather than absent. Pagination/ordering behavior of the list mode is not disclosed.

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 mode enumeration are front-loaded and efficient. However the trailing sentences about timestamps, distances and durations appear to be generic field conventions not tied to any input of this tool, and they dilute an otherwise tight definition.

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 two-mode read tool with no output schema, the description covers mode selection, id format, field vocabulary and null semantics, which is most of what an agent needs. It leaves list-mode return shape (pagination, ordering) and error cases unstated.

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% with 0 declared top-level parameters (an anyOf of action:list / action:get+id), so the baseline is high. The description maps directly onto the two schema variants and clarifies the id format and action values, though it then documents `flag`/`hullType`, which are not inputs in the schema and may momentarily confuse call shape.

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 ('Read the caller's boats') and immediately scopes it as a 'reusable, per-owner registry', then enumerates the two modes (list all, get one by id). The read/write split against sibling ship_write is unambiguous from the name plus this phrasing.

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 two usage modes are spelled out ('list them all, or get one by id'), which tells the agent how to shape the call. It offers no explicit when-not guidance or named alternative (e.g. ship_write for mutations), so it lands just short of a 5.

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?

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.

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

With only readOnlyHint available, the description carries real behavioral nuance: unattributed voyages count only under 'all' and surface as `unattributedTripsCount`, and `ownedTripsCount`/`sharedTripsCount` split the log regardless of `role`. These are non-obvious semantics an agent could not infer from the annotation.

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 scope and return shape, then the role filter, then units. Dense but nearly every clause earns its place; the closing unit/type/ID-format reminders are slightly repetitive but useful given 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 compensates by enumerating every returned figure, its units (meters/seconds/knots-null), ordering rules (newest-first years, largest-first boats), ID format, and timestamp conventions. Nothing needed to interpret the result 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 0% in prose, but the description fully specifies `role`: default 'all', with 'skipper'/'crew' filtering every figure by the caller's role on each trip. That is meaning well beyond the bare const enum 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+resource: computes the caller's lifetime logbook statistics over owned and shared trips, with totals, per-year, and per-boat breakdowns. Siblings (trip_read, leg_read, etc.) are entity CRUD tools, so this aggregate tool is unmistakably distinct.

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 context for use — whole-log aggregation including trips shared as linked crew, with the default role of 'all' — but never explicitly names when to prefer it over siblings like trip_read or states exclusions.

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 only supply readOnlyHint=true; the description carries the rest. It adds material behavior not in the structured data: audit results are paged, long tracks produce many audit points, and there is an access asymmetry on shared trips where the audit is restricted to the owner. Return-shape details are only partially covered, keeping it from a 5.

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 core action and modes, then moves to the access caveat and finally to unit conventions. The trailing unit sentences (UTC ISO 8601 timestamps, integer meters, integer seconds) are useful but read as a block of conventions rather than being woven into the relevant sentences.

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 has to convey return semantics, and it does so partially: drop reasons per point, paged audit results, and the unit conventions for timestamps, distances, and durations. It leaves the exact fields of the `get` payload implicit, so a small gap remains.

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 reported at 100%, so the baseline is 3. The description still adds meaning: it explains that offset/limit exist specifically to page audit results and warns that long tracks have many points, plus it reinforces the 6-character case-sensitive alphanumeric ID format stated in the pattern.

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 ("Read a leg's GPX track") and further splits the tool into two concrete modes, `get` (current track) and `audit` (kept/dropped points with drop reasons). It does not, however, explicitly contrast itself with the sibling `leg_read`, which also operates on a leg, so an agent could still hesitate between the two.

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 for both actions and a real usage constraint: on a trip shared with the caller, `get` reads the track but the audit remains owner-only. It does not name alternatives or state explicit "do not use this for X" exclusions, so it falls short of a 5.

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 only give destructiveHint=true, and the description earns that destructiveness: delete makes 'the leg revert to statsSource 'manual', retaining its last computed stats.' It also discloses the distinct inline (5 Mi UTF-16 code units) versus server-side (32 MB / 75,000 trackpoints) pipeline caps and that reprocess runs 'at the current pipeline version.' These are behaviors the annotations cannot 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?

The action is front-loaded, but the definition is one very long sentence with heavily nested parentheticals that bury the actionable content in the middle. The trailing sentence about timestamps, distances, and durations is dead weight here — none of those appear in this tool's input schema and there is no output schema to annotate.

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 multi-mode write tool with no output schema and destructive annotations, the description covers caps, failure paths, and the post-delete state, which is most of what an agent needs. The remaining gaps are the unexplained maxSpeedKn semantics and no mention of what a successful import/reprocess 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?

With 100% schema coverage the baseline is 3, but the description adds real meaning: it clarifies that maxLength counts UTF-16 code units (so the 5 Mi cap is not a byte count), and documents ID format, UTC ISO 8601 timestamps, and integer meters/seconds. The one gap is maxSpeedKn — its unit and purpose (knots, filtering/handling fast segments) are never explained.

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 first clause names a specific verb and resource — 'Change a leg's GPX track' — and then enumerates the three modes (import, reprocess, delete), so an agent knows exactly what the tool does. It is distinguishable from the read sibling track_read by the write verb, though it never names a sibling to route against 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?

It clearly explains which mode applies and, importantly, an alternative path: files over the inline cap 'go through the REST upload route instead' and over the point cap must be split or simplified. It stops short of stating tool-level when-not-to-use or naming a specific sibling tool for the REST route, so it falls just short of a 5.

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 only supply readOnlyHint=true, but the description adds substantial behavioral context: shared trips have their charter and `pickupBase` withheld, `map` omits legs with no geometry, `get_share` returns a public no-login link or null, and `get` composes metadata rather than requiring separate crew/charter reads. These are real disclosure of data-visibility rules beyond the 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?

Every sentence carries information — action semantics, visibility rules, and data-type conventions — with no filler, and the action list is front-loaded. It is, however, one dense unbroken paragraph covering five actions plus output conventions, so structure could be improved.

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 much of the return-value work (GeoJSON FeatureCollection shape, per-leg features, omitted geometry, null share link). It does not explain list pagination/ordering or result counts, a modest gap for a tool that has limit/offset parameters.

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% and the anyOf branches fully constrain each action, so the schema already carries parameter semantics; baseline 3 applies. The description reinforces the ID format ('6-character case-sensitive alphanumeric') but adds no meaning about limit/offset pagination behavior.

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 precise verb+resource and then enumerates each of the five actions (list, list_shared, get, map, get_share) with what each returns, so an agent can tell them apart without opening the schema. It also preempts confusion by noting 'there is no separate crew or charter read' and distinguishes the caller's own log from trips shared with them.

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 explicit routing: `list` is the caller's OWN log, `list_shared` is for trips others shared, and a shared trip is 'readable with `get` and `map` and listed by `list_shared`, never by `list`'. The alternatives and the exclusion condition are both spelled out, leaving nothing to inference.

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?

The only annotation is destructiveHint=true, so the description carries real weight and delivers: announce is rate-limited per trip and per recipient address and reports how many messages actually sent; create_share returns the same URL on repeat calls; the public view is redacted (no charter, initials-only crew) yet semi-public to anyone holding the link. These are exactly the traits an agent needs before firing a mutation.

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 block, but the action inventory is front-loaded and nearly every clause carries new information (units, idempotency, rate limits, redaction). It would scan better as an action list rather than one paragraph, which keeps it just short of a 5.

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 destructive multi-action write tool with no output schema, the description covers data types and units, per-action side effects, rate limits, notification audience filtering (linked account, not opted out in Settings), share idempotency, and the redacted public view. Nothing essential for correct invocation is missing beyond the optimistic-concurrency hint.

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 union schema already encodes the action constants and regex patterns, but the description adds semantics the schema cannot express: charter price/deposit are integer minor units with an ISO 4217 currency and never floats, IDs are 6-character case-sensitive alphanumerics, timestamps are UTC ISO 8601. It does not explain expectedUpdatedAt (optimistic concurrency) or the patch merge semantics, which is the remaining 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?

Opens with a specific verb+resource ('Change the caller's own voyages') and then enumerates every supported action (create, update, delete, set_crew, set_charter, announce, create_share/revoke_share), so an agent knows exactly what the tool mutates. It also carves out the invitation case as belonging to person_write, which separates it from a same-domain sibling.

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 conditions: set_charter with a null clears the charter, create_share is idempotent, revoke_share turns the link off, and crew invitations belong to person_write's invite/accept_invitation rather than here. It does not explicitly route read operations to trip_read, but the ownership scoping ('caller's own trips') makes the boundary clear.

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=true, so the safe-read profile is covered. The description adds that the caller must be authenticated and supplies value-format conventions (6-character case-sensitive IDs, UTC ISO 8601 timestamps, meters, seconds), but several of these (distances, durations) are not fields this tool returns, suggesting generic boilerplate.

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 correctly front-loaded in the first sentence. However, the trailing format conventions are generic and partly irrelevant to the four fields actually returned, so not every sentence earns its place.

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 the return value, and it does so by listing the four profile fields. The only gap is the absence of guidance about when this tool is preferable to person_read.

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 has zero parameters and the description explicitly confirms 'Takes no arguments', matching the empty schema with additionalProperties:false. Baseline 4 applies for a no-parameter tool.

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 resource and scope: the authenticated caller's own profile, with the returned fields enumerated (id, email, name, language). This implicitly distinguishes it from the sibling person_read, since it is scoped to the caller rather than an arbitrary person, though the sibling is never named.

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 when-to-use guidance and no reference to alternatives such as person_read. 'Takes no arguments' is a usage fact but not a routing rule, so an agent gets no help deciding between this and the other read tools.

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