Search and book live flights and hotels. No API key; the traveller confirms on their phone.
Scored across 15 tools
Most tools map to a distinct resource+action in the booking lifecycle (search, offer, book, cancel, pay, support), and descriptions helpfully state when to use each. The main soft spot is get_booking_status vs get_booking_progress, whose boundary (live payment state vs 'progress of the newest booking for the Vuelo widget') is not obvious, and change_package_flight reads like a search tool despite the 'change' verb.
Every tool is snake_case verb_noun (book_trip, cancel_booking, get_offer, resend_link, update_travellers), with get_/search_/change_/send_ prefixes used predictably. No camelCase or stylistic mixing anywhere in the set.
15 tools sits at the top of the well-scoped range and each one earns its place: search, offer detail, book, two payment paths, status, cancel, traveller edits, support, and link resend all reflect real steps a traveller takes. There is no filler or duplicate tool bloating the surface.
The core journey is fully covered end to end: search_trips → get_offer → book_trip → get_booking_status → change_payment_option/cancel_booking, plus post-booking support, traveller corrections and link resend. The notable gap is that post-payment modifications (dates, name changes, refunds) route out to contact_support rather than having direct tools, and there is no tool returning full details of an existing booking without texting a link.
Bookings are made under Vuelo's Booking Terms and Conditions (https://getvuelo.com/uk/legal/terms-of-booking-service/); the Vuelo card and pay page show them. Start booking a Vuelo offer, by the offerId and paymentOption that search_trips returned; call it whenever the traveller asks in the chat to book one. The Vuelo card then shows the traveller a Pay button that opens Vuelo's secure page (Apple Pay, Google Pay or a card), or, where there is no card or they ask for one, Vuelo texts them a secure link; nothing is booked until they pay. Never show a link in the chat, except a passkey approval link Vuelo returns for you to show. Pre-fill: pass everything you already know about the traveller, from this conversation or what you know about the user, so checkout is a single tap with nothing to type: leadTraveller (full name as on their ID, email, date of birth, home postcode), mobile, and for flights each passenger's name, date of birth, title and gender. Never guess or invent any of it; ask only for what Vuelo says is missing, once, in one message. Flights cannot book without each passenger's name and date of birth. To change how an open booking is paid for, use change_payment_option (calling book_trip again with another paymentOption does the same). Do not wait for the traveller to tell you they have paid: pass notify_url to hear the moment they open the link, pay or cancel, or straight after sending the link call get_booking_status with wait_seconds: 50, which answers the moment they pay. Then tell them it is booked, with the reference.
| Name | Required | Description | Default |
|---|---|---|---|
| host | No | Which assistant this is, so the Vuelo page names it and matches its look. One of: chatgpt, claude, gemini, meta, instinct, openclaw, perplexity, copilot, mistral, grok, poe, duckduckgo. Optional, and an unrecognised value is simply ignored rather than refused. | |
| payer | No | Only when the traveller says someone else is paying (a friend, a partner, a parent): their name and mobile or email, as the traveller gives them. Vuelo then sends the secure link to that person instead of the traveller; they pay in full from their own Vuelo account. Ask who is paying before booking if the traveller has mentioned it. The traveller still gets the confirmation at their own mobile, if given. | |
| mobile | No | Mobile number to text the link to (any country; international format outside the UK). Not needed for returning customers, or if you already passed it to search_trips in this conversation. If you already know it from this conversation or from what you know about the user, pass it rather than asking again: Vuelo then texts the link at once, with nothing for the traveller to type. | |
| offerId | Yes | ||
| delivery | No | How the confirmation reaches the traveller. Leave it out: a card payment always goes by text to the traveller's mobile, and a no-card reservation by a Confirm button in the Vuelo card. qr and on_device are no longer offered and are treated as a text. Defaults to a text message, or to a Confirm button in the Vuelo card when nothing needs paying now. | |
| from_card | No | Set only by the Vuelo card. Leave it out. | |
| notify_url | No | Your own https address. The moment the traveller confirms on their phone, Vuelo POSTs it a booking.confirmed event (reference, trip, dates, amount), so you can tell them without being asked. Optional. | |
| travellers | No | Each passenger, as on their passport, with their title and gender where you know them (airlines need both). If the traveller has already told you who is flying, pass them rather than making them type it again. Leave it out for a returning traveller: Vuelo fills in its own saved passengers and asks you to confirm them. | |
| consumer_ref | No | The vc_ reference Vuelo gave you after this traveller authorised you to book for them within limits. Only if you already hold one; never ask the traveller for it, or mention it to them: they do not have one to give. With it, Vuelo books inside their limits without a payment step, or asks them to approve with their passkey. Without it, book as usual: the traveller pays with one tap on Vuelo's secure page. | |
| notify_token | No | A secret of yours. Vuelo sends it back in X-Vuelo-Notify-Token and signs the event with it (X-Vuelo-Signature: sha256=HMAC). Optional. | |
| leadTraveller | No | The traveller booking: name, email, date of birth and home postcode, town and county, as far as you know them. Pass whatever you already know from this conversation or about the user rather than asking: Vuelo logs them straight in, or fills in their Vuelo account so they only check it and accept Vuelo's terms. For a traveller new to Vuelo, their Vuelo account needs their name, date of birth and home postcode, town and county: pass them if you know them, or ask once before booking, so the pay page is one tap. Never invent any of it. | |
| paymentOption | Yes | One of the options search_trips returned as eligible | |
| conversationId | No | ||
| travellersConfirmed | No | Set true when the traveller has confirmed the passengers Vuelo filled in and named back to you. Vuelo asks for this once, before it starts a booking with saved passengers. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well past the annotations: nothing is booked until payment, the traveller sees a Pay button on the Vuelo card or an SMS link, links must never be shown in chat except a passkey approval link, and payer/consumer_ref paths change the flow. This is consistent with readOnlyHint=false and idempotentHint=false, and no claim contradicts 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?
A single dense paragraph where nearly every sentence carries operational guidance, but the opening is a legal T&C link rather than the action, and the "never invent any of it" instruction is repeated in both the description and the leadTraveller schema. Minor front-loading and redundancy costs.
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 14-parameter, nested-object, no-output-schema mutation tool, it covers the end-to-end flow (pre-fill, pay link, notify, status poll, confirm with reference) well enough to call correctly. The only soft spot is that the response shape is only implied by "tell them it is booked, with the reference".
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 86%, and the description reinforces the highest-risk fields with intent rather than syntax: what to pre-fill into leadTraveller and travellers, that flights cannot book without passenger name and date of birth, and that nothing may be guessed. It adds little on consumer_ref, conversationId, delivery, or from_card, but the schema carries those.
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+resource ("Start booking a Vuelo offer") and pins it to the required identifiers (offerId, paymentOption) that search_trips returned. It also draws an explicit boundary against the nearest sibling by name, stating that changing payment on an open booking is change_payment_option.
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 the trigger condition directly ("call it whenever the traveller asks in the chat to book one"), names the alternative for the adjacent case (change_payment_option), and prescribes the follow-up (notify_url or get_booking_status with wait_seconds: 50 rather than waiting for the user to say they paid). Nothing about when/when-not is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Cancel a Vuelo booking, before or after the traveller confirms. Pass the taskId if it was made in this conversation; from any other conversation, a made booking can be cancelled with its Vuelo reference (VU-...) and the email or mobile it was booked with. Not confirmed yet: it is called off at once, the texted link stops working and nothing was charged. Already booked: call it first with preview: true and tell the traveller what they would get back (refund.amount, summary). If they want to go ahead, call it again without preview. A reservation with nothing paid is cancelled at once. For anything paid, Vuelo texts the traveller a six-digit code and nothing is cancelled until it is given: ask them for it and call again with code (they can also enter it on their booking page). Never guess a code, and never say a paid booking is cancelled until this or get_booking_status says so.
| Name | Required | Description | Default |
|---|---|---|---|
| code | No | For a paid booking: the six-digit code Vuelo texted the traveller, as they gave it to you. Finishes the cancellation and the refund. | |
| No | With reference: the email the traveller booked with. | ||
| mobile | No | With reference, instead of email: the mobile on the booking. | |
| taskId | No | The taskId book_trip returned, when the booking was made in this conversation. | |
| preview | No | true: only say what cancelling would refund, changing nothing. | |
| reference | No | Otherwise: the Vuelo booking reference (VU-...). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag destructive/openWorld/idempotent, but the description adds real operational context beyond them: the texted link stops working, nothing was charged if unconfirmed, unpaid confirmed reservations cancel immediately, paid ones require a six-digit code and nothing is cancelled until it is supplied. It also warns not to claim a paid booking is cancelled until this tool or get_booking_status confirms it.
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?
Dense and front-loaded: identity resolution comes first, then the unconfirmed case, then the confirmed/paid flow. It runs long, but for a multi-step destructive flow nearly every sentence carries a distinct constraint; a tighter edit would still help.
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 compensates by naming the preview return fields (refund.amount, summary) and stating the confirmation source of truth. Nothing an agent needs to call this 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 100%, so the baseline is 3, but the description adds conditional pairing logic the schema states only piecemeal: taskId is the in-conversation path, while reference requires email or mobile as an alternative identifier. The preview and code semantics are restated with the sequencing that makes them actionable.
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 ("Cancel a Vuelo booking") plus the scope that matters most ("before or after the traveller confirms"). This clearly separates it from read-only siblings like get_booking_status and find_my_booking.
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?
Explicit routing: pass taskId when the booking came from this conversation, otherwise reference (VU-...) plus the email or mobile used to book. It also prescribes a two-step protocol for confirmed bookings (call with preview: true first, then without) and a code step for paid bookings, with a hard exclusion ("Never guess a code").
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
For a flight-and-hotel package from search_trips: every other flight for the same route and dates, each priced as a package with the same stay, with what it costs each traveller more or less than the current flight. The Vuelo card uses this for its Change flight list; call it yourself when the traveller asks for other flights for a package, then book the offerId they choose.
| Name | Required | Description | Default |
|---|---|---|---|
| offerId | Yes | The package offerId from search_trips |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive, so the safety profile is covered. The description adds genuinely new behavior: it is a re-quoting operation that re-prices alternatives with the same stay and reports price deltas, and it names the downstream step (booking the chosen offerId). Return shape/pagination is not described, but with a read-only single-offer quote that is a minor 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?
Two sentences, front-loaded with the core result, then the usage trigger and next step. No filler; the UI reference ('The Vuelo card uses this') is the only mildly extraneous clause and it still orients the agent.
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?
Single required parameter with full schema coverage and no output schema, and the description compensates by explaining what comes back (alternative flights, package pricing with the same stay, price deltas). An agent has everything needed to call it and act on 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 the baseline is 3, and the description goes further by pinning the offerId's provenance ('from search_trips') and clarifying that the offerIds returned are themselves bookable. That chaining semantics is real added meaning 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?
States a precise verb and resource: returns every other flight for the same route and dates, each re-priced as a package with the same stay. It also says what makes the result meaningful (per-traveller price difference vs the current flight), which no sibling tool 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 trigger ('call it yourself when the traveller asks for other flights for a package') and the follow-up action ('book the offerId they choose'), plus the prerequisite that the offer originates from search_trips. No explicit when-not or named alternative for a fresh search, but the usage path is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
When the traveller wants to pay a different way (for example reserve now instead of paying in full) before they have confirmed. Switches the open booking to that paymentOption; the link already texted stays the same and opens with the new choice, so nothing new is sent. Only an option the trip lists as available.
| Name | Required | Description | Default |
|---|---|---|---|
| taskId | Yes | ||
| paymentOption | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover the safety profile (not read-only, idempotent, non-destructive), and the description adds real context beyond them: the change only applies to an unconfirmed/open booking, the already-sent link keeps working so nothing new is dispatched, and only trip-listed options are accepted. Those are exactly the side-effect and precondition details an agent needs before mutating state.
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 situation, then the action, then the side effects, in roughly three sentences with no filler. The trailing fragment 'Only an option the trip lists as available' is slightly clipped, but it still earns its place as a validity 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 two-parameter mutation with annotations and no output schema, the description covers trigger, precondition, side effects and option validity. The remaining gaps — what taskId actually identifies and what happens when an unavailable option is supplied — keep it from being 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 description coverage is 0%, so the description carries the burden: it explains paymentOption's meaning and restricts it to trip-available values, which reinforces the enum. However, taskId is never explained — an agent cannot tell whether it is a booking id, a trip id or a task handle — so half the input surface is still undocumented.
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: switches an open booking to a given paymentOption, with the precondition that it happens before confirmation. The clause about the existing link staying the same implicitly separates it from siblings like resend_link and send_to_payer, so an agent can pick it 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?
Gives a clear trigger condition (traveller wants a different payment method before they have confirmed) and a validity constraint (only an option the trip lists as available). It does not name a named alternative or state explicitly when not to use it, so it stops short of the top band.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send the traveller's request to Vuelo's support team, who will be in touch with them. Use it whenever the traveller wants something done to a Vuelo booking that the other tools cannot do, or wants a person: change dates or names after paying, a refund question, a payment problem, a complaint, anything. It works in any conversation: pass the taskId if the booking was made in this chat; otherwise their Vuelo booking reference (VU-...) and the email or mobile they booked with, or just their email if they have no reference. To cancel a booking made in this chat, use cancel_booking first: it raises the request itself when Vuelo's team has to do it. Write the message in the traveller's words, with what they want and why. Tell them the ticket reference and reply time this returns.
| Name | Required | Description | Default |
|---|---|---|---|
| No | The email the traveller booked with: needed when there is no taskId, or when this tool asks for it. | ||
| topic | Yes | What the request is about. | |
| mobile | No | With reference, instead of email: the mobile on the booking. | |
| taskId | No | The taskId book_trip returned, when the booking was made in this conversation. | |
| message | Yes | What the traveller wants, in their words. | |
| reference | No | The Vuelo booking reference (VU-...), when there is no taskId. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations (readOnlyHint=false, openWorldHint=true, destructiveHint=false) establish that this is a non-destructive write, and the description adds the genuinely useful behaviour: the request goes to a human team who 'will be in touch', and the call returns a ticket reference and reply time that must be relayed. It does not warn that repeated calls create separate tickets (relevant given idempotentHint=false) or that the handoff is asynchronous with no guaranteed SLA, which keeps it off 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 with purpose, then alternatives, then the parameter decision tree, then the follow-up obligation — a sensible order with no filler. Some sentences are long and stack multiple clauses, but each one carries a distinct instruction.
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 open-world, non-idempotent write with no output schema, the description covers purpose, exclusions, credential selection, message authoring, and even the return payload (ticket reference and reply time). An agent could call this correctly with no 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 baseline would be 3, but the description adds real routing logic the schema only hints at: taskId when the booking was made in this chat, otherwise reference plus email/mobile, or just email when there is no reference. It also specifies message content ('in the traveller's words, with what they want and why'). The enum values for topic are left to 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 and resource ('Send the traveller's request to Vuelo's support team') and explicitly scopes the tool as the catch-all for tasks 'the other tools cannot do, or wants a person'. That single clause differentiates it from every sibling in the list (cancel_booking, change_package_flight, get_support_ticket, etc.) without the agent needing to open 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 positive conditions (change dates/names after paying, refund question, payment problem, complaint, anything) and an explicit negative with the correct redirect: 'To cancel a booking made in this chat, use cancel_booking first'. It also resolves the ambiguous middle case by noting cancel_booking raises the request itself when Vuelo's team must act.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
For a traveller who booked with Vuelo before, in another conversation, and wants to see, change, cancel or get help with it: Vuelo texts the booking's own page to the mobile on that booking. On that page they can cancel, add it to their calendar, and contact Vuelo's team. Pass their Vuelo booking reference (VU-...) and the email or mobile they booked with. You never see the link or whether it matched, so tell them: if the details match a booking, Vuelo has texted its page to the mobile on it. For anything else they want a person for, use contact_support.
| Name | Required | Description | Default |
|---|---|---|---|
| No | The email the traveller booked with. | ||
| mobile | No | Or the mobile on the booking, instead of the email. | |
| reference | Yes | The Vuelo booking reference, VU-... |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds crucial behavior beyond annotations: the tool sends an SMS to the mobile on the booking, the agent never sees the link or whether it matched, and the agent must tell the traveller a specific conditional message. This is exactly the kind of side-effect and privacy context an agent needs.
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 audience and action, then adds only necessary side-effect and user-messaging details. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and an open-world SMS side effect, the description supplies the missing outcome behavior and the exact fallback message. Nothing essential for correct invocation is 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 coverage is 100%, so the schema already documents the reference, email, and mobile parameters. The description only restates the reference format and the email-or-mobile choice, adding little beyond the structured 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 action and resource: Vuelo texts the booking's own page to the mobile on that booking. It also distinguishes the scope from contact_support by naming that sibling for person-help requests.
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: a traveller who booked before in another conversation and wants to see, change, cancel, or get help with it. It also gives the alternative: use contact_support for anything else they want a person for.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Progress of the newest booking for an offer, or the newest booking of all, for the Vuelo widget.
| Name | Required | Description | Default |
|---|---|---|---|
| offerId | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this as a safe, idempotent, non-destructive read operation, so the safety profile is covered. The description adds useful selection semantics ('newest booking') and offer scoping, but it does not explain what 'progress' includes, what happens when no booking exists, or any authorization 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?
The description is a single efficient sentence with the scope and filtering behavior front-loaded and no wasted clauses.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple and annotations cover its safety profile, but with no output schema the description should clarify what 'progress' returns or what empty results look like. As written, an agent can infer basic selection behavior but not the response shape or failure modes.
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 0% schema description coverage, the optional offerId parameter is documented only by the schema type and name. The description partially compensates by explaining that offerId scopes the result to the newest booking for an offer and that no offerId means the newest booking of all, but it gives no format or validation details.
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 identifies the specific resource (booking progress), the selection scope (newest booking), and the optional offer filter. However, it does not explicitly distinguish this tool from the sibling get_booking_status or find_my_booking, leaving some ambiguity about when this progress view differs from a status 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?
The description implies that providing an offer targets the newest booking for that offer and omitting it targets the newest booking overall, but it gives no explicit when-to-use guidance and names no alternatives among the many booking-related sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The current state of a Vuelo booking started with book_trip. Pass wait_seconds (up to 50) straight after the traveller has the link: it answers the moment they open it, pay or cancel, so you can tell them it is booked without being told.
| Name | Required | Description | Default |
|---|---|---|---|
| taskId | Yes | ||
| wait_seconds | No | Hold the answer until the booking changes, up to this many seconds. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, idempotent, non-destructive, and closed-world. The description adds real behavioral context beyond them: wait_seconds blocks until the booking changes, up to 50 seconds, and returns as soon as the traveller opens, pays, or cancels. It does not explain timeout behavior or returned states, but the blocking semantics are clearly disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose and followed by the most actionable usage detail. The final clause ('without being told') is slightly awkward, but the definition is compact and has 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 simple two-parameter status tool with annotations, the description covers purpose and wait behavior. However, with no output schema it should say more about the states returned (e.g., pending, paid, cancelled) and what happens if wait_seconds times out without a change.
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 50%: wait_seconds has a schema description, and the tool description reinforces its meaning and timing ('answers the moment they open it, pay or cancel'). The required taskId has no description in either place, and the description only implies it comes from book_trip rather than explicitly saying so.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence gives a specific verb and resource ('current state of a Vuelo booking') and ties it to book_trip as the originating call. However, it does not distinguish itself from the close sibling get_booking_progress, leaving ambiguity about which status/progress tool to pick.
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 useful timing guidance for wait_seconds ('straight after the traveller has the link') so the agent knows when to poll. But it never states when to use this versus get_booking_progress or find_my_booking, and gives no when-not conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Live rooms and prices at ONE hotel the traveller already has in mind, for their dates and number of guests, without searching the whole town. Pass the reference you hold: a Vuelo hotel link (https://…/h/…), an offerId from an earlier Vuelo search, a Vuelo property_id (VHP_…) or a hotel id from a Vuelo search. Use it when the traveller shares a Vuelo hotel link or asks about the same hotel on other dates. The result appears in the Vuelo card. No result means the hotel has nothing for those dates or is not one Vuelo can sell: say so, and offer to search the town. Prices hold for about an hour: book soon after, or check again.
| Name | Required | Description | Default |
|---|---|---|---|
| to | Yes | Check-out date, YYYY-MM-DD | |
| from | Yes | Check-in date, YYYY-MM-DD | |
| property | Yes | The hotel: a Vuelo hotel link, an offerId from a Vuelo search, a Vuelo property_id (VHP_…) or a hotel id from a Vuelo search. | |
| travellers | Yes | Number of adults |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the read-only, idempotent, open-world safety profile, so the bar is lower, yet the description still adds substantive behaviour: results render "in the Vuelo card," an empty result means the hotel has no inventory or is unsellable, and prices hold only about an hour. That price-freshness caveat is the kind of contextual trait annotations 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?
The scope constraint is front-loaded in the first sentence and the operational caveats come last, which is the right ordering. It runs dense and slightly crowded, repeating the four accepted property reference forms that the schema already lists, so a small amount of text does not earn its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description still tells the agent where results surface (Vuelo card), how to read an empty response, and how long prices are valid. For a single-hotel availability lookup that is everything needed to call it and act on the 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 coverage is 100%, so the baseline is 3, and the description largely repeats the property reference types already documented verbatim in the schema field description. The date semantics (from/to) and traveller counts carry no extra explanation beyond what the schema states. Nothing is missing, but nothing is added either.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource ("Live rooms and prices") and immediately bounds the scope to "ONE hotel the traveller already has in mind... without searching the whole town," which sharply separates it from the town-wide search sibling. It never restates the name tautologically and gives the agent an unambiguous mental model.
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 trigger conditions ("when the traveller shares a Vuelo hotel link or asks about the same hotel on other dates") and an explicit fallback for the empty case ("say so, and offer to search the town"). The absence of a result is turned into a directive rather than left to inference, which is exactly the routing behaviour the agent needs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Details, terms, photos and the payment options for one Vuelo offer, repriced live.
| Name | Required | Description | Default |
|---|---|---|---|
| offerId | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, idempotent and non-destructive, so the safety profile is covered. The description still adds real value beyond them by disclosing that the offer is 'repriced live', warning the agent that returned prices are not cached or guaranteed. It says nothing about rate limits or whether a stale offerId errors out.
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-loaded with the resource and followed by the payload contents and the live-pricing trait. Nothing is wasted and nothing important is buried.
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 with no output schema, describing the returned contents and the live repricing is largely sufficient. The gap is the offerId's origin and validity, which is the only thing an agent could realistically get wrong when calling this 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 0% and the description never mentions offerId at all — not its format, not that it comes from a prior search result, not what happens if it is invalid. With a single required parameter fully undocumented in both structured data and prose, the description fails to compensate.
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-and-resource pair ('Details, terms, photos and the payment options for one Vuelo offer') and even enumerates the payload, so the agent knows exactly what comes back. It does not name a sibling to contrast with, which keeps it 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 agent can infer this is the detail-fetch step before book_trip, but the description never says when to call it versus search_trips or find_my_booking, nor any prerequisite. No exclusions or alternatives are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Where a request to Vuelo's support team stands: with the team, replied (the reply is in the traveller's email), or resolved. Pass the ticket reference (SUP-...) and either the taskId of the booking in this conversation or the email the traveller gave. Use it when the traveller asks for an update. To add to a request, call contact_support again with the same booking and reason: it joins the same conversation.
| Name | Required | Description | Default |
|---|---|---|---|
| No | The email the traveller gave for the reply. | ||
| taskId | No | The booking's taskId, if it was made in this conversation. | |
| ticket | Yes | The ticket reference, SUP-... |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds genuinely useful context beyond them: the reply itself lives in the traveller's email, not in the tool result. It does not say what happens if the ticket reference is unknown or expired, which is the remaining behavioral gap for a lookup tool.
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 sentences, front-loaded with what the tool reports, then how to call it, then the alternative. No sentence restates the name or the title, and 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 carries the return values and does so by enumerating the three possible states, so the agent knows what a result means. Combined with the lookup inputs, an agent has enough to call this correctly 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 baseline is 3, but the description earns above that by stating the either/or coupling between taskId and email that the schema does not express (only ticket is marked required). It doesn't explain what to do when neither is available.
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 the specific resource (a Vuelo support request) and enumerates the exact states it returns: with the team, replied, resolved. This is clearly distinguishable from contact_support, which it names as the way to add to a request, so an agent can route between the two 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 trigger ('Use it when the traveller asks for an update') and explicitly redirects the add-to-request case to contact_support with the matching booking and reason. Both when-to-use and the alternative are stated rather than inferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
When the traveller says the secure link has not arrived, or asks for another: Vuelo texts it again, to the same number. The first time it resends the same link; after that, once it has been opened, or once it has expired, Vuelo cancels it and texts a fresh one, and only the newest works. Never pass the link on in the chat yourself. At most three links a booking.
| Name | Required | Description | Default |
|---|---|---|---|
| taskId | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only say it is not read-only and not idempotent; the description explains the actual mechanics: first resend reuses the same link, after opening or expiry the old link is cancelled and a fresh one is issued, and only the newest works. It also discloses a rate limit (three links per booking) and the destination constraint (same number), none of which is in 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?
Front-loaded with the trigger, then the escalation rule, then the hard constraint. Four sentences, each carrying information, though 'Vuelo texts it again, to the same number' partially restates the title and could be tighter.
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 action tool with no output schema, the description covers trigger, side effects on prior links, and limits. The remaining gap is the meaning of taskId and what the caller sees on success, which the absence of an output schema leaves 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?
The single required parameter taskId has 0% schema description coverage and the description never mentions it, so the agent must guess whether it is a booking id, task id, or traveller id. The phrase 'a booking' hints the identifier is booking-scoped, but that is inference rather than documentation.
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 (texts the Vuelo secure link again) plus the exact scope (same number as before). An agent can immediately distinguish this from send_to_payer, contact_support, or any link-generation step.
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 conditions (traveller reports the link never arrived, or asks for another) and an explicit prohibition that steers away from an alternative action (never paste the link into chat yourself). The three-links-per-booking cap further bounds when this can be used.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find hotels, flights and flight-and-hotel packages on Vuelo for a destination, dates and number of travellers, within a budget. The results appear in the Vuelo card, where the traveller compares and books them: do not follow up with a question asking which one they want. Hotels are live; pass origin and destinationAirport (IATA codes) to include flights and packages. Flight fares are live and ticketed at purchase. Pass cabin for premium economy, business or first. Returns prices, photos and the payment options Vuelo offers for each trip. Show payment options exactly as returned and always show the full price. Call it ONCE for what the traveller asked: every call shows another Vuelo card in the chat. Do not run extra searches for other towns, dates or budgets on your own; if the request is broad ("somewhere near London"), pick the best single destination or ask the traveller, and search again only when they ask for something different.
| Name | Required | Description | Default |
|---|---|---|---|
| to | Yes | Check-out or return date, YYYY-MM-DD. For a one-way flight, give the same date as from. | |
| from | Yes | Check-in date, YYYY-MM-DD | |
| only | No | What the traveller asked for. Set "flights" whenever they ask for flights and not a hotel (for example "find me flights to Nice"), "stays" for a hotel only, "packages" for flight and hotel together. Only leave it out when they want to see everything. Never add hotels to a flights request. | |
| cabin | No | Which cabin to price flights in, when the traveller asks for one ("business class", "premium economy", "first"). Economy when not said. Only affects flights and packages. | |
| hotel | No | The hotel, when the traveller names one ("the Pulitzer", "The Savoy"): its name only, with the town in destination. Vuelo finds it by name and lists it first, with other hotels in the town after it. Never use minStars or a budget to stand in for a named hotel. | |
| budget | No | Maximum total in pounds | |
| mobile | No | The traveller's mobile number (any country; international format such as +1 415 555 2671 outside the UK), whenever you already know it from this conversation or about the user. Always pass it if you have it: when they tap Book in the Vuelo card, Vuelo texts the secure link straight to it, so they type nothing. Vuelo keeps it for this conversation only and never shows it in the chat. Do not ask for it just to search. | |
| origin | No | Where they fly from, to include live flights and packages: an airport code (LHR) or, when the traveller names a city, the city (London, or LON), which searches every airport there (Heathrow, Gatwick, Stansted, Luton, City). Pass the city unless they named one airport. Ask where they are flying from if they want flights. | |
| minStars | No | Minimum hotel star rating, when the traveller asks for one (for example 5 for "5-star"). | |
| traveller | No | The person booking, whenever you know them from this conversation or about the user: full name as on their ID, email, date of birth (YYYY-MM-DD) and home postcode. Vuelo keeps them for this conversation, so when the traveller taps Book in the card they have nothing to type. Never guess any of it. | |
| passengers | No | Pass this whenever you know it: the results page and checkout then need nothing typed. Who is flying, if the traveller has already told you or you know it: full names as on the passport, and dates of birth if you have them. Vuelo fills these into the booking form so they are not asked for again. Names alone still help. This is who is flying; travellers above is how many. | |
| travellers | Yes | Number of travellers | |
| destination | Yes | Town or city, with its country when the name is shared or could be ambiguous: "Lisbon", "Zurich, Switzerland", "Cambridge, UK". A region (the Cotswolds) cannot be searched: use one town in it. | |
| refundableOnly | No | Only stays with a refundable rate, when the traveller asks for refundable or free cancellation. Flights are ticketed at booking, so none are refundable. | |
| destinationAirport | No | Arrival airport for the destination, for example LIS for Lisbon; for a city with several airports (London, Paris, New York, Milan, Rome, Tokyo, Stockholm) pass the city to search them all. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well past the readOnly/idempotent annotations: it discloses that each call renders a new Vuelo card in the chat, that the traveller books from that card so no follow-up question is needed, that hotel and flight data are live and fares are ticketed at purchase, and that payment options must be shown verbatim with full prices. Missing only rate/latency or result-count behavior, which is minor for a search.
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, then constraints in a sensible order. It is dense and mostly earns its length, though the 'do not follow up with a question' and 'call it ONCE / another Vuelo card' instructions overlap slightly and the payment-display rules are repeated in spirit.
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 open-world search with nested objects and no output schema, the description covers what comes back (prices, photos, payment options), where it appears (the card), freshness of data, and the behavioural contract around repeat calls. Nothing an agent needs 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 schema already documents all 15 parameters in detail and the baseline applies. The description adds a little genuine meaning — the origin/destinationAirport pairing that unlocks flights and packages, and that cabin only affects flights and packages — but it does not explain most parameters beyond what the schema 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 (find) plus the three resource types (hotels, flights, packages) and the scoping inputs (destination, dates, travellers, budget). It is clearly separable from siblings like get_hotel_availability (availability lookup for one property) and book_trip (the conversion step that follows the card).
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?
Explicit when-to-use and when-not: call it ONCE for what the traveller asked, do not run extra searches for other towns/dates/budgets, search again only when they ask for something different, and pick one destination or ask when the request is broad. It also gives the conditional rule for including flights (pass origin and destinationAirport) versus stays only.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
After a booking has started, when the traveller says someone else is paying (a friend, a partner, a parent, their company); if you know before booking, pass payer to book_trip instead. Vuelo sends that person a secure link of their own, by text, email or both. Only when the traveller asks, with the name and the mobile or email they give you: never guess or reuse a number, and confirm it with the traveller first. The payer sees the trip, the price and who asked, never the traveller's own details, and pays in full from their own Vuelo account (no payment plan). The traveller's own link stops working, so the trip cannot be paid twice; the traveller still gets the booking confirmation. The link lasts 24 hours and the price is checked when they pay. Never pass the link on in the chat yourself.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | The name of the person paying, as the traveller gave it. | |
| No | Their email, to email the link. | ||
| mobile | No | Their mobile, to text the link. | |
| taskId | Yes | The taskId book_trip returned. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well past the annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false) by disclosing what the payer sees, that the traveller's own link is invalidated to prevent double payment, that the link expires in 24 hours, and that the price is re-checked at payment. The main gap is that it never explains what the tool returns to the agent on success or failure, though with no output schema that is a minor omission for a fire-and-forget notification.
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 trigger is front-loaded in the first clause and nearly every sentence carries operational value — expiry, invalidation, payer visibility, no payment plan. It is dense and slightly run-on, packing several distinct rules into single sentences, but there is no filler to cut.
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 four flat parameters, no enums, and no output schema, the description covers everything an agent needs: trigger, alternative routing, contact-detail sourcing rules, expiry, price re-check, and what the traveller and payer each receive. Nothing material is left to 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 already 100%, so the baseline is 3; the description adds real semantics on top by constraining the contact fields (text, email, or both) and imposing a social-rule the schema cannot express: never guess or reuse a number and confirm it with the traveller first. It does not clarify taskId beyond the schema's own note.
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 — send a secure pay link to a third-party payer — and anchors it to a concrete trigger (after a booking has started). It actively distinguishes itself from the sibling book_trip by telling the agent to use book_trip's payer parameter instead when the payer is known before booking.
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?
Explicit when-to-use (traveller says someone else is paying), when-not (before booking → use book_trip with payer), and a hard precondition (only when the traveller asks, with the contact details they give). It even forbids guessing or reusing a number and requires confirming with the traveller first.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Correct who is travelling on a booking the traveller has not paid for yet: a passenger's name or date of birth (names exactly as on the passport, dates YYYY-MM-DD). Give only what changes, by position: { passenger: 2, name: "Sophie Hougham", dateOfBirth: "1990-04-12" }. What you leave out stays as it was. The link already sent opens with the new names; nothing is resent. Refused once the traveller has paid: names on a ticket are changed with the airline through Vuelo support.
| Name | Required | Description | Default |
|---|---|---|---|
| taskId | Yes | The taskId book_trip returned. | |
| travellers | No | ||
| leadTraveller | No | The booking traveller's email, date of birth and home postcode, town and county, to fill in their Vuelo account on the pay page. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare a non-readonly, idempotent, non-destructive write; the description goes well beyond that by explaining partial-update semantics ("what you leave out stays as it was"), the external side effect (the existing link picks up the new names, nothing is resent), and the failure condition once payment has occurred. No contradiction with the declared idempotent/destructive hints — correcting a name is naturally idempotent, which matches.
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 tight paragraph, front-loaded with the eligibility condition before the mechanics, and every sentence carries a distinct obligation. The inline example substitutes for several sentences of explanation.
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 still covers outcome behavior (the link reopens with new names) but never says what the call itself returns — e.g. an updated task/booking object — which an agent may need for follow-up steps. Otherwise complete for a mutation on a nested-object 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?
Adds real meaning beyond the 67%-covered schema: a concrete positional payload example, the passport-name formatting rule, and the "give only what changes" contract that makes the array partial rather than a full replacement. It does not discuss leadTraveller at all, so a meaningful third of the parameter surface is left entirely to the schema description.
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?
Specific verb and resource ("correct who is travelling on a booking") plus an explicit precondition ("a booking the traveller has not paid for yet"). It names the fields it touches (name, date of birth), which separates it cleanly from siblings like book_trip, change_package_flight, and resend_link.
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 both directions of the routing decision: use this before payment is made, and it is "refused once the traveller has paid" — at which point names are changed with the airline via Vuelo support. It also pre-empts the obvious wrong sibling by noting the link already sent reflects the change and nothing is resent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
book_tripcancel_bookingchange_package_flightchange_payment_optioncontact_supportfind_my_bookingget_booking_progressget_booking_statusget_hotel_availabilityget_offerget_support_ticketresend_linksearch_tripssend_to_payerupdate_travellersSearch ~300 airlines and book flights with a checkout link. OAuth sign-in by email code.
Live flight prices and working booking links for AI agents and travel apps.
Search and book flights and hotels: hundreds of airlines, plus bookable hotel rates.
Search hotels worldwide, compare live room rates, and create booking payment links.
Add one secure layer between your agents and this server.
