MAPL Tours Jamaica

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

With annotations only stating readOnlyHint=false, idempotentHint=false and destructiveHint=false, the description supplies the critical facts the agent actually needs: it CHARGES the traveller, an already-paid identical ride is reported and never charged twice, and the token must have been traveller-approved. That is meaningful behavior beyond the structured hints.

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 the charge warning, then the prerequisite checklist, then the dedup and return-value guarantees. Dense but every sentence carries information; only the multi-prerequisite sentence is slightly overloaded.

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, nested-object, payment-taking tool with no output schema, the description covers the charge, the prerequisite sequence, required traveller data, duplicate handling and the return value (booking reference, email follows). Nothing needed to invoke it safely 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 already 85%, so the baseline is 3; the description goes further by tying approved_total_usd to the quote, specifying the guest fields needed (name, email, phone) and requiring every flight number/time. It doesn't explain direction/trip_type interplay, but adds real value over the schema.

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

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

States a specific verb pair (book and pay) plus the resource (airport transfer) and the payment mechanism (Stripe spt token), which clearly separates it from sibling quote/terms/start tools. An agent reading only the first sentence knows exactly what this does.

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 precondition chain ('Before calling: get the exact price with get_transfer_quote, tell the traveller the price and the cancellation terms (get_booking_terms), and get their explicit yes'), naming the sibling tools to call first. It does not, however, explain when to use this versus the unmentioned start_transfer_booking sibling, leaving one routing ambiguity.

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

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

Annotations already declare readOnlyHint/idempotentHint, so safety is covered, but the description adds the non-obvious 12-hour notice business rule, the Jamaica-time constraint, and a summary of what is returned (bookability per leg plus earliest bookable time). The trailing 'Read-only' restates the annotation but the rest adds real 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 purpose, then prerequisites, then parameter guidance, then the return summary — a logical order with no filler. It is dense in a single paragraph, but each clause carries actionable 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 compensates by summarizing the return (per-leg bookability and earliest bookable time), and it specifies the exact input format and timezone for all three optional parameters. An agent has everything needed 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?

Schema coverage is 100%, so baseline is 3, but the description adds meaning beyond the schema by disambiguating departure_at (hotel pickup) from departure_flight_at (flight departure, pickup derived from it) and presenting them as alternatives for the return leg. That relational framing is not in the individual property descriptions.

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 — checking whether a pickup can be booked online — with the scope of both legs (arrival and flight home). It is clearly distinguishable from the sibling booking tools (book_and_pay_transfer, start_transfer_booking) because it only checks eligibility rather than transacting.

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 clear precondition (12 hours' notice in Jamaica time) and explains which parameters apply to which leg, which tells the agent when the tool is applicable. It stops short of naming alternatives or stating exclusions (e.g. 'use book_and_pay_transfer to actually book'), so it is strong context but not a full when/when-not guide.

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 safety (readOnly, idempotent, non-destructive, closed-world), and the description adds real behavior beyond them: capped at 8 matches, a per-area "Other hotel or villa" fallback id when nothing matches, and 199 properties across named regions. It also discloses the out-of-scope regions handled by email instead, which prevents a dead-end call.

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, each carrying distinct load: what is searched, what comes back, coverage extent, and where the tool does not apply. The return-shape and fallback id lead before the regional caveat, so the most decision-relevant facts are 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?

No output schema exists, and the description compensates by stating result count, return id semantics, and the no-match fallback. For a one-parameter read with full annotation coverage, nothing an agent needs in order to call it correctly or interpret the response is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the single query parameter is fully described there, so the schema does the heavy lifting. The description adds only indirect signal about input tolerance (town names as well as property names, implied by the area/fallback behavior), which is a marginal gain over the existing example-bearing schema.

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

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

States a specific verb and resource ("Find hotels and villas"), scopes it geographically to properties served from MBJ, and ties the output to a sibling ("the id to use in get_transfer_quote"). An agent can distinguish this lookup step from booking/quote/pricing siblings 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 routes the agent: use this to obtain the id consumed by get_transfer_quote, and use email quoting for Kingston, Port Antonio and Mandeville. It gives a clear when-to-use context and a regional exclusion, but never names the other siblings (check_transfer_timing, get_booking_terms) or says those should be called after this one.

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, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered; "Read-only" in the description merely repeats this. The description adds the useful behavioral fact that this is static policy content to be surfaced to the traveller before booking, but says nothing about freshness, scope of applicability, or failure modes.

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 scope and content inventory; every clause carries information about what the tool returns. Minor waste in the trailing "Read-only," which duplicates the annotation.

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 parameters and no output schema, the description carries the full burden of telling the agent what comes back, and it does so by enumerating the policy topics covered. An agent has enough to decide to call it and to relay the content to a traveller.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, which is the baseline-4 case: there is nothing for the description to disambiguate beyond what the empty schema already conveys.

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 (MAPL Tours Jamaica booking terms) and enumerates the content it returns: pricing, notice, flight tracking, cancellation/refunds, payment methods, contact. This clearly separates it from the action-oriented siblings (start_tour_booking, get_transfer_quote), though it never names an alternative 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?

"Tell the traveller the cancellation terms before they book" gives a concrete when-to-use trigger tied to the booking flow. It is clear context but stops short of naming alternatives or stating when this tool is NOT the right one (e.g., for a specific tour's terms).

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the trailing 'Read-only.' is redundant. What earns credit is the substantive disclosure about the response itself: the duration vs fromHotelAndBack distinction, the Full day/Half day convention, that price is an exact total for a party size, and that the earliest bookable date is included.

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 leads with the core purpose and enumerates the return contents, followed by a short clarifying clause. It is front-loaded and mostly waste-free, though the trailing 'Read-only.' adds nothing given the annotations.

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

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

With no output schema, the description carries the burden of describing the returned data and does so field by field, while the annotations cover the safety profile. Nothing essential for correct invocation appears missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is already 100%, but the description adds real meaning: it clarifies that pricing depends on party size ('the exact total for a party size') and explains the vehicle/time semantics surrounding fromHotelAndBack and duration, which the two schema fields alone do not convey.

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 ('Details for one tour') and enumerates exactly what is returned: inclusions, ages, fitness, what to bring, duration, price total, and earliest bookable date. This clearly separates it from list_tours (enumeration) and start_tour_booking (mutation).

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 — an agent can infer this is the detail/price lookup for a single tour, and the schema points back to list_tours for the identifier. However, the description never explicitly says when to use it versus alternatives (e.g., list_tours, start_tour_booking) or states any prerequisite.

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, idempotentHint=true and destructiveHint=false, so the closing 'Read-only' is redundant. Beyond the annotations, the description discloses the pricing model (per vehicle up to 4, per person for 5-7), the email escalation path for 8+, and that a timing recommendation is returned — genuinely useful behavioral context an agent cannot get from structured fields.

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 core purpose and price scope, then degraded gracefully into the edge-case parenthetical and the sequencing hint. The nested parenthetical about 5-7/8+ passengers is dense but each clause carries information; only the trailing 'Read-only' duplicates the annotations.

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 return-value burden and does name the two key outputs (all-in price, recommended pre-flight pickup time). Combined with full schema coverage and complete read-only annotations, an agent has what it needs, though the exact response shape and currency/multi-vehicle handling remain implicit.

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 still earns an increment by explaining the capacity-to-pricing relationship tied to the 'passengers' parameter and confirming that round trip / one way applies in either direction, which the schema's enums alone don't convey.

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 (returns exact all-in USD price for a private airport transfer between MBJ and a hotel/villa), plus the scope constraints around vehicle capacity and party size. It also names the sibling it precedes (start_transfer_booking), so an agent can distinguish it from start_transfer_booking or get_tour 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 a clear sequencing rule ('Use before start_transfer_booking') and a routing rule for out-of-scope requests (8+ passengers must email). It does not address the overlap with check_transfer_timing, even though the description claims this tool returns pickup-timing guidance that the sibling presumably also covers.

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

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

Annotations already declare readOnly/idempotent/openWorld=false, so safety is covered. The description adds real context: fromPriceUsd covers the smallest party, priceUnit disambiguates per-person vs per-party, up to 12 rows returned, hotel pickup included, and duration excludes transfer time – all disclosed caveats that prevent misreading 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?

Front-loads scope and offering examples, then bundles the pricing and duration caveats efficiently. Dense but nearly every clause conveys a usable fact; the parenthetical tour list is the only slightly expendable part.

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 fields (fromPriceUsd, priceUnit, duration) and does so adequately. Minor gap: it doesn't describe the shape of returned rows beyond pricing and duration, though for a list tool this is close to complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with both 'area' and 'query' already documented with examples, so the baseline is 3. The description only says 'Optional keyword or area filter' without adding syntax, matching behavior, or precedence beyond what the schema provides.

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 (list), resource (private tours and day packages), operator and geography, plus concrete example offerings. It clearly separates itself from get_tour by scoping this as the browse/list entry point rather than the detail lookup.

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 the agent: 'Use get_tour with guests for the exact total' for precise pricing, while this tool returns fromPriceUsd. It also states the filters are optional and the row cap, so an agent knows what to expect without trial-and-error.

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 by disclosing that the tool reserves and charges nothing itself, that the traveller completes checkout elsewhere (contact details, waiver, payment), and that a 12-hour lead time applies. This is exactly the workflow context annotations cannot convey, and it is consistent with readOnlyHint/destructiveHint=false.

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 core action, then the downstream flow, the non-charging guarantee, and prerequisites in a tight sequence. Every sentence carries actionable 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 link-generating tool with no output schema, the description fully specifies the effect (a checkout link pre-filled with tour, date and guests), the prerequisites, and the required traveller confirmation. 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 75%, so the schema already documents date, tour and pickup_hotel. The description reinforces meaning by framing date against the 12-hour notice rule and guests as 'party size', and adds the confirmation step, though it does not explain the guests 1-12 bound or pickup_hotel's role.

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 ('Make a mapltours.com booking link for a tour or day package'), plus the scoping inputs (date, party size). It clearly contrasts with the transfer siblings (start_transfer_booking, book_and_pay_transfer) by naming the tour/product domain and its non-charging nature.

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 when-to-use conditions: needs 12 hours' notice, consult get_tour for earliest date and price, and confirm tour/date/guests/price with the traveller first. Prerequisites and the informational alternative are explicit, leaving nothing to inference.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and idempotentHint=true, so the safety profile is covered. The description adds genuinely new behavioral context: the link lands the traveller on checkout with fields pre-filled, payment is handled by the traveller (card/Apple Pay/Google Pay/Link), and the tool itself books and charges nothing.

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 definition is front-loaded with the core action and outcome, and every sentence carries information. The direction/flight-field sentence is dense and semicolon-packed, but it earns its space by encoding conditional requirements.

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 link-generation tool with no output schema and 78% parameter coverage, the description covers what the tool produces, what the end user must supply, the prerequisite quote step, and per-direction input rules. Only the absence of explicit failure/edge-case behavior keeps it from being fully complete.

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 78%, so the baseline would be 3, but the description adds conditional semantics the schema does not encode: airport_to_hotel pairs with arrival_at and arrival_flight, while hotel_to_airport uses departure_at (or departure_flight_at) plus departure_flight. That dependency mapping is real value beyond the field-level descriptions.

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

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

The description states a specific verb and resource — 'Make a mapltours.com booking link for an airport transfer' — and immediately clarifies the scope by saying it 'Books and charges nothing by itself.' This clearly separates it from siblings like get_transfer_quote (pricing) and start_tour_booking (a different product).

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 concrete prerequisite — 'Confirm the details and the price from get_transfer_quote with the traveller first' — and spells out which inputs each trip direction requires. It stops short of stating when not to use the tool, so it is strong but not exhaustive.

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