Advocate

Create Booking Payment Link

create_booking_payment_link

Idempotent

For a reservation that reserve_slot returned with payment.required = true: returns the MPP payment link, the amount charged now, and the balance due at the visit. The agent pays it itself (HTTP 402 challenge, then the person's wallet credential); no code is sent to the customer for a paid booking. A booking that takes no payment through Advocate answers payment_required false with a detail, not an error, and, if not confirmed yet, is confirmed with confirm_booking and the customer's code.

Input Schema

Name	Required	Description	Default
`slug`	Yes	Business slug identifier
`reservation_id`	Yes	The reservation_id reserve_slot returned with payment.required = true

Output Schema

Name	Required	Description
`kind`	No
`detail`	No	Present when payment_required is false: what to do instead, since no payment is taken through Advocate
`currency`	No
`expires_at`	No	Unix seconds after which the reservation lapses unpaid
`amount_cents`	No	Minor units charged now
`due_at_visit`	No
`instructions`	No
`payment_link`	No	POST here (no body) to receive the HTTP 402 MPP challenge
`reservation_id`	No	Present when payment_required is false
`payment_required`	Yes	true: payment for this booking is taken through Advocate; it may already be authorized or in flight, so ask for a new approval only if the pay route answers 402. Comes with payment_link, amount_cents, currency, kind, balance_due_cents, due_at_visit, expires_at and instructions. false: no payment is taken through Advocate for this booking, which does not mean the service is free. Comes with reservation_id and detail only.
`balance_due_cents`	No	Minor units due at the visit

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedNov 7, 2026

addedOutput schema / properties / detail

Added value: +{
+  "description": "Present when payment_required is false: what to do instead, since no payment is taken through Advocate",
+  "type": "string"
+}

addedOutput schema / properties / payment_required

Added value: +{
+  "description": "true: payment for this booking is taken through Advocate; it may already be authorized or in flight, so ask for a new approval only if the pay route answers 402. Comes with payment_link, amount_cents, currency, kind, balance_due_cents, due_at_visit, expires_at and instructions. false: no payment is taken through Advocate for this booking, which does not mean the service is free. Comes with reservation_id and detail only.",
+  "type": "boolean"
+}

addedOutput schema / properties / reservation_id

Added value: +{
+  "description": "Present when payment_required is false",
+  "type": "string"
+}

changedOutput schema / required

Previous value: -[
-  "payment_link",
-  "amount_cents",
-  "currency",
-  "kind",
-  "balance_due_cents",
-  "due_at_visit",
-  "expires_at",
-  "instructions"
-]New value: +[
+  "payment_required"
+]

AddedSep 23, 2026

TDQS

A4.2/5.0

Behavior3/5

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

Annotations already declare readOnlyHint=false, idempotentHint=true, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: the agent itself pays via an HTTP 402 challenge using the person's wallet credential, and no code is sent to the customer for a paid booking. It also clarifies that the no-payment outcome is a false flag plus detail, not an error, which is valuable failure-mode disclosure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

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

Three sentences, each carrying distinct load: the precondition and return values, the payment mechanism and the no-customer-code rule, then the non-payment branch and its alternative. The precondition is front-loaded so an agent can decide eligibility before reading further, and there is no filler.

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 names the three returned values that matter (link, amount now, balance at visit) and spells out the failure semantics of the no-payment path. Combined with the 100%-covered input schema and annotations, an agent has everything needed to call this correctly inside the booking flow.

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 description coverage is 100%, so both slug and reservation_id are already documented, and the baseline is 3. The description does reinforce the critical provenance constraint on reservation_id (it must be the one reserve_slot returned with payment.required = true), but that is essentially a restatement of the schema's own parameter description rather than new syntax or format guidance.

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

Purpose4/5

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

The description states a specific outcome for a specific precondition: given a reservation that reserve_slot marked payment.required = true, it returns the MPP payment link, the amount due now, and the remaining balance. It names reserve_slot and confirm_booking, so an agent can place it in the booking flow. It does not, however, contrast itself with the sibling get_payment_handoff_url, leaving some ambiguity about which link-generation tool applies.

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?

The gating condition is stated up front ('For a reservation that reserve_slot returned with payment.required = true'), and the negative case is fully routed: a no-payment booking answers payment_required false rather than erroring, and an unconfirmed booking should go through confirm_booking with the customer's code. That is explicit when-to-use, when-not, and which alternative to call.

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

All Advocate 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?