AdvocateMCP

Reserve Time Slot

reserve_slot

DestructiveIdempotent

Reserve a time slot on an active configured calendar. Returns a pending_offer reservation and sends a 6-digit confirmation code to the customer's email or phone. The reservation expires in 15 minutes if not confirmed. Idempotent: re-using the same idempotency_key returns the original reservation without resending the code. At a business that takes a deposit for agent bookings, pass the offer_id from get_quote (without it the answer is quote_required); no code is sent and the result's payment block carries the amount to pay instead.

Input Schema

TableJSON Schema

Name	Required	Description
`slug`	Yes	Business slug identifier
`agent_id`	No	Optional agent identifier
`offer_id`	No	Optional id of a signed get_quote offer to redeem against this reservation. Omit for a business with no exact-priced service — authentication is a capability upgrade here, never a toll.
`window_end`	Yes	Slot end (Unix seconds, an absolute instant) — the matching get_availability slot's `end`; see window_start.
`window_start`	Yes	Slot start (Unix seconds, an absolute instant). Take it from a get_availability slot: that response carries the business's `timezone`, so request a wide availability window there and filter the returned slots locally rather than guessing the zone.
`idempotency_key`	Yes	Unique key for idempotent reservation
`customer_contact`	Yes	How to reach the customer. MUST include at least one of email or phone — the confirmation code is delivered there, and a hold nobody can confirm is unreachable from both sides. Email is used when both are present.

Output Schema

TableJSON Schema

Name	Required	Description
`status`	Yes	Reservation state — 'pending_offer' on a fresh hold; a replay returns the existing row's state
`payment`	No	Always present. required:false — confirm with the code (confirmation.method 'otp'). required:true — the customer pays amount_cents (currency) to confirm; balance_due_cents is paid at the visit.
`expires_at`	Yes	ISO-8601. When this hold lapses if it is not confirmed (by code, or by payment when payment.required)
`confirmation`	Yes
`reservation_id`	Yes
`booking_details`	No	For configured calendars: present these fixed booking details to the customer before confirming their code. No owner approval is required.
`idempotent_replay`	No	Present and true when this idempotency_key already had a reservation; no new code was sent

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedSep 23, 2026

changedOutput schema / properties / confirmation / properties / method / description

Previous value: -"Always 'otp' today"New value: +"'otp': a 6-digit code was sent to the customer. 'payment': no code — this booking is confirmed by paying the deposit in `payment`"

changedOutput schema / properties / expires_at / description

Previous value: -"ISO-8601. When this hold lapses if the code is not confirmed"New value: +"ISO-8601. When this hold lapses if it is not confirmed (by code, or by payment when payment.required)"

addedOutput schema / properties / payment

Added value: +{
+  "additionalProperties": false,
+  "description": "Always present. required:false — confirm with the code (confirmation.method 'otp'). required:true — the customer pays amount_cents (currency) to confirm; balance_due_cents is paid at the visit.",
+  "properties": {
+    "amount_cents": {
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "balance_due_cents": {
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "currency": {
+      "type": "string"
+    },
+    "kind": {
+      "enum": [
+        "deposit",
+        "full"
+      ],
+      "type": "string"
+    },
+    "required": {
+      "type": "boolean"
+    }
+  },
+  "required": [
+    "required"
+  ],
+  "type": "object"
+}

Changed1 schema field changedSep 5, 2026

addedOutput schema / properties / booking_details

Added value: +{
+  "additionalProperties": false,
+  "description": "For configured calendars: present these fixed booking details to the customer before confirming their code. No owner approval is required.",
+  "properties": {
+    "business_name": {
+      "type": "string"
+    },
+    "calendar_name": {
+      "type": "string"
+    },
+    "end": {
+      "type": "string"
+    },
+    "reference": {
+      "type": "string"
+    },
+    "start": {
+      "type": "string"
+    },
+    "timezone": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "business_name",
+    "timezone",
+    "start",
+    "end",
+    "calendar_name",
+    "reference"
+  ],
+  "type": "object"
+}

Changed3 schema fields changedSep 4, 2026

addedInput schema / properties / customer_contact / anyOf

Added value: +[
+  {
+    "required": [
+      "email"
+    ]
+  },
+  {
+    "required": [
+      "phone"
+    ]
+  }
+]

changedInput schema / properties / window_end / description

Previous value: -"Slot end (Unix seconds)"New value: +"Slot end (Unix seconds, an absolute instant) — the matching get_availability slot's `end`; see window_start."

changedInput schema / properties / window_start / description

Previous value: -"Slot start (Unix seconds)"New value: +"Slot start (Unix seconds, an absolute instant). Take it from a get_availability slot: that response carries the business's `timezone`, so request a wide availability window there and filter the returned slots locally rather than guessing the zone."

Changed1 schema field changedAug 25, 2026

changedInput schema / properties / customer_contact / properties / phone / description

Previous value: -"SMS fallback for the confirmation code when no email is given. Give it in E.164 form, e.g. +15125551234; a bare national number is accepted and read as US. If it cannot be resolved to a real number and no email was supplied, the call returns invalid_phone rather than holding a slot nobody can confirm."New value: +"SMS fallback for the confirmation code when no email is given. Any common way of writing a number is accepted and reformatted for you: (512) 317-1992, 512-317-1992 and 5123171992 all work, and a bare national number is read as US. Only input that cannot be read as a number at all is refused, and then only when no email was supplied, since a hold nobody can confirm is worse than a refused call."

Changed1 schema field changedAug 25, 2026

changedInput schema / properties / customer_contact / properties / phone / description

Previous value: -"SMS fallback for the confirmation code when no email is given"New value: +"SMS fallback for the confirmation code when no email is given. Give it in E.164 form, e.g. +15125551234; a bare national number is accepted and read as US. If it cannot be resolved to a real number and no email was supplied, the call returns invalid_phone rather than holding a slot nobody can confirm."

Changed1 schema field changedAug 21, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "confirmation": {
+      "additionalProperties": false,
+      "properties": {
+        "channel": {
+          "description": "Where the code went: 'email', 'sms', or 'none' if delivery was unavailable",
+          "type": "string"
+        },
+        "delivered": {
+          "description": "False means the hold exists but no code reached the customer — the booking cannot be confirmed until one does",
+          "type": "boolean"
+        },
+        "method": {
+          "description": "Always 'otp' today",
+          "type": "string"
+        }
+      },
+      "required": [
+        "method",
+        "channel",
+        "delivered"
+      ],
+      "type": "object"
+    },
+    "expires_at": {
+      "description": "ISO-8601. When this hold lapses if the code is not confirmed",
+      "type": "string"
+    },
+    "idempotent_replay": {
+      "description": "Present and true when this idempotency_key already had a reservation; no new code was sent",
+      "type": "boolean"
+    },
+    "reservation_id": {
+      "format": "uuid",
+      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
+      "type": "string"
+    },
+    "status": {
+      "description": "Reservation state — 'pending_offer' on a fresh hold; a replay returns the existing row's state",
+      "type": "string"
+    }
+  },
+  "required": [
+    "reservation_id",
+    "status",
+    "expires_at",
+    "confirmation"
+  ],
+  "type": "object"
+}

Changed4 schema fields changedAug 21, 2026

changedInput schema / properties / customer_contact / description

Previous value: -"Customer contact information"New value: +"How to reach the customer. MUST include at least one of email or phone — the confirmation code is delivered there, and a hold nobody can confirm is unreachable from both sides. Email is used when both are present."

addedInput schema / properties / customer_contact / properties / email / description

Added value: +"Where the 6-digit confirmation code is sent, preferred over phone"

addedInput schema / properties / customer_contact / properties / name / description
```
Added value: +"Customer's name, if known"
```
addedInput schema / properties / customer_contact / properties / phone / description
```
Added value: +"SMS fallback for the confirmation code when no email is given"
```

Changed1 schema field changedAug 19, 2026

addedInput schema / properties / offer_id

Added value: +{
+  "description": "Optional id of a signed get_quote offer to redeem against this reservation. Omit for a business with no exact-priced service — authentication is a capability upgrade here, never a toll.",
+  "format": "uuid",
+  "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
+  "type": "string"
+}

Changed2 schema fields changedJul 17, 2026
- addedInput schema / properties / customer_contact / properties / email / format
```
Added value: +"email"
```
- addedInput schema / properties / customer_contact / properties / email / pattern
```
Added value: +"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
```
Changed10 schema fields changedJul 16, 2026
- removedInput schema / additionalProperties
```
Removed value: -false
```
- addedInput schema / properties / agent_id / description
```
Added value: +"Optional agent identifier"
```
- removedInput schema / properties / customer_contact / additionalProperties
```
Removed value: -false
```
- addedInput schema / properties / customer_contact / description
```
Added value: +"Customer contact information"
```
- addedInput schema / properties / idempotency_key / description
```
Added value: +"Unique key for idempotent reservation"
```
- addedInput schema / properties / slug / description
```
Added value: +"Business slug identifier"
```
- addedInput schema / properties / window_end / description
```
Added value: +"Slot end (Unix seconds)"
```
- addedInput schema / properties / window_end / maximum
```
Added value: +9007199254740991
```
- addedInput schema / properties / window_start / description
```
Added value: +"Slot start (Unix seconds)"
```
- addedInput schema / properties / window_start / maximum
```
Added value: +9007199254740991
```
Changed10 schema fields changedJul 12, 2026
- addedInput schema / additionalProperties
```
Added value: +false
```
- removedInput schema / properties / agent_id / description
```
Removed value: -"Optional agent identifier"
```
- addedInput schema / properties / customer_contact / additionalProperties
```
Added value: +false
```
- removedInput schema / properties / customer_contact / description
```
Removed value: -"Customer contact information"
```
- removedInput schema / properties / idempotency_key / description
```
Removed value: -"Unique key for idempotent reservation"
```
- removedInput schema / properties / slug / description
```
Removed value: -"Business slug identifier"
```
- removedInput schema / properties / window_end / description
```
Removed value: -"Slot end (Unix seconds)"
```
- removedInput schema / properties / window_end / maximum
```
Removed value: -9007199254740991
```
- removedInput schema / properties / window_start / description
```
Removed value: -"Slot start (Unix seconds)"
```
- removedInput schema / properties / window_start / maximum
```
Removed value: -9007199254740991
```
Changed10 schema fields changedJul 12, 2026
- removedInput schema / additionalProperties
```
Removed value: -false
```
- addedInput schema / properties / agent_id / description
```
Added value: +"Optional agent identifier"
```
- removedInput schema / properties / customer_contact / additionalProperties
```
Removed value: -false
```
- addedInput schema / properties / customer_contact / description
```
Added value: +"Customer contact information"
```
- addedInput schema / properties / idempotency_key / description
```
Added value: +"Unique key for idempotent reservation"
```
- addedInput schema / properties / slug / description
```
Added value: +"Business slug identifier"
```
- addedInput schema / properties / window_end / description
```
Added value: +"Slot end (Unix seconds)"
```
- addedInput schema / properties / window_end / maximum
```
Added value: +9007199254740991
```
- addedInput schema / properties / window_start / description
```
Added value: +"Slot start (Unix seconds)"
```
- addedInput schema / properties / window_start / maximum
```
Added value: +9007199254740991
```
First observedMay 5, 2026

TDQS

A4.7/5.0

Behavior5/5

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

The description goes well beyond annotations by disclosing the 15-minute expiry, the confirmation code delivery mechanism, idempotent re-use behavior, and the deposit edge case where no code is sent and payment amount appears in the result. Annotations already flag idempotency and write intent, but the description adds operational detail that materially affects agent behavior.

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?

The description is dense but every sentence earns its place: main purpose, return value, code delivery, expiry, idempotency, and the deposit exception. It is front-loaded with the core action and progressively adds edge cases. No filler or repetition of schema text.

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 tool with 7 parameters, nested objects, and an output schema, the description covers all critical operational aspects: what it does, how to handle idempotency, deposit requirements, and contact preferences. It does not need to describe return values since an output schema exists. Nothing an agent needs to call it correctly 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 each parameter is already documented. The description adds cross-tool meaning by explaining how offer_id ties to get_quote and the consequence of omitting it (quote_required). It also clarifies the customer_contact requirement (must include email or phone) beyond the schema's structural requirement, which is useful. This exceeds the baseline for high schema coverage.

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?

The description states a specific verb ('Reserve'), a clear resource ('a time slot on an active configured calendar'), and distinguishes it from siblings by mentioning it returns a pending_offer reservation and sends a confirmation code. It clearly differentiates from get_availability (listing) and confirm_booking (confirming).

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?

The description gives clear context: it is the reservation step, and it explicitly addresses the deposit scenario by instructing to pass offer_id from get_quote and warning about the quote_required result when omitted. It does not explicitly name alternatives like confirm_booking, but the flow is unambiguous from the sibling list and the description's own details.

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

All AdvocateMCP 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.