ATA Travel

create_provisional_booking

Secure a reservation or create a host-approval enquiry on behalf of a traveler. policyAcknowledged is required as an explicit boolean and must be true for financially binding flows after the exact total, payment schedule, and cancellation terms are shown; identity verification is not consent. A host-approval enquiry may pass false because payment is not due unless accepted. Also requires the traveler’s full name, email, and country (guestCountry, required for bookings; optional for quotes) plus travelerAssertion or approved internal BOOKING_HOLD agentHandoffId. If verification is needed, keep internal tool details private; tell the traveler to confirm their email and follow the code or link instructions returned by verification. If instant book is enabled and payment is ready, creates an inventory-holding provisional booking and returns payment/manual-payment next steps. If instant book is disabled or Stripe checkout is not ready, creates an enquiry hold for host approval/payment follow-up.

Input Schema

TableJSON Schema

Name	Required	Description
`notes`	No	Optional traveler comments, questions, or requests for the host. Especially useful for host-approval enquiries.
`adults`	Yes
`roomId`	Yes
`checkIn`	Yes
`checkOut`	Yes
`children`	No
`guestName`	Yes	Traveler’s full name, as supplied by the traveler.
`guestEmail`	Yes
`guestPhone`	No
`ratePlanId`	No	Rate plan ID. If omitted, the system auto-selects the default active rate plan per night, then the cheapest active auto-selectable fallback.
`guestCountry`	Yes	Required traveler country, as supplied by the traveler. Ask only if missing. Do not infer it from the property location, language, currency, or phone number. Quotes do not require country.
`priceAudience`	No
`propertyToken`	Yes
`agentHandoffId`	No	Approved ATA traveler handoff ID from start_traveler_handoff/get_traveler_handoff_status. Required for third-party agents before inventory-holding booking actions.
`displayCurrency`	No	Optional 3-letter currency for approximate traveler-facing display conversion. Native property currency remains authoritative.
`internalAgentKey`	No
`bookingAssistance`	No	Internal Little John booking attribution; requires the internal agent credential.
`selectedRoomCount`	No	For direct-booking room-count configurations, the number of rooms the traveler selected. Use defaultSelectedRoomCount from availability results.
`travelerAssertion`	No	Signed traveler email verification assertion from ATA.
`policyAcknowledged`	Yes	Explicit policy-consent state. Set true only after the traveler agrees to the exact price, payment schedule, and cancellation terms. Required before creating either an instant-book hold or a host-approval enquiry.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 3, 2026

addedInput schema / properties / bookingAssistance

Added value: +{
+  "description": "Internal Little John booking attribution; requires the internal agent credential.",
+  "enum": [
+    "AI_ASSIST"
+  ],
+  "type": "string"
+}

Changed4 schema fields changedSep 15, 2026

addedInput schema / properties / guestCountry

Added value: +{
+  "description": "Required traveler country, as supplied by the traveler. Ask only if missing. Do not infer it from the property location, language, currency, or phone number. Quotes do not require country.",
+  "maxLength": 80,
+  "minLength": 1,
+  "type": "string"
+}

addedInput schema / properties / guestName / description

Added value: +"Traveler’s full name, as supplied by the traveler."

addedInput schema / properties / guestName / minLength
```
Added value: +1
```

changedInput schema / required

Previous value: -[
-  "propertyToken",
-  "roomId",
-  "checkIn",
-  "checkOut",
-  "guestName",
-  "guestEmail",
-  "adults",
-  "policyAcknowledged"
-]New value: +[
+  "propertyToken",
+  "roomId",
+  "checkIn",
+  "checkOut",
+  "guestName",
+  "guestEmail",
+  "guestCountry",
+  "adults",
+  "policyAcknowledged"
+]

Changed2 schema fields changedAug 29, 2026

addedInput schema / properties / policyAcknowledged

Added value: +{
+  "description": "Explicit policy-consent state. Set true only after the traveler agrees to the exact price, payment schedule, and cancellation terms. Required before creating either an instant-book hold or a host-approval enquiry.",
+  "type": "boolean"
+}

changedInput schema / required

Previous value: -[
-  "propertyToken",
-  "roomId",
-  "checkIn",
-  "checkOut",
-  "guestName",
-  "guestEmail",
-  "adults"
-]New value: +[
+  "propertyToken",
+  "roomId",
+  "checkIn",
+  "checkOut",
+  "guestName",
+  "guestEmail",
+  "adults",
+  "policyAcknowledged"
+]

First observedJun 29, 2026

TDQS

A4.5/5.0

Behavior5/5

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

Annotations only supply generic mutation flags (readOnly=false, idempotent=false); the description adds substantial context beyond them: consent semantics (identity verification is not consent), auth requirements (travelerAssertion or approved agentHandoffId), privacy guidance during verification, and the two distinct side-effect paths (inventory-holding provisional booking vs enquiry hold). No contradiction with 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.

Conciseness4/5

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

Front-loaded with the core action and the consent rule, then the required identity fields, then branch behavior. It is dense but every sentence carries operational meaning; only slight redundancy with policyAcknowledged's schema description keeps it from a 5.

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

Completeness4/5

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

For a 20-parameter mutation with no output schema, the description supplies the essential consent, identity, and branch semantics and even sketches the return (payment/manual-payment next steps, or host-approval follow-up). Return-value detail and a few opaque parameters remain undocumented, but nothing critical is missing for correct invocation.

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

Parameters4/5

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

With 20 params at 50% schema coverage, the description carries part of the load: it explains policyAcknowledged's consent conditions, guestCountry's requirement/profile and that it must not be inferred, and the travelerAssertion/agentHandoffId alternatives. It leaves several params (priceAudience, displayCurrency, selectedRoomCount, bookingAssistance, internalAgentKey) to the schema, so it does not fully compensate for the coverage gap.

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

Purpose5/5

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

States a specific verb and resource with scope: secure a reservation OR create a host-approval enquiry on behalf of a traveler. The two branches (instant-book vs enquiry hold) are named, and the sibling create_quote is implicitly distinguished by the description's own handling of quotes vs bookings.

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

Usage Guidelines4/5

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

Gives explicit conditions: policyAcknowledged must be true for financially binding flows but may be false for host-approval enquiries; country is required for bookings but optional for quotes; instant book enabled vs disabled determines which hold is created. It stops short of naming create_quote as the alternative for quote-only flows, but the when-to-use logic is unusually complete.

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

All ATA Travel tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?