Skip to main content
Glama
Sign In

Samuelz Chauffeur Booking

by com.samuelz.platform-api
OverviewDiscussionsAdmin

Review cancellation of this booking

prepare_booking_cancellation
Read-onlyIdempotent

Use this when the customer wants to review cancellation of the OAuth-selected existing booking. Do not use for a ride amendment (use prepare_booking_change instead). For its recorded state use get_booking_status; for its timeline use get_booking_history. bookingKey must match the selection. Create onceKey once for this booking/cancellation intent and retain it on unchanged retries; never reuse an amendment key. consent_required returns a private consentUrl carrying the selection and intent; open it in the original signed-in session for current amount/terms, separate action consent and confirmation. Correct invalid_request; not_found denies access; unavailable leaves review unverified. Safe to repeat with authority checked before/after. Retrieving the link stores no cancellation, grants no execution authority and performs no refund, payment or message.

Input Schema

NameRequiredDescriptionDefault
onceKeyYesCaller-chosen retry key: 16–128 characters from A–Z, a–z, 0–9, underscore or hyphen. Reuse it for the same booking, action and unchanged request facts; use a fresh key for changed facts. The caller creates it; this handoff assigns it no independent expiry or execution authority. Later review still requires a current original session, object, offer and separate action consent.
bookingKeyYesInternal booking ID or visible bookingReference of the one booking already selected by this OAuth connection. Copy the same booking's bookingKey or bookingReference from an available get_offer_status/prepare_offer or authorized booking-read result; prepared returns links, not IDs. Never substitute the supplier offerKey. It grants no access to another booking.

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedOutput schema / oneOf
      Previous value: -[
-  {
-    "additionalProperties": false,
-    "properties": {
-      "consentUrl": {
-        "description": "Open this exact private proposal link in the original signed-in session. Its fragment contains the selected object, action, onceKey and proposed facts. Current authority is rechecked, then the existing flow requires separate visible action consent and confirmation; the link itself grants no authority.",
-        "pattern": "^https:\\/\\/platform-api\\.samuelz\\.com\\/app\\/customer-booking\\/manage#request=",
-        "type": "string"
-      },
-      "status": {
-        "const": "consent_required",
-        "description": "A private proposal link is ready for review; no action consent or execution grant has been issued.",
-        "type": "string"
-      }
-    },
-    "required": [
-      "status",
-      "consentUrl"
-    ],
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "status": {
-        "description": "invalid_request rejects malformed selection/action facts; not_found denies access to the currently selected booking; unavailable means the handoff could not be supplied safely. No booking action has occurred.",
-        "enum": [
-          "invalid_request",
-          "not_found",
-          "unavailable"
-        ],
-        "type": "string"
-      }
-    },
-    "required": [
-      "status"
-    ],
-    "type": "object"
-  }
-]New value: +[
+  {
+    "additionalProperties": false,
+    "properties": {
+      "consentUrl": {
+        "description": "Open this exact private proposal link in the original signed-in session. Its fragment contains the selected object, action, onceKey and either a complete proposal or explicitly requested changes. Current authority is rechecked and unchanged facts are loaded privately. The existing flow then requires a complete proposal, current price and terms, separate visible action consent and confirmation; the link grants no execution authority.",
+        "pattern": "^https:\\/\\/platform-api\\.samuelz\\.com\\/app\\/customer-booking\\/manage#request=",
+        "type": "string"
+      },
+      "status": {
+        "const": "consent_required",
+        "description": "A private proposal link is ready for review; no action consent or execution grant has been issued.",
+        "type": "string"
+      }
+    },
+    "required": [
+      "status",
+      "consentUrl"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "status": {
+        "description": "invalid_request rejects malformed selection or change facts; not_found denies access to the currently selected booking; unavailable means the handoff could not be supplied safely. No booking action has occurred.",
+        "enum": [
+          "invalid_request",
+          "not_found",
+          "unavailable"
+        ],
+        "type": "string"
+      }
+    },
+    "required": [
+      "status"
+    ],
+    "type": "object"
+  }
+]
  2. Changed3 schema fields changed
    • changedInput schema / properties / bookingKey / description
      Previous value: -"Internal booking ID or visible bookingReference of the one booking already selected by this OAuth connection. Copy a returned ID or reference for that same booking; it grants no access to another booking."New value: +"Internal booking ID or visible bookingReference of the one booking already selected by this OAuth connection. Copy the same booking's bookingKey or bookingReference from an available get_offer_status/prepare_offer or authorized booking-read result; prepared returns links, not IDs. Never substitute the supplier offerKey. It grants no access to another booking."
    • changedInput schema / properties / onceKey / description
      Previous value: -"Caller-chosen retry key: 16–128 characters from A–Z, a–z, 0–9, underscore or hyphen. Reuse it for the same booking, action and unchanged request facts; use a fresh key for changed facts. It grants no execution authority."New value: +"Caller-chosen retry key: 16–128 characters from A–Z, a–z, 0–9, underscore or hyphen. Reuse it for the same booking, action and unchanged request facts; use a fresh key for changed facts. The caller creates it; this handoff assigns it no independent expiry or execution authority. Later review still requires a current original session, object, offer and separate action consent."
    • changedOutput schema / oneOf
      Previous value: -[
-  {
-    "additionalProperties": false,
-    "properties": {
-      "consentUrl": {
-        "pattern": "^https:\\/\\/platform-api\\.samuelz\\.com\\/app\\/customer-booking\\/manage#request=",
-        "type": "string"
-      },
-      "status": {
-        "const": "consent_required",
-        "type": "string"
-      }
-    },
-    "required": [
-      "status",
-      "consentUrl"
-    ],
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "status": {
-        "enum": [
-          "invalid_request",
-          "not_found",
-          "unavailable"
-        ],
-        "type": "string"
-      }
-    },
-    "required": [
-      "status"
-    ],
-    "type": "object"
-  }
-]New value: +[
+  {
+    "additionalProperties": false,
+    "properties": {
+      "consentUrl": {
+        "description": "Open this exact private proposal link in the original signed-in session. Its fragment contains the selected object, action, onceKey and proposed facts. Current authority is rechecked, then the existing flow requires separate visible action consent and confirmation; the link itself grants no authority.",
+        "pattern": "^https:\\/\\/platform-api\\.samuelz\\.com\\/app\\/customer-booking\\/manage#request=",
+        "type": "string"
+      },
+      "status": {
+        "const": "consent_required",
+        "description": "A private proposal link is ready for review; no action consent or execution grant has been issued.",
+        "type": "string"
+      }
+    },
+    "required": [
+      "status",
+      "consentUrl"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "status": {
+        "description": "invalid_request rejects malformed selection/action facts; not_found denies access to the currently selected booking; unavailable means the handoff could not be supplied safely. No booking action has occurred.",
+        "enum": [
+          "invalid_request",
+          "not_found",
+          "unavailable"
+        ],
+        "type": "string"
+      }
+    },
+    "required": [
+      "status"
+    ],
+    "type": "object"
+  }
+]
  3. Changed2 schema fields changed
    • addedInput schema / properties / bookingKey / description
      Added value: +"Internal booking ID or visible bookingReference of the one booking already selected by this OAuth connection. Copy a returned ID or reference for that same booking; it grants no access to another booking."
    • addedInput schema / properties / onceKey / description
      Added value: +"Caller-chosen retry key: 16–128 characters from A–Z, a–z, 0–9, underscore or hyphen. Reuse it for the same booking, action and unchanged request facts; use a fresh key for changed facts. It grants no execution authority."
  4. Added

TDQS

A4.8/5.0
Behavior5/5

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

Annotations already declare readOnly/idempotent/non-destructive, yet the description adds substantial context beyond them: the consent_required branch returns a consentUrl that must be opened in the original signed-in session, the error taxonomy (invalid_request, not_found, unavailable) and what each means, and the guarantee that retrieving the link stores no cancellation, grants no execution authority, and performs no refund/payment/message. This is exactly the supplementary behavioral detail annotations cannot convey.

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 use case and exclusion, and every clause is load-bearing (key hygiene, consent flow, error mapping, safety guarantees). It is dense and runs as a single block, which slightly reduces scannability, but 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, so return-shape explanation is unnecessary; the description instead supplies the pieces an agent needs to act correctly — the consent handoff path, session requirement, error handling, and idempotency/authority contract. Nothing material for a two-parameter review tool 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; the description earns an increment by adding cross-parameter and cross-tool semantics the schema only partly states — bookingKey must match the OAuth selection, onceKey is created once per booking/cancellation intent and retained on unchanged retries, and must never be reused from an amendment. Some of this duplicates the onceKey schema text, keeping it from a 5.

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?

Names a specific verb and resource ("review cancellation of the OAuth-selected existing booking") and immediately distinguishes itself from the amendment sibling (prepare_booking_change). An agent can identify what this does and what it does not do 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?

Explicit when-to-use ("customer wants to review cancellation of the ... existing booking"), explicit when-not ("Do not use for a ride amendment"), and two named alternatives with their conditions (get_booking_status for recorded state, get_booking_history for timeline). Nothing is left to inference.

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

All Samuelz Chauffeur Booking toolsInspect
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