Skip to main content
Glama

get_booking_status

Idempotent

Check the current status of a booking.

If the booking is not yet marked paid, this call may poll the operator's
payment processor and finalize and record a payment that has already
settled. It never initiates a payment or cancellation.

Returns the raw persisted `status` value (`pending`, `awaiting_payment`,
`paid`, `cancelled`, `expired`), `payment_status`, and a convenience
`paid` boolean. Legacy compatibility rows may still report
`awaiting_payment`; present that to end users as traveler payment pending
rather than as a new canonical state name.

Polling cadence after presenting a payment link:

1. **First poll** — call with ``wait_seconds=60``. The server returns
   sub-second once payment lands, or after 60s if still pending.
2. **Active-wait loop** — if still ``paid: false``, loop with another
   ``wait_seconds=60`` call. Realistic payment latency is p95 ~3 min,
   p99 ~8 min; **cap the loop at ~10 iterations (10 min)** of active
   waiting.
3. **Pivot at 10 min** — tell the tourist "I'll let you know the
   moment payment confirms, feel free to ask me anything else in the
   meantime" and stop the active-wait loop. The payment window remains
   open for 30 minutes from link creation.
4. **On resumption** — if the tourist replies later, do a single
   non-blocking peek (``wait_seconds=0``) before continuing. That
   surfaces a payment that landed while you weren't watching.
5. **Absolute ceiling** — at 30 minutes the payment window closes. A
   later status check reports expiry and tells the guest to book again.

Do not require the user to say "I paid" — check proactively. Requires
OAuth2 authentication.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "booking_reference": "<booking_reference>"
    },
    "name": "get_booking_status"
  }
}

Input Schema

NameRequiredDescriptionDefault
wait_secondsNoHow long the server should long-poll for the booking to reach a terminal state (``paid``, ``cancelled``, ``expired``) before returning. Returns immediately if the booking is already terminal. Default 0 — single-shot read, model picks its own cadence. Set ``wait_seconds=60`` after presenting a payment link so the tool returns the moment the tourist completes payment, instead of forcing a sleep + re-call. Cap 90 to stay safely under the ~300s client timeout.
booking_referenceYesBooking reference code returned by create_booking.

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.6/5.0
Behavior4/5

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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the mutation signal is present, but the description goes further by explaining why it is not read-only (it may poll the operator's payment processor and finalize a settled payment), that it cannot initiate payment or cancellation, that it requires OAuth2, and realistic payment latencies (p95 ~3 min, p99 ~8 min). What it does not cover is failure behavior for an invalid or unknown booking_reference, which keeps it below 5.

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 surprising behavior (it may finalize a payment) before the procedural detail, and the numbered polling steps are easy to follow. It is long for a status check, and the legacy awaiting_payment presentation note plus the return-value enumeration overlap with what the output schema already supplies, so it is not maximally tight.

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

Completeness5/5

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

An output schema exists, yet the description still flags the one non-obvious presentation rule (legacy awaiting_payment should be shown as traveler payment pending), and it covers authentication, side effects, timing expectations, and the full polling lifecycle. Nothing an agent needs to call this correctly and interpret the result is missing.

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?

Schema coverage is 100%, so the baseline is 3, but the description adds genuinely operational meaning for wait_seconds by prescribing concrete values (60 for post-link polling, 0 for a non-blocking peek) and explaining why they matter, which is more than the schema's generic range description conveys. booking_reference is left to the schema, appropriately.

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 ('Check the current status of a booking') and immediately discloses the non-obvious scope: this read may also finalize and record an already-settled payment. It also enumerates the exact status values returned, which lets an agent distinguish it from create_booking, cancel_booking and get_payment_link 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.

Usage Guidelines5/5

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

Gives an explicit when-to-use protocol keyed to wait_seconds (first poll at 60, active-wait loop capped at ~10 iterations, pivot language at 10 min, single non-blocking peek on resumption), plus the 30-minute hard ceiling and the instruction not to wait for the user to volunteer 'I paid'. It also bounds what the tool will not do ('never initiates a payment or cancellation'), which routes cancellation intent elsewhere.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources