Skip to main content
Glama

RCO-A2A - Record of Cleared Orders

by io.github.Agentic-Private-Office
OverviewDiscussionsAdmin

write_receipt

Idempotent

Write one v1 receipt for a read a gate has cleared. Authenticated: Authorization: Bearer . Idempotent on (writer, subject, subject_type, market, rule_version, cleared_at, answer_hash). Returns the receipt.

Input Schema

NameRequiredDescriptionDefault
callerNowho asked, when the gate knows it: x402:<wallet address>; stored only as its sha256
marketNoISO country or exchange code of the read
subjectYeswhat was read: the identifier (an ISIN, LEI, GTIN, ticker, record id …)
caller_keyNothe customer key the reader presented to the gate (RCO-Key); the door checks it and stores sha256("key:" + key id) as caller
cleared_atNoRFC 3339 UTC; stored to the second; the door's clock when absent
answer_hashNosha256:<hex> of the canonical answer bytes the agent received
rule_versionYesthe rule set and version the gate cleared under
subject_typeYesisin | lei | gtin | ticker | cmr | … (open list)

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed12 schema fields changed
    • removedInput schema / properties / actor_class
      Removed value: -{
-  "type": "string"
-}
    • addedInput schema / properties / answer_hash
      Added value: +{
+  "description": "sha256:<hex> of the canonical answer bytes the agent received",
+  "type": "string"
+}
    • addedInput schema / properties / caller
      Added value: +{
+  "description": "who asked, when the gate knows it: x402:<wallet address>; stored only as its sha256",
+  "type": "string"
+}
    • addedInput schema / properties / caller_key
      Added value: +{
+  "description": "the customer key the reader presented to the gate (RCO-Key); the door checks it and stores sha256(\"key:\" + key id) as caller",
+  "type": "string"
+}
    • changedInput schema / properties / cleared_at / description
      Previous value: -"RFC 3339 UTC; the door's clock when absent"New value: +"RFC 3339 UTC; stored to the second; the door's clock when absent"
    • removedInput schema / properties / decision_id
      Removed value: -{
-  "description": "the gate's decision id (dec_<hex>); minted here when absent",
-  "type": "string"
-}
    • removedInput schema / properties / gtin
      Removed value: -{
-  "description": "the cleared object's identifier (a GTIN on goods rails; the ISIN or issuer identifier on a market door)",
-  "type": "string"
-}
    • changedInput schema / properties / market / description
      Previous value: -"ISO 3166-1 alpha-2 market code"New value: +"ISO country or exchange code of the read"
    • changedInput schema / properties / rule_version / description
      Previous value: -"the rule set and version the gate applied"New value: +"the rule set and version the gate cleared under"
    • addedInput schema / properties / subject
      Added value: +{
+  "description": "what was read: the identifier (an ISIN, LEI, GTIN, ticker, record id …)",
+  "type": "string"
+}
    • addedInput schema / properties / subject_type
      Added value: +{
+  "description": "isin | lei | gtin | ticker | cmr | … (open list)",
+  "type": "string"
+}
    • changedInput schema / required
      Previous value: -[
-  "gtin",
-  "actor_class",
-  "rule_version"
-]New value: +[
+  "subject",
+  "subject_type",
+  "rule_version"
+]
  2. Changed9 schema fields changed
    • addedInput schema / properties / actor_class
      Added value: +{
+  "type": "string"
+}
    • addedInput schema / properties / cleared_at
      Added value: +{
+  "description": "RFC 3339 UTC; the door's clock when absent",
+  "type": "string"
+}
    • addedInput schema / properties / decision_id
      Added value: +{
+  "description": "the gate's decision id (dec_<hex>); minted here when absent",
+  "type": "string"
+}
    • addedInput schema / properties / gtin
      Added value: +{
+  "description": "the cleared object's identifier (a GTIN on goods rails; the ISIN or issuer identifier on a market door)",
+  "type": "string"
+}
    • addedInput schema / properties / market
      Added value: +{
+  "description": "ISO 3166-1 alpha-2 market code",
+  "type": "string"
+}
    • removedInput schema / properties / receipt
      Removed value: -{
-  "anyOf": [
-    {
-      "properties": {
-        "actor_class": {
-          "description": "for which actor class (never a person)",
-          "type": "string"
-        },
-        "decided_at": {
-          "type": "string"
-        },
-        "decision_id": {
-          "description": "the id the issuing door gave the decision",
-          "pattern": "^dec_[a-f0-9]{16,40}$",
-          "type": "string"
-        },
-        "issuing_door": {
-          "type": "string"
-        },
-        "object": {
-          "description": "what was cleared: a GTIN, an ISIN, a product id",
-          "properties": {
-            "id": {
-              "type": "string"
-            },
-            "type": {
-              "enum": [
-                "isin",
-                "ticker",
-                "lei",
-                "cmr",
-                "gtin",
-                "product",
-                "identifier"
-              ],
-              "type": "string"
-            }
-          },
-          "required": [
-            "type",
-            "id"
-          ],
-          "type": "object"
-        },
-        "records_read": {
-          "description": "the records read, each with its signature (or null where the record carries none)",
-          "items": {
-            "properties": {
-              "as_of": {
-                "type": [
-                  "string",
-                  "null"
-                ]
-              },
-              "sha256": {
-                "type": [
-                  "string",
-                  "null"
-                ]
-              },
-              "signature": {
-                "type": [
-                  "object",
-                  "null"
-                ]
-              },
-              "url": {
-                "type": "string"
-              }
-            },
-            "required": [
-              "url"
-            ],
-            "type": "object"
-          },
-          "type": "array"
-        },
-        "rule": {
-          "description": "the rule object and version the decision was made under",
-          "properties": {
-            "id": {
-              "type": "string"
-            },
-            "version": {
-              "type": "string"
-            }
-          },
-          "required": [
-            "id",
-            "version"
-          ],
-          "type": "object"
-        },
-        "signal": {
-          "pattern": "^ACM-(000|200|300|403|404|451|500)$",
-          "type": "string"
-        },
-        "signature": {
-          "description": "the issuing door's detached JWS (EdDSA) over the receipt's canonical JSON (keys sorted, compact) without signature, signature_check, ledger, receipt_url, page",
-          "properties": {
-            "alg": {
-              "type": "string"
-            },
-            "jws": {
-              "type": "string"
-            },
-            "keyring": {
-              "type": "string"
-            },
-            "kid": {
-              "type": "string"
-            }
-          },
-          "type": "object"
-        }
-      },
-      "required": [
-        "decision_id",
-        "object",
-        "actor_class",
-        "rule",
-        "records_read",
-        "signal",
-        "decided_at",
-        "issuing_door",
-        "signature"
-      ],
-      "type": "object"
-    },
-    {
-      "properties": {
-        "actor_class": {
-          "type": "string"
-        },
-        "decided_at": {
-          "type": "string"
-        },
-        "decision_id": {
-          "description": "the hub gate decision id",
-          "pattern": "^gate_[a-f0-9]{16,40}$",
-          "type": "string"
-        },
-        "gtin": {
-          "pattern": "^[0-9]{14}$",
-          "type": "string"
-        },
-        "hub": {
-          "enum": [
-            "a2a-grocery",
-            "a2a-cosmetics",
-            "a2a-peptides"
-          ],
-          "type": "string"
-        },
-        "hub_signature": {
-          "description": "the hub's detached JWS over the receipt (keys sorted, compact JSON), verified against the hub keyring",
-          "properties": {
-            "alg": {
-              "type": "string"
-            },
-            "jws": {
-              "type": "string"
-            },
-            "kid": {
-              "type": "string"
-            }
-          },
-          "type": [
-            "object",
-            "null"
-          ]
-        },
-        "market": {
-          "pattern": "^[A-Z]{2}$",
-          "type": "string"
-        },
-        "reason_code": {
-          "type": "string"
-        },
-        "record": {
-          "description": "the gtinfetch answer the decision read: source_page, fetch_date, status, kid",
-          "properties": {
-            "fetch_date": {
-              "type": [
-                "string",
-                "null"
-              ]
-            },
-            "kid": {
-              "type": [
-                "string",
-                "null"
-              ]
-            },
-            "source_page": {
-              "type": [
-                "string",
-                "null"
-              ]
-            },
-            "status": {
-              "type": [
-                "string",
-                "null"
-              ]
-            }
-          },
-          "type": [
-            "object",
-            "null"
-          ]
-        },
-        "result": {
-          "type": "string"
-        },
-        "rule_set": {
-          "properties": {
-            "id": {
-              "type": "string"
-            },
-            "version": {
-              "type": [
-                "string",
-                "null"
-              ]
-            }
-          },
-          "required": [
-            "id"
-          ],
-          "type": "object"
-        }
-      },
-      "required": [
-        "decision_id",
-        "hub",
-        "gtin",
-        "market",
-        "actor_class",
-        "result",
-        "reason_code",
-        "rule_set",
-        "decided_at"
-      ],
-      "type": "object"
-    }
-  ],
-  "description": "a door receipt (dec_ id, x-door-key) or a hub receipt (gate_ id, x-hub-key)",
-  "type": "object"
-}
    • addedInput schema / properties / rule_version
      Added value: +{
+  "description": "the rule set and version the gate applied",
+  "type": "string"
+}
    • changedInput schema / required
      Previous value: -[
-  "receipt"
-]New value: +[
+  "gtin",
+  "actor_class",
+  "rule_version"
+]
    • changedOutput schema / (root)
      Previous value: -{
-  "additionalProperties": true,
-  "properties": {
-    "decision_id": {
-      "type": "string"
-    },
-    "idempotent": {
-      "type": "boolean"
-    },
-    "ledger": {
-      "type": "object"
-    },
-    "page": {
-      "type": "string"
-    },
-    "receipt_url": {
-      "type": "string"
-    },
-    "written": {
-      "type": "boolean"
-    }
-  },
-  "required": [
-    "written",
-    "decision_id",
-    "receipt_url",
-    "ledger"
-  ],
-  "type": "object"
-}New value: +null
  3. Changed4 schema fields changed
    • addedInput schema / properties / receipt / anyOf
      Added value: +[
+  {
+    "properties": {
+      "actor_class": {
+        "description": "for which actor class (never a person)",
+        "type": "string"
+      },
+      "decided_at": {
+        "type": "string"
+      },
+      "decision_id": {
+        "description": "the id the issuing door gave the decision",
+        "pattern": "^dec_[a-f0-9]{16,40}$",
+        "type": "string"
+      },
+      "issuing_door": {
+        "type": "string"
+      },
+      "object": {
+        "description": "what was cleared: a GTIN, an ISIN, a product id",
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "type": {
+            "enum": [
+              "isin",
+              "ticker",
+              "lei",
+              "cmr",
+              "gtin",
+              "product",
+              "identifier"
+            ],
+            "type": "string"
+          }
+        },
+        "required": [
+          "type",
+          "id"
+        ],
+        "type": "object"
+      },
+      "records_read": {
+        "description": "the records read, each with its signature (or null where the record carries none)",
+        "items": {
+          "properties": {
+            "as_of": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "sha256": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "signature": {
+              "type": [
+                "object",
+                "null"
+              ]
+            },
+            "url": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "url"
+          ],
+          "type": "object"
+        },
+        "type": "array"
+      },
+      "rule": {
+        "description": "the rule object and version the decision was made under",
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "version": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "id",
+          "version"
+        ],
+        "type": "object"
+      },
+      "signal": {
+        "pattern": "^ACM-(000|200|300|403|404|451|500)$",
+        "type": "string"
+      },
+      "signature": {
+        "description": "the issuing door's detached JWS (EdDSA) over the receipt's canonical JSON (keys sorted, compact) without signature, signature_check, ledger, receipt_url, page",
+        "properties": {
+          "alg": {
+            "type": "string"
+          },
+          "jws": {
+            "type": "string"
+          },
+          "keyring": {
+            "type": "string"
+          },
+          "kid": {
+            "type": "string"
+          }
+        },
+        "type": "object"
+      }
+    },
+    "required": [
+      "decision_id",
+      "object",
+      "actor_class",
+      "rule",
+      "records_read",
+      "signal",
+      "decided_at",
+      "issuing_door",
+      "signature"
+    ],
+    "type": "object"
+  },
+  {
+    "properties": {
+      "actor_class": {
+        "type": "string"
+      },
+      "decided_at": {
+        "type": "string"
+      },
+      "decision_id": {
+        "description": "the hub gate decision id",
+        "pattern": "^gate_[a-f0-9]{16,40}$",
+        "type": "string"
+      },
+      "gtin": {
+        "pattern": "^[0-9]{14}$",
+        "type": "string"
+      },
+      "hub": {
+        "enum": [
+          "a2a-grocery",
+          "a2a-cosmetics",
+          "a2a-peptides"
+        ],
+        "type": "string"
+      },
+      "hub_signature": {
+        "description": "the hub's detached JWS over the receipt (keys sorted, compact JSON), verified against the hub keyring",
+        "properties": {
+          "alg": {
+            "type": "string"
+          },
+          "jws": {
+            "type": "string"
+          },
+          "kid": {
+            "type": "string"
+          }
+        },
+        "type": [
+          "object",
+          "null"
+        ]
+      },
+      "market": {
+        "pattern": "^[A-Z]{2}$",
+        "type": "string"
+      },
+      "reason_code": {
+        "type": "string"
+      },
+      "record": {
+        "description": "the gtinfetch answer the decision read: source_page, fetch_date, status, kid",
+        "properties": {
+          "fetch_date": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "kid": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "source_page": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "status": {
+            "type": [
+              "string",
+              "null"
+            ]
+          }
+        },
+        "type": [
+          "object",
+          "null"
+        ]
+      },
+      "result": {
+        "type": "string"
+      },
+      "rule_set": {
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "version": {
+            "type": [
+              "string",
+              "null"
+            ]
+          }
+        },
+        "required": [
+          "id"
+        ],
+        "type": "object"
+      }
+    },
+    "required": [
+      "decision_id",
+      "hub",
+      "gtin",
+      "market",
+      "actor_class",
+      "result",
+      "reason_code",
+      "rule_set",
+      "decided_at"
+    ],
+    "type": "object"
+  }
+]
    • addedInput schema / properties / receipt / description
      Added value: +"a door receipt (dec_ id, x-door-key) or a hub receipt (gate_ id, x-hub-key)"
    • removedInput schema / properties / receipt / properties
      Removed value: -{
-  "actor_class": {
-    "type": "string"
-  },
-  "decided_at": {
-    "type": "string"
-  },
-  "decision_id": {
-    "description": "the hub gate decision id",
-    "pattern": "^gate_[a-f0-9]{16,40}$",
-    "type": "string"
-  },
-  "gtin": {
-    "pattern": "^[0-9]{14}$",
-    "type": "string"
-  },
-  "hub": {
-    "enum": [
-      "a2a-grocery",
-      "a2a-cosmetics",
-      "a2a-peptides"
-    ],
-    "type": "string"
-  },
-  "hub_signature": {
-    "description": "the hub's detached JWS over the receipt (keys sorted, compact JSON), verified against the hub keyring",
-    "properties": {
-      "alg": {
-        "type": "string"
-      },
-      "jws": {
-        "type": "string"
-      },
-      "kid": {
-        "type": "string"
-      }
-    },
-    "type": [
-      "object",
-      "null"
-    ]
-  },
-  "market": {
-    "pattern": "^[A-Z]{2}$",
-    "type": "string"
-  },
-  "reason_code": {
-    "type": "string"
-  },
-  "record": {
-    "description": "the gtinfetch answer the decision read: source_page, fetch_date, status, kid",
-    "properties": {
-      "fetch_date": {
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "kid": {
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "source_page": {
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "status": {
-        "type": [
-          "string",
-          "null"
-        ]
-      }
-    },
-    "type": [
-      "object",
-      "null"
-    ]
-  },
-  "result": {
-    "type": "string"
-  },
-  "rule_set": {
-    "properties": {
-      "id": {
-        "type": "string"
-      },
-      "version": {
-        "type": [
-          "string",
-          "null"
-        ]
-      }
-    },
-    "required": [
-      "id"
-    ],
-    "type": "object"
-  }
-}
    • removedInput schema / properties / receipt / required
      Removed value: -[
-  "decision_id",
-  "hub",
-  "gtin",
-  "market",
-  "actor_class",
-  "result",
-  "reason_code",
-  "rule_set",
-  "decided_at"
-]
  4. First observed

TDQS

A3.8/5.0
Behavior4/5

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

Goes meaningfully beyond the annotations: annotations only declare idempotent/non-destructive/non-readOnly, while the description adds the Bearer writer-token auth requirement, the exact idempotency key tuple, and what is returned. It omits failure modes (what happens on a duplicate or a rejected token), so not a 5.

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?

Four short sentences, all front-loaded and load-bearing: purpose, auth, idempotency key, return. No filler or restatement of the tool name beyond the necessary scope statement.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Auth and idempotency are well covered and annotations carry the safety profile, but there is no output schema and 'Returns the receipt' does not describe the returned shape or key fields. For an 8-parameter mutation with an open-ended subject_type, that leaves a real gap for an agent that needs to chain verify_receipt afterwards.

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 already 100%, so the baseline is 3, but the description adds genuinely new semantics by enumerating which fields compose the idempotency key (writer, subject, subject_type, market, rule_version, cleared_at, answer_hash), which the schema does not state. 'writer' is also mapped to the token implicitly, though caller/caller_key interplay is left to the schema.

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?

States a specific verb and resource — 'Write one v1 receipt for a read a gate has cleared' — which clearly distinguishes a write from the sibling reads/verifications (list_receipts, verify_receipt, get_statement). It does not explicitly name those siblings, and 'v1 receipt' / 'gate' assume domain familiarity, so it stops short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'for a read a gate has cleared' implies a precondition for use, and the auth header requirement is stated, but there is no explicit when-to-use guidance, no mention of when not to write a receipt, and no routing versus verify_receipt or list_receipts.

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

All RCO-A2A - Record of Cleared Orders 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