Skip to main content
Glama

Request a booking

request_booking

Create a booking (訂課、預約) for one open slot on behalf of the customer, after the customer has agreed to the service, time, quantity and contact details. Sends the customer's name, phone and email to the business. The result is either 'confirmed' or 'pending' (waiting for the business to confirm). Payment is at the venue, unless the business takes online payment (payment in get_business): then the status is 'awaiting_payment' with amount, currency, expires_at and payment_handlers, and the place is held until expires_at for complete_booking. Returns booking_id and a one-time status_token for get_booking_status, complete_booking, modify_booking and cancel_booking. Repeating the call for the same contact details, service and slot is rejected as a duplicate.

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": {
      "business_id": "<business_id>",
      "service_id": "<service_id>",
      "slot": "<slot>",
      "quantity": "<quantity>",
      "customer_name": "<customer_name>",
      "phone": "<phone>",
      "email": "<email>"
    },
    "name": "request_booking"
  }
}

Input Schema

NameRequiredDescriptionDefault
noteNoOptional request for the business, e.g. 'first time, please arrive early'. Do not include health or medical information.
slotYesslot value from get_availability, e.g. 2026-10-20T19:30
emailYesCustomer's email, for the business to reach them
phoneYesCustomer's mobile phone, for the business to reach them
quantityYesNumber of people or places
service_idYesservice_id from get_business
business_idYesbusiness_id from search_businesses
customer_nameYesName the business should use
idempotency_keyNoOptional key (8–64 letters, digits, _ . : -) that makes retries safe: the same key with the same parameters returns the original result

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.4/5.0
Behavior5/5

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

Goes well beyond the annotations: discloses the possible outcomes (confirmed / pending / awaiting_payment), that payment is at the venue unless the business takes online payment, that the place is held until expires_at for complete_booking, and that duplicate requests for the same contact/service/slot are rejected. It also names the returned booking_id and one-time status_token and which sibling tools consume it.

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-loads the core action and precondition, then layers payment and return-value details. It is information-dense and largely justified, though the long run-on structure mixing outcome states, payment routing and token usage is slightly harder to scan than a short bulleted flow.

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?

For a 9-parameter mutation with no output schema, the description covers preconditions, side effects, duplicate rejection, all three result states, payment handling, and the returned identifiers plus their downstream tools. An agent has everything needed to call it correctly and interpret the result.

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

Parameters3/5

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

Schema coverage is 100%, so the schema already documents each parameter including where slot, service_id and business_id come from. The description adds the duplicate-detection rule keyed on contact details, service and slot, but adds little else about parameter semantics beyond what structured fields provide, so the baseline 3 applies.

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 ('Create a booking (訂課、預約)') scoped to one open slot on behalf of the customer, and immediately clarifies the precondition that the customer already agreed to the details. This clearly distinguishes it from sibling mutations like modify_booking and cancel_booking.

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 clear context for when to call it (customer has agreed to service, time, quantity, contact details) and points to get_business for payment capability. It does not explicitly say when NOT to use it or name the alternative for changing an existing booking, so it stops short of full routing guidance.

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.