Skip to main content
Glama

Pay for a booking

complete_booking
Idempotent

Pay for a booking (付款) whose status is awaiting_payment, with a payment credential the customer approved for the booking's amount and currency. payment.handler_id must come from the booking's payment_handlers ("stripe_payments"), and credential is {type: "stripe_payment_token", token: "spt_…"}: a Stripe shared payment token issued to the handler's business_profile. Charges the customer once (repeating the call does not charge twice). Returns the booking (confirmed, or pending if the business confirms it) and the payment result; if payment.status is requires_action, open payment.redirect_url for the customer and call again with the same credential.

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>",
      "booking_id": "<booking_id>",
      "status_token": "<status_token>",
      "payment": "<payment>"
    },
    "name": "complete_booking"
  }
}

Input Schema

NameRequiredDescriptionDefault
paymentYesPayment credential for this booking
booking_idYesbooking_id returned by request_booking
business_idYesbusiness_id from search_businesses
status_tokenYesstatus_token returned once by request_booking
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.6/5.0
Behavior5/5

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

Goes well past the annotations: it discloses that the customer is charged once and that repeating the call does not double-charge, describes both possible terminal outcomes (confirmed vs. pending if the business confirms it), and gives a concrete recovery path when payment.status is requires_action (open redirect_url, re-call with the same credential). This is real behavioral context for a money-moving mutation.

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 purpose then narrowing into payment mechanics and error handling, with no filler sentences. It is dense with nested parentheses and inline JSON that make it slightly harder to scan than an ideal definition, but nothing is wasted.

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?

Absent an output schema, the description still tells the agent what comes back (the booking with its status plus the payment result) and how to handle the non-terminal requires_action state. For a nested four-required-parameter payment tool, that closes the loop an agent needs to call and recover correctly.

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; the description earns a step up by explaining where handler_id comes from (the booking's payment_handlers, e.g. stripe_payments) and spelling out the credential shape (type stripe_payment_token, token spt_… issued to the handler's business_profile). It says nothing about status_token or idempotency_key, but the schema already covers those.

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?

Opens with a specific verb+resource ("Pay for a booking") and immediately constrains it with the precondition status=awaiting_payment, which makes it unmistakable against siblings like request_booking or cancel_booking. An agent knows exactly which operation this is 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 Guidelines4/5

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

It states the required precondition (status awaiting_payment), the prerequisite that the credential be one the customer approved for the booking's amount and currency, and what to do on requires_action. It does not name a fallback sibling (e.g., request_booking or get_booking_status) for when the precondition fails, so the alternatives routing is implied rather than explicit.

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.