Charter Boats

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

Annotations only declare a non-read-only, non-destructive, closed-world write; the description adds genuinely non-obvious behavior - that on a partner-synced boat the hold propagates to that partner and, with X-Lock on, to the other partner - plus a statement of what is returned. It stops short of covering conflict/overwrite handling or auth needs, so not 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?

Two tightly packed sentences with the core action front-loaded and zero filler; the propagation caveat and return note each earn their 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?

No output schema, but the description states the return shape ('the stored block and how each hold went') and covers the multi-system hold behavior, which is the main complexity risk. Remaining gaps - overwrite/conflict behavior, timezone handling of the date fields, permission requirements - keep it from a 5.

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 schema coverage at 60%, the description must compensate for the undocumented parameters, but it never mentions boat_id, start_at/end_at semantics, notes, or reason. Only 'dates' and 'boat' are implied, and the schema already carries the YYYY-MM-DD format and list_boats hint.

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?

Names a specific verb (block dates) and resource (one of the operator's boats) and states the effect ('so they cannot be booked'), which is enough to separate it from the counter-tool remove_block and from calendar/pricing tools in the sibling list.

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 only implied: an agent can infer you call this to make dates unbookable, and the partner/X-Lock sentences hint at when side effects occur, but there is no explicit when-to-use, no alternative named (e.g. remove_block for reversing), and no stated prerequisites such as required permissions.

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 declare the safety profile (not read-only, not destructive), and the description adds behavior they don't cover: the imported events actively block dates on charter.boats, the tool returns the stored source, and it does not itself fetch events immediately (sync_calendar does). That last nuance is genuinely useful, though nothing is said about duplicates, auth, or removal.

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?

Two short clauses with zero filler; the core effect is front-loaded and the sibling pointer is appended compactly. Every clause carries 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?

With no output schema, the description usefully states what is returned ('the stored source'), and it discloses the calendar's blocking side effect. Missing only edge-case guidance (duplicates, re-adding, error conditions) for a mutation tool whose sibling remove_calendar exists.

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% (boat_id, source_url, source_name, source_type all documented), so the baseline is 3. The description adds no syntax or format detail beyond the schema, such as iCal URL constraints or the meaning of source_type.

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?

Names a specific verb (connect) and resource (external calendar), states the concrete effect ('its events block those dates on charter.boats'), and implicitly distinguishes itself from sync_calendar. An agent can identify the operation 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?

Identifies the complementary sibling and its role ('sync_calendar pulls it at once'), which tells the agent this is the setup step and sync is the follow-up. It doesn't spell out when-not-to-use or prerequisites (e.g., must the boat exist, can duplicates be added), so it stops short of full routing guidance.

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 cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false), so the description's burden is lower. It adds the return contract — the stored row plus `warnings` listing overlapping rows — which is real behavioral information not derivable from the annotations, though permissions and side effects on existing pricing go unmentioned.

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?

Two tight sentences with no filler, and the purpose is front-loaded ahead of the return-value note. Slightly ambiguous phrasing ('the operator prices directly') costs it a point but nothing 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?

For a 12-parameter mutation with no output schema, the description usefully explains the return payload, but it omits how this differs from add_price, what happens to overlapping fees besides being warned about, and any prerequisite for the 4 required fields.

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 75% across 12 parameters, so the schema carries most of the load and a baseline of 3 applies. The description adds no parameter meaning beyond the schema and leaves `category`, `on_request`, and `amount_is_percentage` to the schema 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?

States a specific verb (add) and resource (extra/fee) scoped to boats the operator prices directly, which separates it from the more generic add_price. It does not explicitly name a sibling tool, but the scope qualifier makes the intent legible without opening a 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 phrase 'a boat the operator prices directly' implies a precondition for use, which is useful context, but there is no explicit when-to-use / when-not-to-use guidance and no named alternative (e.g. add_price vs add_fee). Usage must be largely inferred.

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 declare this is a non-destructive write (readOnlyHint=false, destructiveHint=false), and the description adds two things structured fields don't: the return behavior ('Returns the stored row') and the applicability constraint (direct pricing source). It stops short of documenting failure modes or auth requirements.

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?

Two tight sentences with the action front-loaded and zero filler. Every clause carries information (scope, applicability, return).

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 8-parameter mutation tool with 50% schema coverage and no output schema, the description covers purpose and return shape but leaves the date fields and priority semantics unexplained. Adequate but with clear 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 only 50%; the four date fields (start_month/day, end_month/day) have no description in either schema or description. The prose adds no syntax, format, or meaning beyond the word 'season', so it fails to compensate for the coverage 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?

States a specific verb (Add) and resource (season price to a boat), plus a scoping qualifier (pricing source direct). It's clearly distinct from get_pricing/delete_price, but it never explicitly contrasts with the sibling update_price, so an agent must infer the boundary.

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 parenthetical '(pricing source direct)' implies a precondition for use, which is better than nothing, but there is no explicit when-not and no named alternative such as update_price for adjusting an existing season row. Usage is only implied.

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 establish read-only/non-destructive, so the description's job is to add semantics and it does: only boats open at least one week are compared, prices are the max-guest all-in figure used by search, peer prices are shown as deltas against the anchor (absolute in `absolute_weeks`), null means not sellable that week, and `in` `id`-less mode peers carry their own specs. That is meaningfully more than the annotations provide.

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 correctly, but the body is a single ~180-word paragraph of stacked clauses ("a peer's `price` is its figure minus the boat's (its own in the weeks listed in `absolute_weeks`)") with no breaks, and it introduces output fields like `anchor` and `absolute_weeks` without definition. Information-dense but hard to parse on a single pass.

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 carries the full return-value burden: `similar_pct`, `overlap_pct`, `same`, signed spec deltas, price deltas vs absolute figures, and `weeks` check-in dates are all explained. An agent can call this and interpret the response without further documentation.

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 the schema already documents every parameter including the dual match-vs-minimum semantics of berths/cabins/guests. The description mostly restates this ("the specs take search_boats' names... with `id` they filter its peers as search_boats would") and never explains `lock`, `makemodel`, or the year/length range pairs. 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?

Opens with a precise statement of what is compared: one boat versus up to 10 closest published boats of the same type and country, across 52 weeks of specs and all-in weekly prices. It explicitly routes the 'is this boat good?' question to get_boat_standouts, so an agent can separate it from siblings without reading schemas.

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?

States directly when to use it ("how a boat compares with others nearby on price, size or age"), names the two invocation modes (by `id`, or by `boat_type`+`country`), and names the alternative for a different intent (get_boat_standouts). It even covers the operator-benchmarking-own-boat case.

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 carry the generic safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false). The description adds genuinely non-obvious behavioral context: the discount is charged against the operator's payout rather than the platform commission, and it discloses the return ("the stored discount"). It still omits auth/validation requirements, keeping it short of 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?

Two compact clauses with the action and the key financial constraint front-loaded, plus a brief return note. No filler; 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?

For a 15-parameter mutation tool with no output schema, the description covers the risky/ambiguous part an agent most needs (who bears the cost) and states the return shape. It lacks prerequisite/auth context and any reference to the update/delete counterparts, but the schema carries the field-level burden.

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 87%, so the schema already documents nearly all 15 parameters, including the code-vs-pay_in_full trigger rule and currency defaults. The description adds no parameter-level detail beyond an indirect hint about how discount_value financially lands, 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?

States a specific verb and resource ("Create a discount") and adds the crucial business framing that the discount is deducted from the operator's payout, not the platform commission. This is more informative than a bare CRUD restatement, though it never explicitly distinguishes itself from update_discount/delete_discount 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?

No guidance on when to create a discount versus updating one, no prerequisites (permissions, existing company), and no routing to list_discounts/update_discount. The schema hints at trigger semantics but the description offers no usage context.

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 supply destructiveHint=true, readOnlyHint=false and openWorldHint=false, so the safety profile is covered by structured data. The description nonetheless adds real value by emphasizing permanence ('for good') and by contrasting with the reversible path. It leaves unstated whether auth/ownership is required or what happens when the id does not resolve.

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?

Two tight sentences: the destructive action first, then the routing alternative. No filler, and the most important constraint is front-loaded.

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-param mutation with a destructive annotation and no output schema, the description covers the key agent question (delete vs. disable). The residual gap is the undocumented image_id, which the agent must infer from having listed the boat's images.

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 schema documents only 'id' (via list_boats) and leaves 'image_id' completely bare, and the description adds no parameter meaning at all — no format for image_id, no relation to the boat's cover image. At 50% schema coverage the description is expected to compensate, and it does not.

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 (delete) and narrowed resource (one photo of the boat), with an explicit scope of exactly one image. It also names the sibling tool it is not, so an agent can distinguish it from update_boat_images without opening either 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?

Gives an explicit when-to-use versus alternative: destroy the photo with this tool, or remove it from the listing non-destructively with update_boat_images + disable_id. The decision criterion is fully spelled out, including the exact parameter of the 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 destructiveHint=true and readOnlyHint=false, so safety is covered; the description adds the genuinely useful blast-radius detail that existing bookings retain the discount while new usage is blocked. It stops short of stating reversibility, idempotency, or behavior when the id is unknown.

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?

One sentence, front-loaded with the action and followed by the two facts that matter (new usage blocked, existing bookings unaffected). No 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?

For a single-parameter mutation with annotations covering safety and no output schema, the description supplies the key effect semantics. Missing only edge-case behavior (non-existent id, already-ended discount, permanence), which is minor at this complexity.

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 single 'id' parameter is documented in the schema ('Discount id, from list_discounts'). The description adds nothing about the parameter, 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?

States a specific verb+resource ('End a discount') and immediately defines what ending means, so the agent can distinguish it from update_discount, create_discount, and list_discounts without opening a schema. The scope statement ('guests can no longer use it') pins down the operation precisely.

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 only implied: the description makes clear this is the termination path rather than a modification, but it never says when to prefer it over update_discount or what preconditions (e.g. discount must exist / not already ended) apply. No alternatives are named.

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 destructiveHint=true and readOnlyHint=false, so the agent knows this is an irreversible write. The description adds only the scope qualifier 'direct fee row'; it says nothing about whether the delete cascades, whether confirmation is required, or what the caller sees on success or failure. With annotations carrying the safety profile, this is adequate but thin.

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 front-loaded sentence with no filler or repetition. It is efficient, though its brevity shades into under-specification rather than exemplary conciseness.

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-parameter destructive mutation the annotations and fully documented schema cover the essentials, but the description leaves open what 'direct fee' means and what happens to the parent fee after deletion. The minimum an agent needs to call it correctly is present; the behavior around the call is not.

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% – both id and fee_id are documented with their source tools (list_boats, list_boat_fees). The description adds nothing about parameter meaning or format, 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?

States a specific verb and resource (delete a fee row), which distinguishes it from the sibling add_fee and update_fee. The qualifier 'direct' hints at a scope distinction, though it never explains what a non-direct fee would be, so the differentiation from siblings is only partial.

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?

No guidance on when to use this versus update_fee (which could also clear a row) or the broader delete_* family. No prerequisites, no warnings, no mention that list_boat_fees is the source of the required row id beyond what the schema already says.

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 destructiveHint=true and readOnlyHint=false, so the safety profile is known. The description adds genuine context beyond that: it discloses the downstream effect that the covered dates lose their price until another row covers them. It doesn't cover idempotency or error behavior on a missing row id.

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?

One compact sentence that leads with the action and follows immediately with the consequence. Every clause earns its place with no 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?

For a two-parameter delete with fully documented params, destructive annotations, and no output schema, the description supplies the key missing piece – what happens to the underlying dates. Return/error behavior is the only notable gap, which is minor here.

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% – both id (boat id, from list_boats) and price_id (row id, from get_pricing) are documented in the schema with provenance. The description adds no parameter-level detail beyond what the schema already provides, 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?

States a specific verb+resource ('Delete a direct season price') and the scope of the operation, which distinguishes it from sibling deletion tools like delete_fee, delete_discount, and remove_block. It doesn't explicitly name an alternative, so it stops 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?

No when-to-use or when-not-to-use guidance is given, and no alternative is named (e.g., update_price to modify rather than remove coverage). Usage is only inferable from the stated consequence.

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 safety profile (readOnly, non-destructive, closed-world), and the description adds real value beyond that by enumerating the return scope: boats, partner links, and event types by source. It omits return format and pagination details, but for a read-only tool this is solid added context.

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 tool's identity, followed by a dense enumeration and a one-line usage hint. The em-dash list is a bit heavy but each clause carries information; 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 compensates by describing what the calendar contains and its event sources. Combined with the read-only annotations and 100% schema coverage for the single parameter, an agent has enough 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 description coverage is 100%, and the single company_id parameter is fully documented in the schema (including where to source it). The description adds no parameter-level meaning, 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 states a specific resource and scope: the company's fleet calendar listing every boat with partner links and every date-consuming event (bookings, options, blocks, synced partner/iCal events) with its source. This is far more concrete than a generic 'get', though it never names itself as distinct from near-siblings like list_bookings or list_calendars.

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 context: 'Read it before add_block to see what a range already holds,' tying usage to a concrete sibling and precondition. It does not state exclusions or when another listing tool is preferable, so it falls short of a full when/when-not breakdown.

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 a safe read (readOnlyHint, non-destructive, closed-world), so the bar is lower. The description adds genuine behavioral context: hidden equipment items are included, and locked_fields are the fields MMK or Nausys rewrite on every sync — information an agent cannot get from annotations or schema.

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 sentence that front-loads the core purpose ('one of the operator's boats in full') and then enumerates contents. No filler, though the trailing enumeration is packed.

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 what is returned (editable fields, photos with ids, videos, equipment including hidden, locked_fields). No permissions or sync-freshness caveats beyond locked_fields, but essentially complete for a single-resource 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?

Schema description coverage is 100% with a single id parameter documented as coming from list_boats, so the schema carries the parameter semantics. The description adds nothing further about the id, which is acceptable at this coverage level.

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 verb+resource (fetch one boat in full) and scopes it precisely: every editable field, photos with ids, videos, equipment with hidden items, and locked_fields. It implicitly separates itself from get_boat_standouts by emphasizing the full edit-page view, but never names the sibling tools it is distinguished 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?

Usage is implied by 'as its edit page shows it' and 'every editable field', suggesting this is the tool for full editable state rather than a summary. However, there is no explicit when-to-use/when-not guidance and no mention of alternatives like get_boat_details or get_boat_standouts.

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, openWorldHint=false and destructiveHint=false, so safety is covered. The description still adds genuine behavioral detail beyond the annotations: the free-date payload covers priced date ranges plus bookable slots for the year ahead, and stay_price orders its output as Due now, Paid at pickup, Total. Credit for that context, but no output schema exists and the shape of the detail payload is only sketched.

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?

Two dense but front-loaded sentences; the resource and its payload lead, then usage, then the date/price behavior. No filler, though the parenthetical and em-dash clauses make the second sentence heavy enough to be slightly harder to scan.

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, so the description carries the return-value burden and mostly does: it lists the detail categories, the availability coverage window, and the stay_price field ordering. What is missing is any hint of whether the detail payload is large or how it is structured, which matters for an agent deciding to call this over get_boat.

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 the baseline is 3. The description adds interaction semantics the schema only implies: passing date_from/date_to makes fees stay-specific, makes url open the boat on those dates, triggers stay_price pricing, and on boats without check-in periods anchors the stay to the changeover day.

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 and enumerates exactly what comes back — security deposit, cancellation policy, amenities, fees, seasonal prices, check-in/out times, location details, and free/bookable dates. Clear on its own, but it never contrasts with adjacent siblings like get_boat, get_pricing or get_availability, which an agent choosing between them would want.

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 a concrete trigger ('when the user asks about a specific boat') plus a routing rule from the search flow ('whenever a boat came back in named_matches and they want to know when it IS available'). No when-not-to-use or negative routing against overlapping get_* siblings, so it stops short of 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 carry the safety profile (read-only, closed-world, non-destructive); the description adds substantial behavior beyond that: which attributes are compared, that unlisted attributes are 'ordinary among the boats in `compared_with`', that other fees are not compared, and what `note` means when something is absent ('ordinary' vs. nothing comparable). It also discloses the shape of the output (ordered `rare_kit` with `useful_score` 1-5) and how `fallback` changes behavior when nothing clears the cut-off.

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 purpose and trigger conditions, and the dense parenthetical examples ('47.9 ft (better than 99%)', 'Rare kit: [0.8%] Cool Box') efficiently convey output format. It is a single long paragraph, but nearly every sentence carries distinct information; minor tightening is possible but nothing is clearly 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?

For a complex comparison tool with no output schema, the description covers the comparison basis, the excluded categories (other fees), the meaning of absence, the output fields (`rare_kit`, `useful_score`, `note`), and the fallback behavior. An agent has what it needs to call it correctly 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?

With 100% schema description coverage the baseline is 3, but the description adds meaning beyond the schema: it explains that `date_from` also drives check-in/check-out times, changeover day, and open-weeks judgments, and that 'any of those it does not list is ordinary' — a semantic consequence the schema does not state. Currency, fallback and cutoff_pct are largely left to their schema text, so it is not fully additive.

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 — it reports what stands out (pros and cons) about ONE boat for one week, measured against similar boats. It also distinguishes itself from the closest sibling by name: 'get_boat_details gives each item its [n%] across the whole fleet, this tool what is rare among boats like it.'

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 explicit trigger contexts: 'Use when the guest asks what is special about a boat, what the catch is, why it is cheap or dear, or how it compares with others,' plus a when-not-to-misuse rule (unlisted attributes are ordinary — do not sell them as an edge). It does not address the sibling 'compare_boat' or state when to prefer it over this tool, so it stops short of full when/when-not/alternatives coverage.

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, destructiveHint=false, openWorldHint=false, so the redundant 'Read-only' adds little. However, the description discloses a genuine behavioral nuance not in the annotations: payments are 'empty until the booking is paid,' a state-dependent return detail an agent should anticipate.

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 front-loaded sentence ('One booking in full:') followed by an efficient enumeration of return fields. It is dense but each listed element earns its place, especially since no output schema exists.

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, describing return contents is the description's job and it does so thoroughly. The safety profile is covered by annotations and the param is fully documented; only edge cases (missing id, error behavior) are absent.

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 single 'id' param is fully documented as 'Booking id, from list_bookings.' The description reinforces the list_bookings provenance but adds no format or constraint detail 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?

States a specific verb+resource (get one booking) and enumerates the exact contents returned: stage, dates, guest, price lines, payout, payout_schedule, and due-dated payments. It explicitly ties itself to list_bookings ('stage (as in list_bookings)'), letting an agent distinguish this single-record fetch from the list 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?

Usage is only implied: 'One booking in full' suggests fetching a single record versus list_bookings, and the id source is named. There is no explicit when-to-use/when-not statement or named alternative for adjacent lookups.

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 safety profile (readOnly, non-destructive, closed-world), so the bar is lower. The description adds genuine behavioral context beyond that: it defines what the returned aggregates mean and what a false policy_applies implies ('governs nothing and cannot be changed'). It stops short of coverage like rate limits or a true return contract.

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 return content is front-loaded in the first sentence, followed by the cross-reference and the edge-case note. It is dense but every clause carries information; slightly long for a one-parameter read tool but no 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 carries the burden of explaining return values, and it does so by naming the key output concepts and the policy_applies flag semantics. An agent knows what it will get and how to interpret it, though the exact field shapes remain 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?

There is a single 'id' parameter with 100% schema description coverage ('Company id.'), so the schema already carries the semantics. The description's reference to 'per boat source' and 'the company' reinforces that id identifies a company, but adds no new syntax or constraint beyond the schema. 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 states exactly what the tool returns: per boat source the share paid in advance, days before the charter the balance is due, and the largest refund each notice period covers. That is more informative than a bare verb+resource. It does not explicitly name the sibling it complements (set_cancellation_policy), so it falls short of 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 gives clear context for use ('read beside get_company's cancel_refund_percent and cancel_refund_days') and explains the meaning of a policy_applies=false result. However, it never states when to prefer this over the adjacent set_cancellation_policy or any other tool, so no explicit alternative routing is offered.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuine value by disclosing the return payload contents (bank, tax, invoicing, X-Lock switch, cancellation policy, member/boat counts), which is context not present in annotations or schema.

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 lead phrase front-loads the resource, and the rest is a dense but purposeful enumeration of return fields. It is a single run-on sentence, which slightly hurts readability, 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 burden of explaining what is returned, and it does so comprehensively (profile, contact, bank, tax, invoicing, cancellation policy, X-Lock switch, counts). An agent can anticipate the payload shape without guessing.

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 there is a single parameter whose schema text already explains where company_id comes from, so the description need not compensate. The named fields (cancel_refund_percent, cancel_refund_days) describe return values, not the parameter, so the description adds nothing to parameter meaning beyond 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?

The description clearly identifies this as the company profile retrieval (a specific resource) and enumerates its contents, making it distinguishable from boat-related siblings like get_boat and get_boat_details. It frames the tool as a noun phrase ('the company profile') rather than stating the verb, but the retrieval action is unambiguous.

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 explicit guidance on when to call this versus alternatives such as get_boat_details or update_company, nor any stated prerequisites. Usage is only implied by the read-oriented framing.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds the useful detail that figures are reported in the operator's payout currency and that pending payouts are tied to accepted bookings, but says nothing about permissions, calculation windows, or freshness of the data.

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 sentence that front-loads the resource and then enumerates the contents; nothing is wasted. It is slightly list-heavy but appropriately sized.

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 return contents, and it does so reasonably well: total and monthly payouts, pending payouts, latest bookings, and currency. It stops short of explaining ordering, limits on the 'latest bookings' list, or time ranges.

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 there is only one parameter (company_id), whose schema description even tells the agent where to source it (list_boats or get_company). The description adds no parameter semantics beyond the currency note, 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 specific resource and enumerates its payload (total/monthly payouts, pending payouts, latest bookings), so an agent knows this is a read-only earnings/finance retrieval tool. It lacks any explicit differentiation from siblings like get_pricing or list_bookings, which would have pushed it to 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?

There is no when-to-use statement, no prerequisites, and no mention of alternatives such as get_pricing or list_bookings for related financial data. Usage is only inferable from the payload listing.

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, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuine behavioral context beyond that: the data mixes public marina facts with proprietary AIS-derived traffic signals, and it warns that 'busyness compares a place to its own peak month, never to another place,' which prevents a real misuse (cross-location comparison). No mention of auth or rate limits.

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 in the opening clause, but the return-value enumeration sprawls across a very long compound sentence before the usage guidance arrives. Dense but mostly earned; it could be trimmed without losing 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?

With no output schema, the description carries the full burden of describing returns, and it does: core fields (description, amenities, contact, boat count, cheapest day rate), the AIS signals (monthly busyness, overnight share, day-stop length, fill-up time, hidden-gem flag), outbound destinations ranked by trip share with passage times, and the nearest bookable base. The peak-month normalization note closes the remaining interpretive 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 description coverage is 100%, so the schema already documents both id (verbatim copy from search_locations) and currency (default EUR). The description adds nothing about either parameter, 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?

States a specific verb (get) and resource (full details of a marina, anchorage or bay) keyed by ID, and enumerates the distinct content classes returned: descriptive data, AIS-derived busyness, destination routes and nearest bookable base. An agent can separate this from search_locations or get_poi_details without opening a 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?

Gives explicit triggers: 'when the user is viewing or asks about a specific place, asks when it is quiet, or asks where to go next from one.' Clear context, though it never names an alternative tool (search_locations is only implied via the id parameter's origin).

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?

Although annotations already establish readOnly/non-destructive, the description adds substantial behavioral detail beyond them: the ordering of boats (charted first, then by open weeks), the exact meaning of vs_similar_pct (median over sellable weeks, compared against up to 10 similar boats, null when no week to compare), the 15% thresholds, the 'up to five' caps, and the unit conventions (weekly EUR totals at max guests).

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 in the opening clause, followed by return-structure detail that earns its place because there is no output schema. The downside is that most of it is one dense run-on sentence that is hard to parse, though little is actually 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 one fully documented parameter, read-only annotations, and no output schema, the description carries the return-shape burden well – covering the three sections, thresholds, caps, null semantics, and units. The only meaningful gap is guidance on when to reach for this over the pricing/earnings tools.

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?

There is a single parameter and the schema already describes company_id at 100% coverage, including its provenance (list_boats or get_company). The description adds nothing about the parameter, so baseline 3 applies – the schema does the work.

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 precisely (the company's Opportunities as the dashboard's Analysis page renders them) and enumerates the three sections returned: boats, price_suggestions, source_checks. It is a clear read-only retrieval of a specific dashboard view, though it never explicitly contrasts itself with siblings like get_pricing, get_earnings, or compare_boat.

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 only implied by the phrase 'as the dashboard's Analysis page shows them' – an agent can infer this reproduces the Analysis view, but there is no explicit 'use this when' or 'prefer X instead' guidance against the many pricing/earnings siblings. The 'Empty lists mean nothing to suggest' line clarifies interpretation but is not routing guidance.

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, openWorldHint=false and destructiveHint=false, so safety is covered. The description still adds genuinely useful behavioral context beyond them: the exact data payload and the operational constraint that POIs carry no rating or review count and the agent must not claim one.

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 short sentences, front-loaded with the core action and payload, then usage trigger, then the negative constraint. Every sentence carries distinct information with no 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?

For a read-only, single-parameter lookup with full schema coverage and no output schema, the description covers purpose, trigger, payload, and the main agent-facing pitfall (hallucinating ratings). Nothing critical is missing, though error behavior for an unknown id is 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?

Only one parameter, and schema description coverage is 100% — the schema already says the id comes from search_pois results and must be copied verbatim. The description adds no format, length, or validation detail beyond that, 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?

States a specific verb and resource ('Get full details of a point of interest by ID') and even enumerates the returned fields (hours, address, contact, nearby marinas, offers). It is clearly an ID-based detail fetch distinct from the sibling search_pois, though it never names that sibling 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?

Gives an explicit trigger: 'Use when user is viewing or asks about a specific POI.' That is clear context for invocation, but there is no stated exclusion (e.g., do not use to discover POIs — call search_pois first), which the schema's id description only implies.

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 read-only, non-destructive profile. The description adds genuinely useful behavioral context beyond them: rows with source mmk/nausys are partner-managed and change there, while source=direct rows are the operator's to edit — telling the agent what is and isn't actionable.

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 sentence that front-loads the returned entity and then enumerates fields and source semantics. Minimal waste, though the source-syntax details make it 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?

With no output schema, the description usefully specifies the returned fields (id, date span, price_per_day, source) and their semantics, which is the key missing structured info. It does not address grouping/pagination, but is otherwise sufficient for a single-param 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% for the single company_id parameter, so the schema carries parameter documentation. The description does not mention the company filter, so it adds nothing here; 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?

States a specific verb+resource: retrieves the fleet's season prices as per-boat week-price rows. It also names the sibling edit tools (add_price, update_price, delete_price), helping differentiate this read from the mutations, though differentiation is somewhat indirect.

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: it tells you which rows are editable via add_price/update_price/delete_price, which guides the follow-on action, but never explicitly says when to call get_pricing itself or what alternatives exist.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds the notion of a 'full details' payload, but says nothing about behavior when the ID is unknown or how large the response may be. With annotations carrying the load, this is adequate but not rich.

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?

Two sentences, front-loaded with the action and payload, followed by the usage cue. The field enumeration is informative rather than padding, and nothing 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?

For a single-parameter read tool with annotations covering safety, the description gives the agent enough to call it correctly, and the field list partially compensates for the absent output schema. It omits error/not-found behavior, which keeps it from a 5.

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 tells the agent to copy the ID verbatim from search_trips results. The description adds no syntax or sourcing detail beyond what the schema already provides, 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?

States a specific verb+resource ('Get full details of a sailing itinerary/trip by ID') and enumerates the returned content (day-by-day stops, distances, activities, highlights, notes). This is clearly distinguishable from search_trips (discovery) and get_boat_details (a different resource).

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?

'Use when user is viewing or asks about a specific trip' gives a clear triggering context, and the by-ID framing implicitly contrasts with search_trips. It stops short of naming the alternative tool or stating exclusions explicitly.

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 and destructiveHint=false, so the safety profile is covered. Beyond that, the description adds genuine domain behavior: it discloses the fields returned and the semantic that rows with `source` = direct belong to the operator and are editable. It stops short of explaining other `source` values or ordering.

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?

Two compact sentences, front-loaded with the resource and backed by a concrete field list plus one clarifying note. No filler, though the sentence is dense and could be slightly more scannable.

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 usefully compensates by naming the returned columns and the meaning of `source`. For a simple single-parameter read tool this is nearly sufficient; only ordering/pagination behavior is unaddressed.

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 `id` parameter, and its description even points to list_boats for provenance. The tool description adds no further parameter detail, so the baseline 3 is appropriate when the schema does all the work.

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 (a boat's extra and fee rows) and enumerates the returned attributes (amount, period, required, collection method, source). It is clear what the tool returns, but it never explicitly names a sibling like list_fees/update_fee to disambiguate, so it falls 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?

There is no explicit guidance on when to call this versus add_fee, update_fee, delete_fee, or get_pricing. The phrase 'as its edit page lists them' faintly implies a read-for-editing context but names no conditions, prerequisites, or alternatives.

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 a safe read (readOnlyHint=true, destructiveHint=false, closed world), so the bar is lower. The description adds genuinely useful behavior: unpublished boats are included, the payload carries company name, specs, pricing source, changeover settings and photos, and an empty result has a specific meaning (account belongs to no company).

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 sentences, front-loaded with the resource and scope, then the usage cue, then the empty-state semantics. Every sentence carries information and none is redundant.

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 the returned fields and explaining the empty-list case. Combined with annotations covering the safety profile and a fully documented parameter, 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% and the single company_id parameter is fully documented in the schema, including its optionality and default behavior. The description repeats the same multi-company scoping idea without adding syntax or edge-case detail, 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 gives a specific verb+resource ('every boat of each company the key holder belongs to') and a precise scope ('published or not') that separates it from a generic boat search. It does not name a sibling such as search_boats or get_boat explicitly, but the 'own fleet' framing makes the boundary inferable.

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?

'Start here: it gives the boat ids and company ids every other operator tool takes' tells the agent when to reach for this tool and why it precedes the rest. There are no explicit exclusions or named alternatives, so it stops 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 already cover the safety profile (readOnlyHint, destructiveHint=false, openWorldHint=false), so the description earns credit for going beyond them: it discloses ordering (newest charter first), the meaning of the empty result set, and the lifecycle semantics of status values including the hold_expires_at lapse rule. It does not mention pagination or result-size limits, which is the remaining gap.

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?

Four sentences, front-loaded with scope and ordering before the status vocabulary and the read-only caveat. The status-definition sentence is dense but each clause carries distinct domain meaning; nothing reads as 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 compensates well by describing what each row contains (guest price, discounts, operator payout, payout currency) plus ordering and the empty case. Pagination and total-count behavior are the only meaningful omissions.

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 single boat_id parameter is documented there as 'Optional: one boat only.' The description adds nothing about that filter, so the schema carries the full burden — 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 states the resource and scope precisely: 'Every booking on the operator's boats, newest charter first.' That is far more specific than a bare list tool, but it never distinguishes itself from the sibling get_booking, which retrieves a single booking — an agent must infer the split from the tool names alone.

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?

'Read-only: bookings are handled on the dashboard' signals when this tool is appropriate (inspection) and when it is not (booking management), and the empty-list note tells the agent what an empty result means. It stops short of naming get_booking as the alternative for a single booking, so routing 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 already establish readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds useful behavioral context beyond that: it explains that the list includes sync state, excludes automatically linked MMK/Nausys calendars, and that an empty list means no external calendar is connected.

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 sentences with zero waste. The core purpose is front-loaded, followed by the two most important interpretation details: excluded automatic calendars and the meaning of an empty 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?

For a simple, read-only list tool with a fully documented single parameter and annotations covering safety, the description is nearly complete: it says what is returned, what is excluded, and what an empty result means. The only minor gap is that it does not detail the exact return fields (e.g., calendar id, type, sync state values) in the absence of an output schema.

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%: the single boat_id parameter is fully documented as 'Boat id, from list_boats.' The description reinforces the one-boat scope but adds no syntax, format, or sourcing detail beyond the schema, so the baseline of 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 specific verb (lists), resource (external calendars), and scope (connected to one boat), and explicitly distinguishes the content by excluding MMK/Nausys auto-linked calendars. An agent can tell this apart from add_calendar, remove_calendar, and sync_calendar 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?

Usage is implied: use this to see which external calendars are connected to a boat, with the caveat that MMK/Nausys are not included. However, no explicit when-to-use guidance is given relative to sibling tools like add_calendar or sync_calendar, and no prerequisites or alternatives are named.

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/non-destructive/closed-world, but the description adds real behavior: it returns ONLY active discounts (a filter), documents the empty-list meaning, and describes the return shape (value, booking/stay windows, covered boats). It stops short of noting anything about volume, pagination, or permissions, but it meaningfully exceeds what the annotations 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?

Two sentences, densely front-loaded: the resource and its contents come first, the empty-list edge case last. The parenthetical field notation (start_date..end_date, all_boats/boat_ids) is compact and every clause carries 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?

With no output schema, the description carries the burden of describing return values and does so thoroughly, including the two date windows and the boat-coverage fields. Only minor gaps remain — no mention of pagination or ordering of the returned list.

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 single company_id parameter already documents its source (list_boats or get_company). The description references 'the company's' discounts but adds no extra semantics about the identifier, 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 specific resource (the company's active discounts) and enumerates exactly what the result contains — promo codes, automatic discounts, pay-in-full discount — so an agent knows precisely what it will get back. It does not explicitly contrast itself with siblings like get_pricing or create_discount, but the read-only listing intent is unambiguous.

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 word 'active' signals that expired/inactive discounts are excluded, and 'An empty list means the company runs no discount' tells the agent how to interpret a null result. There is no explicit when-to-use-vs-alternative guidance and no stated prerequisite beyond supplying a company_id.

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 destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds genuinely useful consequence detail beyond that: the block's dates are freed and partner holds are released, which tells the agent what side effects to expect. It stops short of 5 by not addressing reversibility or required permissions.

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 front-loaded sentence: verb+resource first, then the side effects. No filler, no repetition of the schema, and every clause carries 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?

For a one-parameter destructive mutation with full schema coverage and annotations covering the safety profile, the description supplies the key missing piece — what gets destroyed/released. No output schema exists, so return values need not be explained. Minor gap: no error or failure behavior.

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?

There is only one parameter and schema coverage is 100% — the schema itself explains that `id` comes from `block_id` in get_availability or `id` from add_block. The description adds nothing about the identifier, so the 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?

States a specific verb and resource ("Remove a block") and narrows scope with "the operator placed," which separates it from blocks/calendar entries created by others. It does not explicitly name the sibling counterpart (add_block) or distinguish itself from remove_calendar, so it stops 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?

Usage is only implied: the phrase "a block the operator placed" suggests when this applies, and "freeing its dates" hints at the intent (undoing an availability block). There is no explicit when-to-use/when-not, no mention of alternatives like remove_calendar or add_block, and no preconditions.

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 destructiveHint=true and openWorldHint=false, so the safety profile is covered; the description adds genuinely new behavioral detail by enumerating what destruction means here — blocked dates are freed and X-Lock holds are released on partner calendars. It stops short of stating irreversibility or permission requirements.

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 sentence that front-loads the action and then explains its effects, with no filler. Every clause carries 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?

For a one-parameter, destructive tool with no output schema, the description supplies the critical missing piece — the downstream side effects on blocked dates and partner holds. Only irreversibility/auth expectations are left unstated, a minor gap given the destructiveHint annotation.

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 single 'id' parameter already documents itself as the source id from list_calendars. The description adds no additional meaning about the parameter, so the baseline 3 applies where the schema does the work.

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 precise verb+resource, 'Disconnect an external calendar,' which is clearly distinct from the sibling add_calendar, sync_calendar, and list_calendars. It also sketches the effect of disconnecting, but never names a sibling to contrast against, so differentiation is inferred 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?

The description explains the consequences of the operation but gives no when-to-use guidance, no prerequisites (e.g., permissions or ownership), and no explicit routing between this and remove_block or sync_calendar. Usage is only inferable from the verb.

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 declare the read-only safety profile, and the description goes far beyond that: it explains that `total_matching` is the full count while `boats` is only the top `limit`, that `alternatives` are loosened matches that must not be mixed into the match list, that `unpriced_start_index` entries are matches but unbookable, that `named_matches` never contradicts a boat's existence while `name_not_found` is certain, and that absent `alert_query`/`alert_horizon` means no link may be given. This is unusually rich disclosure of what the results do and do not mean.

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 a single monolithic wall of prose with sentences running past 100 words and no headings, lists or paragraph breaks to help an agent parse it. Much of the content is necessary given there is no output schema, yet the density and run-on construction impose a real readability cost. It is under-structured rather than tight.

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 17 parameters, the description carries the full burden of explaining returns, and it does: price_summary/list_price composition, discount and deposit treatment, alternatives, named_matches, unpriced tails, and alert fields are all covered. An agent has what it needs to both call the tool and interpret its answer 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 description coverage is 88%, so the schema already documents nearly every parameter, including the exhaustive feature-slug mapping and the price_max/total_max split. The description adds some value — "Pass the guest's dates as they gave them" and the note that each boat's changeover/min-stay may not match the asked week — but most of its length addresses output semantics rather than parameter meaning. 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 opening sentence states a specific verb and resource plus the searchable dimensions: "Search charter boats by location, name, type, dates, capacity, budget." It also repeatedly routes to get_boat_details, making the search-vs-detail split clear. It does not, however, distinguish itself from the sibling list_boats, which an agent could plausibly confuse with it.

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?

Offers concrete when-to-act guidance: re-call with a higher `limit` when the guest wants more, call get_boat_details with the dates for Due now/Paid at pickup/deposits or when an optional skipper/hostess/cook must be priced in, and use get_boat_details for a named match's actually-free dates. These are genuine routing rules rather than vague context. It gives no guidance on when to prefer search_boats over list_boats, so it stops 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 already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds meaningful scope context by revealing there are two backing sources (site KB vs. docs.charter.boats), but says nothing about result format, ranking, or failure behavior.

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?

Two sentences, both front-loaded: the core action first, then usage and the routing exception. No filler, and the example list is genuinely useful rather than decorative.

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 should sketch what comes back, but it never mentions return shape or result limits, and limit is undocumented. The usage coverage is good, but a search tool with a defaulted result cap leaves the agent guessing about output.

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 only 33%: q is described in the schema and limit is undocumented everywhere. The description partially compensates by explaining one enum value (type=api) and clarifying when to pick it, but 'article', 'question', 'both', and limit's semantics remain unexplained.

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 ('Search articles and Q&A on charter.boats'), which clearly separates it from the boat/booking/location tools in the sibling list. It does not name a sibling tool explicitly, so it stops short of the 5 bar, but the knowledge-base vs. transactional-data distinction is unmistakable.

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 explicit use conditions ('questions about booking process, costs, licenses, cancellation, deposits, check-in, packing') and an internal routing rule ('For developer questions about our API ... use type=api'). It lacks any when-not guidance against sibling tools such as search_boats, so it is clear context but not full alternative routing.

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 a safe read (readOnlyHint=true, destructiveHint=false), so the bar is lower; the description still adds real semantic context by explaining that popularity is ranked on observed AIS vessel traffic over a month rather than an opaque score. It does not describe result volume, pagination, or what an empty result means.

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 three modes in a single dense sentence, then closes with the disjunction rule ('Provide q, or an area, or from'). The parentheticals and uppercase mode labels are functional, though the opening sentence is heavily loaded and takes a second read.

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 11 parameters, zero required, and no output schema, the description covers the selector logic, the from-based workflow and the popularity basis, which is what an agent needs to route a call. Gaps are modest: no statement of what a result set contains or what happens when no selector is supplied beyond the closing 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 82%, so most parameters are self-documented, but the description meaningfully enriches `within_nm` (ring-selection reasoning derived from ~6kt plus 30 minutes) and `from` (origin id sourced from a previous call, results are tracked destinations). It adds less for sort, month, limit and currency beyond what the schema already states.

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 the specific resource (marinas, harbours, anchorages) and enumerates three distinct retrieval modes keyed to parameter names (q, region/country/city, from + within_nm). An agent can distinguish this from search_pois or search_boats 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?

Gives explicit when-to-use triggers with quoted user phrasings ('where can I sail from X', 'a day sail from X') and ties the `from` parameter to a prior search_locations or get_location_details result. It does not contrast itself with the neighbouring search_pois tool, which is the one plausible overlap, so it stops 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 already declare readOnlyHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds one genuinely non-obvious trait — that POIs carry no ratings and should be ranked/described by type and distance — but says nothing about result ordering, pagination, or how limit interacts with the result set.

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?

Two sentences, both front-loaded with the search capability first and the ranking caveat second. Tight and waste-free, though the second sentence's phrasing ('by what they are and how close they are') is a slightly indirect way to state the ordering rule.

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 5-parameter, 40%-covered tool with no output schema, the description omits how location_id relates to location, what limit does, and what a result entry contains. It is adequate for the core purpose but incomplete on the details an agent needs 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 description coverage is 40%, so the description must carry weight, and it does map its phrasing to the q, location and category parameters. It still leaves location_id (and its precedence over location) and the limit default/behavior unexplained, so it only partially compensates for the coverage 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?

States a concrete verb (Find) plus the resource and its categories (restaurants, fuel, groceries, attractions), and covers two distinct modes: proximity search and name lookup. It distinguishes itself from detail-oriented siblings like get_poi_details implicitly, but never names an alternative sibling (search_locations, get_poi_details) to confirm the boundary.

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 implies two usage modes ('near a location' vs 'search by POI name') and mentions the category axis, which is useful implied guidance. However, it gives no explicit when-to-use versus search_locations or get_poi_details, and no prerequisites or 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 already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description only adds that results carry distance and difficulty; it does not disclose the notable resolution behavior (unresolved place names yield no passages) that the schema hints at, nor any result limits.

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 tight sentence with no filler, and the core purpose is front-loaded. It is efficient, though arguably under-sized for a 5-parameter 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?

With no output schema, 5 parameters at 40% coverage, and zero required parameters, a one-line description leaves the agent without enough to invoke this tool confidently or distinguish it from the other search tools.

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 only 40% across 5 parameters. The description touches 'destinations' (from) and 'difficulty' but says nothing about q, limit, or location_id, so it does not compensate for the undocumented parameters.

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 ('find sailing passages between destinations') and hints at returned content (distance, difficulty). It is distinguishable from search_boats/search_locations/search_trips by being about passages rather than boats or points, though it never names a sibling to sharpen the boundary.

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, no prerequisites, and no mention of the many adjacent search_* tools. An agent must infer from the name alone whether to call this or search_trips.

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, destructiveHint=false and a closed-world scope, so safety behavior needs no restating. The description adds one useful trait — results are limited to 'existing curated' itineraries — but says nothing about result volume, the limit default, or what an empty result means.

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 front-loaded sentence with zero filler — verb, resource and filter list in one pass. Nothing to trim.

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 8-parameter search tool with no required params and no output schema, the description is too thin: it omits limit/pagination behavior, boat_type, and how place names resolve. The rich location-resolution note exists only in the schema, so the description does not carry the load the schema coverage gap requires.

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 low (38%): limit, max_days, min_days, boat_type and location_id are undocumented in the schema. The description only echoes concepts already documented for q, location and activities ('location, name, duration, activities') and never clarifies the location vs location_id relationship or the days/limit syntax.

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: finding curated sailing itineraries, and enumerates the filter axes (location, name, duration, activities). It does not differentiate from the closest siblings, search_routes and search_boats, leaving 'itinerary vs route' ambiguous.

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 explicit when-to-use guidance and no naming of alternatives among the many search_* siblings. Usage is only implied by 'Find', so an agent must infer when this beats search_routes or get_trip_details.

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 declare it is a non-read-only, non-destructive, closed-world mutation. The description goes well beyond that: it discloses the owner-only permission requirement, the scope limitation (MMK and Nausys bookings only, direct boats follow charter.boats terms), the refusal case, and the response shape ('Returns the company as it now stands').

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 verb and resource, then the policy formula, then constraints and the prerequisite. Dense but every sentence carries operational information; slightly long, though nothing is clearly expendable.

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, yet the description states what is returned. Combined with the stated scope limits, refusal case, and prerequisite call, an agent has everything needed to invoke this mutation correctly without further inference.

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 schema already documents all three parameters with ranges, making 3 the baseline. The description adds value by framing the two policy parameters as a combined rule (cancel at least N days before → M% refunded), which clarifies their interaction rather than just 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?

States a specific verb+resource ('Set the company's cancellation policy') and immediately defines the policy semantics via the two parameter names, so the agent knows exactly what outcome is produced. It is clearly distinguishable from the read-only sibling get_cancellation_limits and from the other set_* 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?

Gives an explicit prerequisite ('Read get_cancellation_limits first'), an authorization constraint ('company owners only'), and a when-not condition ('a company whose boats are all direct is refused'). The agent is routed to the right sibling and knows before calling whether the call can succeed.

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 annotations: it discloses the authorization requirement (admins/owners), the cross-calendar hold side effect on the partner calendar, and that sync_existing retroactively places or releases holds on existing bookings and blocks — a write touching historical data. Annotations only say readOnly=false, destructive=false, so this adds genuine behavioral context.

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 action and its effect, but the return behavior is stated twice — 'Returns the company as it now stands' and then 'this call returns the value as it now stands' — which is redundant filler in an otherwise tight paragraph.

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?

Covers what the tool mutates, who may call it, the read-before-write workflow, and the return value (the company as it now stands) despite no output schema. Only minor gaps remain, such as whether disabling with sync_existing also releases existing holds.

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 only 33% (just company_id), but the description compensates well: it explains sync_existing's retroactive effect on existing bookings and blocks, and 'enabled' is clearly the on/off switch described in the opening sentence. It adds meaning beyond the bare boolean types.

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 ('Switch X-Lock for a company') and explains the mechanic precisely: enabling it makes every block, option or booking on one partner calendar (MMK or Nausys) also place a hold on the other. That distinguishes it from sync_calendar and update_company, though it never names which sibling is the read counterpart it refers to.

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 a real precondition ('company admins and owners only') and an explicit ordering rule: read the current value with its read tool first. It also explains when sync_existing applies (only for existing bookings and blocks). It stops short of saying when not to enable X-Lock or what the read tool is called.

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 this is a non-read-only, non-destructive write, and the description adds real context beyond them: the effect surface (public listing and search), that the change is reversible ('or show it again'), and that the item is matched even under alternate wording. It does not cover permissions or side effects on other listings, which keeps it at 4 rather than 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?

Three short clauses front-load the action and effect, then the name-sourcing hint, then the return value. Slightly compressed phrasing ('the same item under another wording follows it') costs a little clarity 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?

For a 3-parameter mutation with no output schema, the description covers the action, the effect surface, the return ('the new state'), and the prerequisite read (get_boat). Only permission/eligibility requirements are unaddressed.

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 documents id (from list_boats) and name, leaving the `hidden` boolean undescribed at 67% coverage. The description compensates by framing the two directions (hide vs show again), which makes the boolean's polarity inferable, and reinforces that `name` must match get_boat's listing wording.

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 gives a concrete verb pair plus resource and effect scope: hide or re-show an equipment item from the boat's public listing and search. It clearly is not a generic update/delete tool, so it is distinguishable from siblings like update_boat, though no sibling is named to anchor the contrast 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 supplies a usable workflow ('Use the item's name as get_boat lists it in `equipment_items`'), telling the agent to read get_boat first and how to format the name. It stops short of stating when-not-to-use or naming an alternative toggle path, so it is strong context rather than full routing guidance.

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 declare readOnlyHint=false, so the agent knows this is a mutation (importing events) rather than a safe read, and the description supports that by describing an actual pull. It usefully discloses the return shape ('how many events it brought in, or the error the feed gave'), which annotations do not cover. It does not say how conflicts or duplicates are handled during sync.

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?

Two short sentences, action first, return behavior second. Every clause carries information with no 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 compensates by explaining the return value (event count or feed error). Combined with the mutation hint from annotations and the fully documented parameter, it is nearly complete; only sync-conflict behavior is left unaddressed.

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 single 'id' parameter is documented in the schema as 'Source id, from list_calendars.' The description adds no format or lookup detail beyond what the schema already provides, 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?

States a specific verb (pull/sync) and resource (one external calendar) with scope ('one', 'now'). It is distinguishable from list_calendars by implying a single-source import action, though it does not name 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?

'Pull one external calendar now' implies an on-demand trigger for a feed sync, which gives some usage context. But it never states when to use this versus list_calendars, add_calendar, or remove_calendar, nor any prerequisites or 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 declare it is a non-destructive write; the description goes well beyond by disclosing patch semantics, that fields in `locked_fields` are silently ignored because partner sync owns them, and that the response carries `is_published` and `missing`. That is exactly the kind of side-effect and return behavior an agent needs before calling a 25-param 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?

Three dense sentences, front-loaded with the core mutation behavior and ending with the read-first guidance. The closing clause 'this call returns the value as it now stands' is mildly redundant with the earlier `is_published`/`missing` statement but not wasteful.

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 25-parameter mutation with no output schema and only partial schema documentation, the description covers the essentials: partial-update semantics, sync-owned locked fields, and the key return signals. It stops short of documenting the full parameter surface or other response fields, but nothing critical 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 only 52% across 25 parameters, so the description must compensate. It adds the crucial patch-semantics rule (unsent fields are unchanged) that governs how every parameter is interpreted, but it does not clarify the undocumented params such as `length_unpin`, `check_in_periods`, or `min_charter_days` beyond what the schema already says.

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 ('Change details of one of the operator's boats') and immediately scopes it as a partial update ('only the fields sent change'). It also distinguishes itself from the read path by telling the agent to 'read the current value with its read tool first', routing it away from get_boat.

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 operational context: use it to mutate existing boats, only sent fields change, and read first to see the current value. It does not spell out explicit when-not conditions or name a competing update alternative, but for a straightforward update tool the usage 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 declare readOnlyHint=false, destructiveHint=false, openWorldHint=false, so the mutation/reversibility profile is already structured; the description is consistent with that. It adds value beyond the annotations by stating the return payload ("the boat with its photos as they now stand") and by clarifying that new photos are not created here.

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 short sentences, operations front-loaded, no filler. Each clause carries distinct information: the available actions, the parameter contract, the id source, and the exclusion case.

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 4-parameter mutation tool with no output schema, the description covers the actions, the parameter contract, id provenance (get_boat vs list_boats), and the return shape. Nothing needed to invoke 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 the baseline is 3. The description earns an extra point by supplying semantics the schema omits: the ordering rule ("the first is the cover") and the mutual-exclusivity constraint that only one of enable_id/disable_id/image_ids should be sent per call.

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?

Names three concrete operations on the boat's photos (hide, re-show, reorder with the first as cover) and states the source of photo ids (get_boat) and where uploads happen instead. It differentiates its own modes clearly, but never contrasts with the sibling delete_boat_image, so the hide-vs-delete distinction is left for the agent to infer from the verb choice.

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?

"send one of the three" and "New photos are uploaded on the boat's edit page" give an explicit usage constraint and an out-of-scope case. No prerequisites or error conditions are stated, but the when-to-use boundary is 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?

Beyond the annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=false), it discloses non-obvious behavior: partial-update semantics, field-level authorization tiers, atomic all-or-nothing refusal on unauthorized fields, and that the response returns the updated value. None of this is derivable from 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?

Three tight sentences, front-loaded with the patch-scope rule, followed by the permission rule and the read-first/return-value note. Dense but every clause carries load; minor density cost given how much it compresses.

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 28-parameter mutation with no output schema, the description covers the essentials: partial update, authorization, atomic refusal, and the returned value. It stops short of detailing per-field constraints, relying on the schema for those, which is a reasonable division given 54% schema coverage.

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 only 54%, but the schema already marks each sensitive field 'Owner only' and the description adds the crucial cross-cutting rule that unsent fields are left unchanged and that a mixed request is refused as a whole. It groups sensitive fields (contact email, bank, tax, invoicing) rather than re-documenting each of the 28, which is appropriate but leaves some gap on the unlabeled 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?

States a specific verb and resource ('Change company details') and immediately adds scope in the form of PATCH semantics ('only the fields sent change'). It also names its read counterpart ('its read tool') so an agent can tell update_company apart from get_company without opening either 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?

Explicitly routes usage: read the current value first, then call this. It also states a concrete permission model -- any member may edit the public profile while contact email, bank, tax and invoicing are owner-only -- and that an unauthorized request is refused whole. When-to-use, prerequisites, and the failure condition are all given.

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 declare it is a non-destructive mutation, and the description adds two useful traits: patch semantics (only sent fields change) and that the call echoes the updated value. It does not mention permissions, side effects on bookings, or validation failures.

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?

Two tight clauses, front-loaded with the action, then the patch rule and the workflow hint. Minimal waste.

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?

A 15-parameter mutation tool with no output schema and no annotations coverage of field-specific behavior. The description covers patch semantics and return of current value but omits the shape of that returned value and any validation rules.

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 73%, so most parameters are self-documented. The description adds nothing about individual field semantics; the patch note applies to all fields but the schema already implies optionality via non-required 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?

Clear verb+resource (Change a discount) and describes the partial-update semantics ('only the fields sent change'), which distinguishes it from create_discount/delete_discount. No explicit naming of siblings, but the CRUD role is unambiguous.

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 a concrete workflow instruction: 'Read the current value with its read tool first' (list_discounts/get). Does not state when not to use it, e.g. vs create_discount for new discounts, but the guidance is actionable.

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 establish this is a non-destructive write (readOnlyHint=false, destructiveHint=false). The description adds two meaningful traits beyond them: patch semantics (only sent fields change) and the return behavior ('returns the value as it now stands'). It omits permissions or idempotency details, 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?

Front-loaded verb+resource followed by the essential qualifier, then read-first advice and return behavior. Three tight clauses with no filler, though the ordering could put the read-first prerequisite even earlier.

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 13-parameter mutation tool with no output schema, the description covers the critical gaps: patch semantics, a read-before-write workflow, and return behavior. It lacks error/idempotency notes but is otherwise sufficient for correct invocation.

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 77%, so the schema descriptions largely carry the parameter burden (id sourcing, amount units, period semantics). The description adds no syntax or format detail beyond the schema, so the baseline of 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 verb+resource is specific ('Change a direct fee row') and it clarifies the partial-update scope ('only the fields sent change'), which separates it from wholesale replacements. It does not explicitly name the sibling alternatives (add_fee, delete_fee, update_price), so it stops 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 gives a real prerequisite workflow ('read the current value with its read tool first'), which is genuine usage guidance. However, it never states when to choose update_fee over siblings like update_price or delete_fee, so the routing condition is only implied.

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 description discloses two behaviors not covered by annotations: that this is a partial update where unsent fields are preserved, and that the response echoes the value as it now stands. Annotations only tell us it is a non-destructive write; the partial-update semantics are the genuinely valuable addition.

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?

Two compact clauses with the mutation scope front-loaded and the prerequisite and return behavior trailing. Every sentence earns its place; no 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?

For a 9-parameter mutation tool with no output schema, the description covers the key unknowns an agent needs: partial-update behavior, prior read step, and return semantics. It stops short of describing what happens on overlapping seasons or invalid ids, so it is not exhaustive.

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 56% and the description adds no field-level meaning beyond what the schema already states (ids sourced from list_boats and get_pricing). Moderate coverage with no compensating detail lands at the baseline.

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 ('Change a direct season price') and adds the crucial PATCH-style scope note that 'only the fields sent change'. It implicitly separates itself from add_price/delete_price/update_fee, but never names a sibling explicitly, so it falls short of the top mark.

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 a concrete workflow prerequisite: read the current value with the corresponding read tool (get_pricing) before calling. It does not state when to prefer update_discount or update_fee over this tool, so the alternative-selection guidance is incomplete.

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