Skip to main content
Glama
Sign In

Paddock Cards

by so.paddock
OverviewDiscussionsAdmin

Pay for an order

pay_order
DestructiveIdempotent

Start or resume payment for this exact prepared order and revision. Show the exact amount and returned action_url for the buyer to connect Link, approve this purchase or complete bank authentication. Only the buyer can approve; never ask for payment credentials in chat. Call again after that step, respecting retry_after_seconds. Confirm payment only when status is paid; processing and requires_action are incomplete. Changing the order requires a new quote and approval. Use read_order for separate printing and mailing progress.

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": {
      "order_id": "<order_id>",
      "order_access_token": "<order_access_token>",
      "expected_revision": "<expected_revision>"
    },
    "name": "pay_order"
  }
}

Input Schema

NameRequiredDescriptionDefault
order_idYesParent order.id returned by prepare_order, revise_order or read_order. Use the matching order_access_token; a card ID cannot identify the purchase.
expected_revisionYesParent order.revision for the exact purchase shown to the buyer, returned by prepare_order, revise_order or read_order. A mismatch fails with CONFLICT; read the order and obtain approval for any changed purchase.
order_access_tokenYesExact private order_access_token returned by prepare_order or revise_order for this order. Keep it secret; never invent it or put it in a public URL or log.

Output Schema

NameRequiredDescriptionDefault
okYes
dataYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changed
    • addedInput schema / properties / expected_revision / description
      Added value: +"Parent order.revision for the exact purchase shown to the buyer, returned by prepare_order, revise_order or read_order. A mismatch fails with CONFLICT; read the order and obtain approval for any changed purchase."
    • changedInput schema / properties / order_access_token / description
      Previous value: -"Private purchase capability. Keep it secret; never put it in a public URL or log."New value: +"Exact private order_access_token returned by prepare_order or revise_order for this order. Keep it secret; never invent it or put it in a public URL or log."
    • addedInput schema / properties / order_id / description
      Added value: +"Parent order.id returned by prepare_order, revise_order or read_order. Use the matching order_access_token; a card ID cannot identify the purchase."
    • changedOutput schema / properties / data / oneOf
      Previous value: -[
-  {
-    "additionalProperties": false,
-    "properties": {
-      "action": {
-        "enum": [
-          "connect_and_approve",
-          "approve_purchase",
-          "authenticate_payment"
-        ],
-        "type": "string"
-      },
-      "action_url": {
-        "format": "uri",
-        "type": "string"
-      },
-      "amount_cents": {
-        "exclusiveMinimum": 0,
-        "maximum": 9007199254740991,
-        "type": "integer"
-      },
-      "currency": {
-        "const": "usd",
-        "type": "string"
-      },
-      "order_id": {
-        "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
-        "type": "string"
-      },
-      "retry_after_seconds": {
-        "maximum": 300,
-        "minimum": 1,
-        "type": "integer"
-      },
-      "revision": {
-        "exclusiveMinimum": 0,
-        "maximum": 2147483646,
-        "type": "integer"
-      },
-      "status": {
-        "const": "requires_action",
-        "type": "string"
-      }
-    },
-    "required": [
-      "order_id",
-      "revision",
-      "amount_cents",
-      "currency",
-      "status",
-      "action",
-      "action_url"
-    ],
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "amount_cents": {
-        "exclusiveMinimum": 0,
-        "maximum": 9007199254740991,
-        "type": "integer"
-      },
-      "currency": {
-        "const": "usd",
-        "type": "string"
-      },
-      "order_id": {
-        "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
-        "type": "string"
-      },
-      "retry_after_seconds": {
-        "maximum": 300,
-        "minimum": 1,
-        "type": "integer"
-      },
-      "revision": {
-        "exclusiveMinimum": 0,
-        "maximum": 2147483646,
-        "type": "integer"
-      },
-      "status": {
-        "const": "processing",
-        "type": "string"
-      }
-    },
-    "required": [
-      "order_id",
-      "revision",
-      "amount_cents",
-      "currency",
-      "status",
-      "retry_after_seconds"
-    ],
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "amount_cents": {
-        "exclusiveMinimum": 0,
-        "maximum": 9007199254740991,
-        "type": "integer"
-      },
-      "currency": {
-        "const": "usd",
-        "type": "string"
-      },
-      "order_id": {
-        "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
-        "type": "string"
-      },
-      "revision": {
-        "exclusiveMinimum": 0,
-        "maximum": 2147483646,
-        "type": "integer"
-      },
-      "status": {
-        "const": "paid",
-        "type": "string"
-      }
-    },
-    "required": [
-      "order_id",
-      "revision",
-      "amount_cents",
-      "currency",
-      "status"
-    ],
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "amount_cents": {
-        "exclusiveMinimum": 0,
-        "maximum": 9007199254740991,
-        "type": "integer"
-      },
-      "currency": {
-        "const": "usd",
-        "type": "string"
-      },
-      "order_id": {
-        "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
-        "type": "string"
-      },
-      "revision": {
-        "exclusiveMinimum": 0,
-        "maximum": 2147483646,
-        "type": "integer"
-      },
-      "status": {
-        "const": "failed",
-        "type": "string"
-      }
-    },
-    "required": [
-      "order_id",
-      "revision",
-      "amount_cents",
-      "currency",
-      "status"
-    ],
-    "type": "object"
-  }
-]New value: +[
+  {
+    "additionalProperties": false,
+    "properties": {
+      "action": {
+        "enum": [
+          "connect_and_approve",
+          "approve_purchase",
+          "authenticate_payment"
+        ],
+        "type": "string"
+      },
+      "action_url": {
+        "format": "uri",
+        "type": "string"
+      },
+      "amount_cents": {
+        "exclusiveMinimum": 0,
+        "maximum": 9007199254740991,
+        "type": "integer"
+      },
+      "currency": {
+        "const": "usd",
+        "type": "string"
+      },
+      "order_id": {
+        "description": "Parent order.id returned by prepare_order, revise_order or read_order. Use the matching order_access_token; a card ID cannot identify the purchase.",
+        "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
+        "type": "string"
+      },
+      "retry_after_seconds": {
+        "maximum": 300,
+        "minimum": 1,
+        "type": "integer"
+      },
+      "revision": {
+        "exclusiveMinimum": 0,
+        "maximum": 2147483646,
+        "type": "integer"
+      },
+      "status": {
+        "const": "requires_action",
+        "type": "string"
+      }
+    },
+    "required": [
+      "order_id",
+      "revision",
+      "amount_cents",
+      "currency",
+      "status",
+      "action",
+      "action_url"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "amount_cents": {
+        "exclusiveMinimum": 0,
+        "maximum": 9007199254740991,
+        "type": "integer"
+      },
+      "currency": {
+        "const": "usd",
+        "type": "string"
+      },
+      "order_id": {
+        "description": "Parent order.id returned by prepare_order, revise_order or read_order. Use the matching order_access_token; a card ID cannot identify the purchase.",
+        "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
+        "type": "string"
+      },
+      "retry_after_seconds": {
+        "maximum": 300,
+        "minimum": 1,
+        "type": "integer"
+      },
+      "revision": {
+        "exclusiveMinimum": 0,
+        "maximum": 2147483646,
+        "type": "integer"
+      },
+      "status": {
+        "const": "processing",
+        "type": "string"
+      }
+    },
+    "required": [
+      "order_id",
+      "revision",
+      "amount_cents",
+      "currency",
+      "status",
+      "retry_after_seconds"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "amount_cents": {
+        "exclusiveMinimum": 0,
+        "maximum": 9007199254740991,
+        "type": "integer"
+      },
+      "currency": {
+        "const": "usd",
+        "type": "string"
+      },
+      "order_id": {
+        "description": "Parent order.id returned by prepare_order, revise_order or read_order. Use the matching order_access_token; a card ID cannot identify the purchase.",
+        "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
+        "type": "string"
+      },
+      "revision": {
+        "exclusiveMinimum": 0,
+        "maximum": 2147483646,
+        "type": "integer"
+      },
+      "status": {
+        "const": "paid",
+        "type": "string"
+      }
+    },
+    "required": [
+      "order_id",
+      "revision",
+      "amount_cents",
+      "currency",
+      "status"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "amount_cents": {
+        "exclusiveMinimum": 0,
+        "maximum": 9007199254740991,
+        "type": "integer"
+      },
+      "currency": {
+        "const": "usd",
+        "type": "string"
+      },
+      "order_id": {
+        "description": "Parent order.id returned by prepare_order, revise_order or read_order. Use the matching order_access_token; a card ID cannot identify the purchase.",
+        "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
+        "type": "string"
+      },
+      "revision": {
+        "exclusiveMinimum": 0,
+        "maximum": 2147483646,
+        "type": "integer"
+      },
+      "status": {
+        "const": "failed",
+        "type": "string"
+      }
+    },
+    "required": [
+      "order_id",
+      "revision",
+      "amount_cents",
+      "currency",
+      "status"
+    ],
+    "type": "object"
+  }
+]
  2. Added

TDQS

A4.6/5.0
Behavior5/5

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

Goes well beyond the annotations by disclosing the human-in-the-loop requirement (only the buyer can approve, never request credentials in chat), the retry contract, and unambiguous status semantics (paid vs processing/requires_action incomplete). These are precisely the operational facts a mutating, open-world tool needs and the annotations alone 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?

Purpose is front-loaded and every sentence carries actionable content — approval flow, retry, status confirmation, change handling, sibling routing. It is dense and reads as several packed clauses, but nothing is 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?

For a destructive, idempotent, open-world payment tool with a full output schema, the description covers prerequisites, the approval step, retry behavior, and how to interpret terminal vs non-terminal statuses. Nothing an agent needs to invoke it safely is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and each parameter already has a rich description, so the schema carries the burden. The description reinforces that the exact order and revision must match, but adds no syntax or format meaning beyond the schema; baseline 3 is appropriate.

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?

First sentence states a specific verb and resource ("Start or resume payment") scoped to "this exact prepared order and revision", and the closing sentence routes a different need to read_order. An agent can distinguish this from prepare_order, revise_order and read_order 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 and sequencing: show amount/action_url, buyer approves, then call again respecting retry_after_seconds. It also gives an exclusion (changing the order requires a new quote) and names read_order for printing/mailing progress, so the alternative path is stated rather than inferred.

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

All Paddock Cards 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