MyBoracayGuide: Boracay Transfers and Activities

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

Annotations already cover read-only, idempotent, non-destructive, and closed-world behavior. The description adds valuable context beyond annotations: it clarifies that no booking or payment occurs and that the output is a URL to a specific domain, which prevents misinterpretation of 'booking link'.

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 core action and followed by the critical clarification. Every sentence earns its place with no redundancy.

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 link-generation tool with rich annotations and full schema descriptions, the description covers the essential behavioral nuance (no booking/payment) and domain. It could explicitly state the return type (a URL string), but that is strongly implied by 'Make a link'.

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 clear per-parameter descriptions, examples, and constraints. The description only confirms that option, date, and guests are filled into the link, adding no new meaning beyond what the schema already 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?

The description states a specific action (make a link) and resource (myboracayguide.com booking page for an activity), and clarifies it is not a booking or payment. It distinguishes from the transfer booking link sibling implicitly via 'activity', but does not name any 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?

Usage is implied by 'Nothing is booked or paid: the traveller enters their details and pays there', indicating this is for sharing a booking link rather than completing a transaction. However, there is no explicit guidance on when to use this instead of quote_boracay_activity or list_boracay_activities, nor any 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 readOnly/idempotent/non-destructive/closed-world, so the bar is lower; the description still adds real value by stating "Nothing is booked or paid" and describing what the traveller does with the link afterward. It stops short of saying what is returned (a URL string) or whether links expire.

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, no filler. The output artifact and the no-charge guarantee are both front-loaded where an agent will read them before committing.

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?

Rich annotations and a well-described 19-param schema cover most of the burden, but with no output schema the description should say the result is a shareable URL and whether it is reusable — that is the one thing an agent must know to relay it 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?

With 89% schema coverage the schema does most of the work, but the description usefully groups the 19 parameters into three buckets — trip, passengers, and "any traveller details known" — conveying that optional fields may be omitted and completed later. That partial-fill semantics is meaningfully above 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 concrete verb and artifact — "Make a myboracayguide.com link that opens the transfer booking form already filled in" — which is unambiguous and clearly distinct from the sibling create_boracay_activity_booking_link. Scope (transfer booking form) and prefill behavior are both named up front.

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 second sentence establishes the scenario (traveller completes and pays on the site), so usage is implied rather than stated. It never says when to prefer this over routing through list_boracay_airport_transfers or quote_boracay_airport_transfer first, nor when a link is inappropriate.

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, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds genuinely new behavioral context the annotations do not: results are in Philippine time and 'times can differ by day,' warning the agent not to treat times as static. No pagination or empty-result behaviour is described, which keeps it below 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 sentences, zero filler. The scope-defining sentence comes first and the usage hint second, so the most decision-relevant information 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?

With no output schema, the description carries the burden of saying what comes back, and it does so adequately ('flights ... with the time each runs'). Required airport/direction are implicitly covered. It omits what happens on no match or whether the flight filter narrows or merely highlights, which is the main remaining gap for a four-parameter lookup 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 75% and both enums are declared, so the schema does most of the work. The description reinforces the date semantics ('the time each runs on a given date') but adds nothing on the airport choice (Caticlan vs Kalibo trade-off) or on how partial flight numbers are matched — the two places where an agent would most benefit from guidance. Baseline 3.

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 ('List scheduled flights at Caticlan or Kalibo airport') plus the payload ('the time each runs on a given date'). No sibling in the list does anything similar — the others are listing, quoting, and booking-link tools — so an agent can route here 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?

'Use it to match a traveller's flight number to its landing or take off time' gives a concrete retrieval scenario, which is clear context for when to call it. It stops short of explicit exclusions or named alternatives, but the sibling set (booking links, quotes, activity lists) makes mis-selection unlikely.

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, closed-world behavior, so the safety profile is covered. The description adds genuinely useful context beyond that: what the response contains (starting prices, ratings, inclusions, page links), which matters since there is no output schema. It stops short of noting pagination or result count 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?

One dense sentence front-loads the resource and scope, and a short second sentence handles the filter. No filler, no repetition of the title.

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 read-only list tool with no output schema, the description adequately covers what is returned and how filtering works. The only gap is workflow positioning relative to the quote and booking-link siblings.

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 parameter already documents itself with example categories (water, boat, land, mainland, spa). The description only restates that the filter is optional, adding the implicit 'omit to get all' semantics but no syntax or matching rules 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?

States a specific verb (List) and a well-scoped resource: activities and tours on Boracay sold by MyBoracayGuide, with the sub-types enumerated. The returned fields (starting prices in PHP, ratings, inclusions, page links) make it obviously a catalog/browse tool, distinguishing it from the sibling quote_* and create_*_booking_link 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?

Says 'Optionally filter by category,' which implies the default is to list everything, but there is no explicit when-to-use/when-not guidance. It never names the natural next step (quote_boracay_activity) or explains that this tool is for discovery rather than pricing or booking.

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 and closed-world, so the safety profile is covered. The description adds useful scope context — the results are limited to one vendor's packages and include pricing passenger types — but says nothing about result volume or shape.

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 well-formed sentence, front-loaded with the verb and resource, with the route and vendor qualifiers attached rather than buried. 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 parameters, no output schema and full annotation coverage, the description covers enough to call the tool correctly and hints at the returned fields (packages, passenger types). A brief note on what a package record contains or whether results vary by route would close the remaining 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?

The schema has zero parameters, and the description does not invent any, so there is nothing to mis-specify. Baseline 4 applies for a no-parameter tool.

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

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

States a specific verb and resource ('List the airport transfer packages') with the exact routes covered (Caticlan or Kalibo to Boracay hotels), which is enough to distinguish it from the booking-link and quote siblings. It stops short of naming the sibling it hands off to for pricing, so it is clear but not fully differentiated.

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 framing as a catalog listing ('packages MyBoracayGuide sells ... with the passenger types used for pricing') implies this is a browse-first step before quote_boracay_airport_transfer, but that sequence is never stated. No when-not guidance or explicit alternative is 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?

The annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false. The description adds useful context beyond that: it returns the live page price, includes available options, and explicitly does not book anything, though it does not discuss auth, rate limits, or output shape.

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 description is a single efficient sentence with the core action front-loaded. Every clause adds useful information: currency, price fidelity, option listing, and the no-booking constraint.

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 low-complexity read-only quote tool, the definition is nearly complete: annotations cover safety, the schema fully documents inputs, and the description states the returned price currency and that options are included. The only minor gap is that the exact output format for options is not described, but no output schema exists to carry that detail.

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 schema already documents all three parameters, including examples and the note that quote_boracay_activity lists options. The description restates activity, option, and guests but adds no syntax, constraints, or semantics 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?

The description states a specific verb and resource: get the live price in Philippine pesos for a Boracay activity, option, and guest count. It also clarifies the price fidelity (same as the activity page) and that it books nothing, which distinguishes it from the create_*booking_link 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?

The phrase "Books nothing" clearly signals this is for pricing rather than booking, and the activity scope distinguishes it from quote_boracay_airport_transfer. However, no sibling is explicitly named and no prerequisite such as first using list_boracay_activities is stated in the description itself.

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 readOnly, idempotent and non-destructive, so the bar is lower, and the description still adds real context: live pricing, PHP currency, parity with the myboracayguide.com booking form, and that discounts are already applied. It stops short of stating whether the price is cached or can change between calls, or what the returned figure looks like.

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, no filler, and the core purpose is front-loaded before the currency, price-parity and no-booking caveats. Every clause carries information an agent needs.

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 pricing tool with no output schema and fully documented parameters, the description covers purpose, currency, pricing basis and side-effect-free behavior. The one gap is that it never indicates whether the response is a single total or a per-passenger-type breakdown, which an agent might need to present results.

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 a step up by synthesizing that price is driven by package, trip type, airport and passenger mix, telling the agent which inputs actually move the number. It adds no format or default guidance beyond that, but the schema already carries defaults and enums.

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 the live price ... for a Boracay airport transfer') plus the dimensions that define the quote (package, trip type, airport, passengers). The closing 'Books nothing' explicitly separates it from the sibling create_boracay_transfer_booking_link, so an agent can route 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?

'Books nothing' implies this is the quoting step before booking, but the description never names create_boracay_transfer_booking_link or list_boracay_airport_transfers as the follow-up/preceding calls. The package-name prerequisite exists only in the schema description, not the tool description, so usage is implied rather than stated.

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