The Charter Desk

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

Beyond the readOnly/non-destructive annotations it discloses the excluded-taken-departure rule, one-row-per-yacht grouping, paging via total and cursor, the nearest-deals relaxation with a 'nearest' field reporting what was widened, and the reduced row count without a contact. That is exactly the kind of behavior an annotations block cannot express.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded and dense with no filler sentences; the discount-definition rule and default window come first, which is the right priority. It is written as long comma-chained clauses that take effort to parse, costing a point on structure despite the strong information density.

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 35-parameter, zero-required search tool with paging and a relaxation fallback, the description covers the row contents, ordering semantics, cursor paging and what happens on empty results; an output schema exists, so return-shape detail is rightly left out.

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 every one of the 35 filters is documented in-schema, so the baseline of 3 applies. The description adds only modest cross-parameter meaning: sort order ('in the order asked'), the parenthetical tying the yacht page id to get_yacht and request_quote, and session reuse — all useful but not compensating for anything missing.

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?

It opens with a specific verb and resource — 'Discounted departures of this site's yachts, read from the live inventory' — and immediately bounds what counts as a deal ('only a discount the source itself states ... never a computed gap'). That distinguishes it cleanly from search_yachts, which returns general inventory rather than source-stated discounts.

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 the default window ('tomorrow to 30 days ahead'), the fallback policy when nothing matches, and the contact/no-contact tradeoff ('browsing: fewer rows'). What it doesn't do is state explicitly when to call this instead of search_yachts; it only says 'Narrow with the same typed filters as search', which implies lineage rather than a selection rule.

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, and the description adds genuinely useful context beyond them: absent fields mean the source does not state them, unavailable stays return the nearest free alternatives, and the call works without a contact. It stops short of describing response shape or pagination, but the output schema covers that.

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 core content is front-loaded and every clause carries information, but the main sentence is a single long run-on stuffed with parenthetical enumerations that is slow to parse. The final two sentences ('A field that is absent...', 'Works without a contact') are tight and well-placed.

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 10-parameter tool with an output schema and full schema coverage, the description supplies the pieces structured fields cannot: absence semantics, availability fallback behavior, and no-contact operation. Sibling routing is the one 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 coverage is 100%, so the baseline is 3; the description earns above that by explaining what from/to actually change (stay status and price, or nearest free stays) and that omitting dates yields free stays soonest-first. It does not add detail on cursor, limit, or session beyond the schema text.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific resource and enumerates exactly what is returned: facts, terms (packages, extras, deposit, check-in, stay limits, equipment), and availability. It is clearly a single-yacht detail fetch rather than a list, though it never names search_yachts or best_deals to make the split explicit.

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 with-dates vs without-dates branching is spelled out, but that is parameter behavior, not tool selection. Nothing tells the agent when to call get_yacht instead of search_yachts or best_deals; the routing hint ('as a search or best_deals returned it') lives in the schema, not the description.

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 readOnly/non-destructive annotations, the description discloses what is returned (p25/median/p75 in minor units, item count, cheapest published fitting option, build timestamp, seasonNote) and two useful behaviors: unknown places degrade to a list of places that do have figures, and no contact is required. It doesn't explain pagination or the session/email escalation flow, 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?

The core purpose is front-loaded, but the opening sentence is a heavily stacked clause chain strung together with semicolons and commas that is hard to parse on first read. Every element roughly earns its place, but the structure could be broken into shorter, scannable statements.

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 an output schema present the description needn't explain return values, yet it does, and it also covers the unknown-place fallback and contactless operation. However, for an 8-parameter tool it never mentions session, email, or phone escalation ('more rows'), leaving that mechanism to the schema alone.

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 eight parameters including the optional type filter, session, and contact fields. The description restates the place/month/party/type relationship and adds the units context (minor units of the currency), but does not clarify session, email, phone, or name usage beyond what the schema says. 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 resource and what it returns: the p25/median/p75 range of open departures for a place, month and party, plus counts and a cheapest-published figure. An agent can tell this is a price-statistics lookup rather than a booking or listing tool. It doesn't name or differentiate itself from siblings like best_deals, keeping it below 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 when-to-use or when-not guidance, and no sibling is named as an alternative even though best_deals and search_yachts sit alongside it. The only conditional statements ('An unknown place answers with the places that have figures', 'Works without a contact') describe fallback behavior, not tool selection.

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 that the desk replies out-of-band to the person's own email or phone, that this tool's own answer only confirms receipt and the destination, and that nothing is booked or paid until the person confirms with the desk. Those are exactly the side-effect facts an agent needs and none are derivable from readOnlyHint=false / destructiveHint=false alone.

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 purpose, then inputs, then outcome, then the safety constraint — a sensible ordering with no filler. The sentences are long and comma-heavy, which costs a little scannability, but 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 an output schema present and full schema coverage, the description only needs to supply the semantics the structured fields cannot: the out-of-band delivery, the non-booking nature, and the consent requirement. It supplies all three, leaving no material gap for a 9-parameter 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 description coverage is 100%, so the schema already explains every parameter including the email/phone/session fallback and the 20-item cap. The description restates the same groupings ('the page links... the days and the party... anything the person wants the desk to know') without adding format or constraint 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?

States a specific verb and resource ('Ask this site's desk for a formal quote on one or more yachts') and makes clear it is a downstream step from the search tools, not a search itself. An agent can distinguish it from search_yachts, best_deals, get_yacht and price_range 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?

Explicitly says to pass the page links that 'a search, best_deals or get returned', which establishes the correct call ordering relative to siblings, and adds the consent rule 'Ask the person before calling it.' It stops short of naming an explicit when-not or a named alternative for a different outcome, but the usage context 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?

Goes well past the readOnly/destructive annotations: with dates it returns ONLY yachts free for that stay with stay status, price, list price, discount and checkedAt; without dates each row has a from-price. It discloses the nearest-match widening behavior with a nearest explanation to relay, notApplied for unsatisfiable filters, cursor/total pagination, and the lower row cap when no contact is supplied.

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 every clause carries substance given 36 parameters and a non-obvious fallback model. The single dense paragraph with sentence fragments ("Paged: total and cursor") reads as a wall of text, which makes the fallback and pagination rules easy to skim past.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, yet the description still covers result shape, fallback behavior, pagination and contact-gated row limits, plus the instruction to send the person to the absolute page link. For a 36-parameter, zero-required search tool this leaves nothing 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 coverage is 100%, so the baseline is 3, but the description adds real semantics the schema lacks: within a list any value matches, across filters every filter must hold, priceMin/priceMax count mandatory extras, and session should replace email/phone on later calls. It does not explain the interplay of place and base or how party affects date-based results.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb and resource plus scope: "Find this site's yachts, read from the live inventory." An agent knows exactly what the tool retrieves and that results are live rather than cached. It never names a sibling, though, so nothing explicitly separates it from best_deals or price_range for an agent comparing candidates.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives concrete calling conditions: pass typed filters for what the person wants, pass from/to only when exact days were given, and omit email/phone to browse (fewer rows). It also states the fallback contract when nothing matches exactly. It stops short of naming when to prefer a sibling such as get_yacht or best_deals.

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