Skip to main content
Glama
Sign In

Samuelz Chauffeur Booking

by com.samuelz.platform-api
OverviewDiscussionsAdmin

Read your record documents

get_record_documents
Read-onlyIdempotent

Use this when reading existing invoices, credit notes and verified stored payment/refund evidence for one authorized record. Do not use for an unpaid checkout: use get_booking_payment_review. This read creates or sends no documents and executes no payment or refund.

Selection: omit recordKey for a single-record grant; with a collection grant, call list_customer_records and pass one returned key as recordKey.

Access: customer:documents:read consent AND verified document-recipient authority are required; participation alone is insufficient. Open private links in the customer's signed-in session. API downloads retain the OAuth resource, recordKey and artifactId. No storage keys or other recipients' documents are exposed.

Evidence: returns verified PDF metadata and private review/download links. paymentEvidence requires validated stored provider settlement plus exact document/bank bindings. Credit notes alone do not prove refunds. No provider refresh or complete later-reversal coverage; missing evidence does not mean unpaid or unrefunded.

Outcomes: an empty documents array means no eligible document found, not no invoice exists. not_found masks absent or unauthorized records; consent_required requests only the missing document permission; unavailable means retry later.

Input Schema

NameRequiredDescriptionDefault
recordKeyNoInternal record ID returned by this same authorized customer overview, or the record already selected during consent. It grants no access by itself and cannot switch tenant or module.

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedOutput schema / anyOf
      Previous value: -[
-  {
-    "additionalProperties": false,
-    "properties": {
-      "documents": {
-        "description": "Existing issued invoices and credit notes with verified recipient authority and current PDF evidence. An empty array means no eligible document was found; it does not assert payment, delivery, or a refund.",
-        "items": {
-          "additionalProperties": false,
-          "properties": {
-            "apiDownloadUrl": {
-              "description": "Authenticated API download URL. Send the same OAuth bearer and resource; no cookie or secret is embedded in this URL.",
-              "format": "uri",
-              "type": "string"
-            },
-            "artifactId": {
-              "description": "Identifier of the current verified PDF artifact.",
-              "minLength": 1,
-              "type": "string"
-            },
-            "currency": {
-              "description": "ISO 4217 currency of this document.",
-              "pattern": "^[A-Z]{3}$",
-              "type": "string"
-            },
-            "downloadUrl": {
-              "description": "Private customer-session download URL. This URL is not a bearer capability. API clients use the authenticated document download route with the same recordKey and artifactId.",
-              "format": "uri",
-              "type": "string"
-            },
-            "fileName": {
-              "description": "Suggested download filename.",
-              "minLength": 1,
-              "type": "string"
-            },
-            "grossAmountMinor": {
-              "description": "Gross total in minor units of currency; 12000 means 120.00 for EUR or GBP.",
-              "maximum": 9007199254740991,
-              "minimum": 0,
-              "type": "integer"
-            },
-            "id": {
-              "description": "Identifier of an existing issued document.",
-              "minLength": 1,
-              "type": "string"
-            },
-            "issueDate": {
-              "description": "Stored issue date in YYYY-MM-DD.",
-              "format": "date",
-              "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$",
-              "type": "string"
-            },
-            "kind": {
-              "description": "invoice or credit_note; these are existing documents, not a new refund.",
-              "enum": [
-                "invoice",
-                "credit_note"
-              ],
-              "type": "string"
-            },
-            "number": {
-              "description": "Stored invoice or credit-note number.",
-              "minLength": 1,
-              "type": "string"
-            },
-            "reviewUrl": {
-              "description": "Private review page; requires the customer login and current document permission.",
-              "format": "uri",
-              "type": "string"
-            },
-            "sha256": {
-              "description": "SHA-256 digest of the current PDF bytes.",
-              "pattern": "^[a-f0-9]{64}$",
-              "type": "string"
-            }
-          },
-          "required": [
-            "id",
-            "number",
-            "kind",
-            "issueDate",
-            "currency",
-            "grossAmountMinor",
-            "artifactId",
-            "sha256",
-            "fileName",
-            "reviewUrl",
-            "downloadUrl",
-            "apiDownloadUrl"
-          ],
-          "type": "object"
-        },
-        "maxItems": 64,
-        "type": "array"
-      },
-      "observedAt": {
-        "description": "Cutoff for this read in ISO 8601; reauthorization occurs before and after the read. This is not a provider refresh.",
-        "format": "date-time",
-        "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$",
-        "type": "string"
-      },
-      "recordKey": {
-        "description": "Internal record ID returned by this same authorized customer overview, or the record already selected during consent. It grants no access by itself and cannot switch tenant or module.",
-        "maxLength": 128,
-        "minLength": 1,
-        "type": "string"
-      },
-      "status": {
-        "const": "available",
-        "type": "string"
-      }
-    },
-    "required": [
-      "status",
-      "observedAt",
-      "recordKey",
-      "documents"
-    ],
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "status": {
-        "const": "invalid_request",
-        "type": "string"
-      }
-    },
-    "required": [
-      "status"
-    ],
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "status": {
-        "const": "not_found",
-        "type": "string"
-      }
-    },
-    "required": [
-      "status"
-    ],
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "status": {
-        "const": "unavailable",
-        "type": "string"
-      }
-    },
-    "required": [
-      "status"
-    ],
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "status": {
-        "const": "consent_required",
-        "type": "string"
-      }
-    },
-    "required": [
-      "status"
-    ],
-    "type": "object"
-  }
-]New value: +[
+  {
+    "additionalProperties": false,
+    "properties": {
+      "documents": {
+        "description": "Existing issued invoices and credit notes with verified recipient authority and current PDF evidence. An empty array means no eligible document was found; it does not assert payment, delivery, or a refund.",
+        "items": {
+          "additionalProperties": false,
+          "properties": {
+            "apiDownloadUrl": {
+              "description": "Authenticated API download URL. Send the same OAuth bearer and resource; no cookie or secret is embedded in this URL.",
+              "format": "uri",
+              "type": "string"
+            },
+            "artifactId": {
+              "description": "Identifier of the current verified PDF artifact.",
+              "minLength": 1,
+              "type": "string"
+            },
+            "currency": {
+              "description": "ISO 4217 currency of this document.",
+              "pattern": "^[A-Z]{3}$",
+              "type": "string"
+            },
+            "downloadUrl": {
+              "description": "Private customer-session download URL. This URL is not a bearer capability. API clients use the authenticated document download route with the same recordKey and artifactId.",
+              "format": "uri",
+              "type": "string"
+            },
+            "fileName": {
+              "description": "Suggested download filename.",
+              "minLength": 1,
+              "type": "string"
+            },
+            "grossAmountMinor": {
+              "description": "Gross total in minor units of currency; 12000 means 120.00 for EUR or GBP.",
+              "maximum": 9007199254740991,
+              "minimum": 0,
+              "type": "integer"
+            },
+            "id": {
+              "description": "Identifier of an existing issued document.",
+              "minLength": 1,
+              "type": "string"
+            },
+            "issueDate": {
+              "description": "Stored issue date in YYYY-MM-DD.",
+              "format": "date",
+              "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$",
+              "type": "string"
+            },
+            "kind": {
+              "description": "invoice or credit_note; these are existing documents, not a new refund.",
+              "enum": [
+                "invoice",
+                "credit_note"
+              ],
+              "type": "string"
+            },
+            "number": {
+              "description": "Stored invoice or credit-note number.",
+              "minLength": 1,
+              "type": "string"
+            },
+            "reviewUrl": {
+              "description": "Private review page; requires the customer login and current document permission.",
+              "format": "uri",
+              "type": "string"
+            },
+            "sha256": {
+              "description": "SHA-256 digest of the current PDF bytes.",
+              "pattern": "^[a-f0-9]{64}$",
+              "type": "string"
+            }
+          },
+          "required": [
+            "id",
+            "number",
+            "kind",
+            "issueDate",
+            "currency",
+            "grossAmountMinor",
+            "artifactId",
+            "sha256",
+            "fileName",
+            "reviewUrl",
+            "downloadUrl",
+            "apiDownloadUrl"
+          ],
+          "type": "object"
+        },
+        "maxItems": 64,
+        "type": "array"
+      },
+      "observedAt": {
+        "description": "Cutoff for this read in ISO 8601; reauthorization occurs before and after the read. This is not a provider refresh.",
+        "format": "date-time",
+        "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$",
+        "type": "string"
+      },
+      "paymentEvidence": {
+        "additionalProperties": false,
+        "properties": {
+          "basis": {
+            "const": "verified_stored_provider_settlement",
+            "description": "Events are bound to validated persisted provider settlement sources, the authorized official document and its exact matched bank transaction.",
+            "type": "string"
+          },
+          "currentReversalCoverage": {
+            "const": "not_attested",
+            "description": "Later reversals or disputes may not be covered; do not infer current settlement finality.",
+            "type": "string"
+          },
+          "items": {
+            "description": "Only evidence for the current recipient-authorized record documents; empty is not proof of nonpayment.",
+            "items": {
+              "additionalProperties": false,
+              "properties": {
+                "amountMinor": {
+                  "description": "Verified positive event amount in minor currency units; this is not a current outstanding balance.",
+                  "exclusiveMinimum": 0,
+                  "maximum": 9007199254740991,
+                  "type": "integer"
+                },
+                "currency": {
+                  "description": "Currency of the verified event. The initial stored Stripe settlement adapter supports EUR.",
+                  "pattern": "^[A-Z]{3}$",
+                  "type": "string"
+                },
+                "documentId": {
+                  "description": "ID of the authorized invoice or credit note to which this evidence is bound.",
+                  "minLength": 1,
+                  "type": "string"
+                },
+                "id": {
+                  "description": "Stable opaque identifier for this authorized stored payment or refund evidence; it grants no access.",
+                  "pattern": "^[a-f0-9]{64}$",
+                  "type": "string"
+                },
+                "kind": {
+                  "description": "Verified stored incoming payment or outgoing refund event, not the invoice or credit note itself.",
+                  "enum": [
+                    "payment",
+                    "refund"
+                  ],
+                  "type": "string"
+                },
+                "occurredAt": {
+                  "description": "Time of the recorded provider event; no fresh provider request was made.",
+                  "format": "date-time",
+                  "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$",
+                  "type": "string"
+                },
+                "provider": {
+                  "const": "stripe",
+                  "description": "Provider of the persisted verified event, not a new provider confirmation.",
+                  "type": "string"
+                }
+              },
+              "required": [
+                "id",
+                "documentId",
+                "kind",
+                "amountMinor",
+                "currency",
+                "occurredAt",
+                "provider"
+              ],
+              "type": "object"
+            },
+            "maxItems": 64,
+            "type": "array"
+          },
+          "liveProviderRefresh": {
+            "const": false,
+            "description": "Always false: no provider refresh, payment, refund, document issuance or delivery occurs.",
+            "type": "boolean"
+          },
+          "status": {
+            "description": "available has verified stored events; not_available means no eligible proof was found, not unpaid or unrefunded; unavailable means proof could not be checked safely.",
+            "enum": [
+              "available",
+              "not_available",
+              "unavailable"
+            ],
+            "type": "string"
+          }
+        },
+        "required": [
+          "status",
+          "basis",
+          "liveProviderRefresh",
+          "currentReversalCoverage",
+          "items"
+        ],
+        "type": "object"
+      },
+      "recordKey": {
+        "description": "Internal record ID returned by this same authorized customer overview, or the record already selected during consent. It grants no access by itself and cannot switch tenant or module.",
+        "maxLength": 128,
+        "minLength": 1,
+        "type": "string"
+      },
+      "status": {
+        "const": "available",
+        "type": "string"
+      }
+    },
+    "required": [
+      "status",
+      "observedAt",
+      "recordKey",
+      "documents"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "status": {
+        "const": "invalid_request",
+        "type": "string"
+      }
+    },
+    "required": [
+      "status"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "status": {
+        "const": "not_found",
+        "type": "string"
+      }
+    },
+    "required": [
+      "status"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "status": {
+        "const": "unavailable",
+        "type": "string"
+      }
+    },
+    "required": [
+      "status"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "status": {
+        "const": "consent_required",
+        "type": "string"
+      }
+    },
+    "required": [
+      "status"
+    ],
+    "type": "object"
+  }
+]
  2. Added

TDQS

A4.8/5.0
Behavior5/5

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

Annotations cover the safe-read profile, but the description adds substantial beyond-schema context: required consent (customer:documents:read) plus verified recipient authority, participation being insufficient, signed-in session requirement for private links, and disclosure limits. It also enumerates outcome semantics (empty array ≠ no invoice, not_found masking, consent_required, unavailable) and evidence caveats.

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?

Dense and front-loaded with 'Use this when', organized into Selection/Access/Evidence/Outcomes sections so each block is scannable. It is long, but nearly every sentence carries distinct operational information; minor tightening possible in the Access/Evidence blocks.

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 clarifies return semantics (verified PDF metadata plus private links, paymentEvidence binding requirements, no provider refresh) and error outcomes. For a single-param tool with rich annotations, nothing an agent needs to call it or interpret results 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% and the single recordKey is already documented, but the description adds genuine value by explaining the omit-vs-collection-grant selection logic and the list_customer_records prerequisite. Slightly above baseline because it changes how the agent decides to pass the param.

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 (reading) and resource (invoices, credit notes, verified payment/refund evidence for one authorized record), and explicitly names the sibling it must not be used for (get_booking_payment_review for unpaid checkouts). An agent can distinguish it from all siblings without opening any 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, when-not-to-use with a named alternative, plus a selection rule: omit recordKey for a single-record grant, or call list_customer_records and pass a returned key for a collection grant. 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