Collar Guardrail — Pre-Trade Risk Layer

Evaluate Trade (x402 Paid, Tier 2)

evaluate_trade_paid

Read-onlyIdempotent

Pre-trade risk check gated by an x402 payment. Evaluated as COLR Tier 2: $25,000 notional ceiling, 10/25 per-minute rate limits. No COLR holdings are required — the on-chain payment is the credential.

FLOW

Call WITHOUT payment_proof → the tool returns a PaymentRequiredOutput describing the on-chain payment (network, asset, amount, payTo, resource).
Settle the payment on-chain using an x402-capable client. The facilitator returns a proof string.
Call again with payment_proof=<proof> → the tool forwards the proof to the guardrail's x402-paid endpoint and returns a full EvaluateTradeOutput with tier=2.

Input Schema

TableJSON Schema

Name	Required	Description
`side`	Yes	"buy" or "sell".
`asset`	Yes	Asset symbol, e.g. NVDA, AAPL, TSLA, USDG.
`amount`	Yes	Quantity in token units.
`wallet`	Yes	EVM wallet address (0x...) the trade would execute from.
`request_id`	No	Optional idempotency key.
`payment_proof`	No	x402 payment proof from the facilitator. Omit on the first call to receive the payment challenge.
`contract_address`	Yes	Token contract address (0x...).
`max_slippage_bps`	No	Max slippage in basis points (default 100).

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 7, 2026

changedOutput schema / properties / result / anyOf

Previous value: -[
-  {
-    "description": "Result of a pre-trade risk check.",
-    "properties": {
-      "audit_hash": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "default": null,
-        "description": "SHA-256 hash chaining this decision."
-      },
-      "audit_seq": {
-        "anyOf": [
-          {
-            "type": "integer"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "default": null,
-        "description": "Monotonic sequence number of this decision."
-      },
-      "calculated_notional_usd": {
-        "description": "USD value of the proposed trade.",
-        "type": "number"
-      },
-      "decision": {
-        "description": "Final verdict. 'deny' is a hard stop.",
-        "enum": [
-          "allow",
-          "warn",
-          "deny"
-        ],
-        "type": "string"
-      },
-      "error": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "default": null,
-        "description": "If present, no verdict was produced. Treat as a hard stop; do not execute the trade."
-      },
-      "max_trade_usd": {
-        "description": "USD ceiling for this tier.",
-        "type": "number"
-      },
-      "price_source": {
-        "description": "Where the price came from.",
-        "enum": [
-          "oracle",
-          "uniswap_v4",
-          "fallback_default",
-          "unavailable"
-        ],
-        "type": "string"
-      },
-      "price_usd": {
-        "description": "Asset price used for the valuation.",
-        "type": "number"
-      },
-      "reasons": {
-        "description": "Human-readable reasons. Entries prefixed with 'ADVISORY:' are non-blocking context; all other entries drove the decision.",
-        "items": {
-          "type": "string"
-        },
-        "type": "array"
-      },
-      "request_id": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "default": null,
-        "description": "Echoed idempotency key, if provided."
-      },
-      "risk_score": {
-        "description": "Composite risk score from 0 (safe) to 100 (blocked).",
-        "type": "integer"
-      },
-      "tier": {
-        "description": "Tier the wallet was evaluated at (1-3).",
-        "type": "integer"
-      }
-    },
-    "required": [
-      "decision",
-      "reasons",
-      "tier",
-      "max_trade_usd",
-      "calculated_notional_usd",
-      "price_usd",
-      "price_source",
-      "risk_score"
-    ],
-    "type": "object"
-  },
-  {
-    "description": "x402 payment challenge returned when no proof is supplied.\n\nThe client is expected to settle this payment on-chain and retry the\ntool with the resulting proof carried in `payment_proof`.",
-    "properties": {
-      "amount": {
-        "description": "Amount in asset base units (6 decimals for USDG).",
-        "type": "string"
-      },
-      "asset": {
-        "description": "USDG contract address.",
-        "type": "string"
-      },
-      "description": {
-        "description": "Human-readable purpose.",
-        "type": "string"
-      },
-      "error": {
-        "default": null,
-        "type": "null"
-      },
-      "max_timeout_seconds": {
-        "description": "Payment validity window in seconds.",
-        "type": "integer"
-      },
-      "network": {
-        "description": "CAIP-2 network id, e.g. eip155:4663.",
-        "type": "string"
-      },
-      "pay_to": {
-        "description": "Recipient address for the payment.",
-        "type": "string"
-      },
-      "resource": {
-        "description": "Resource URL the payment unlocks.",
-        "type": "string"
-      },
-      "status": {
-        "const": "payment_required",
-        "default": "payment_required",
-        "type": "string"
-      },
-      "tier_granted": {
-        "description": "Tier the paid proof grants (2 for x402 paid access).",
-        "type": "integer"
-      }
-    },
-    "required": [
-      "network",
-      "asset",
-      "amount",
-      "pay_to",
-      "resource",
-      "description",
-      "max_timeout_seconds",
-      "tier_granted"
-    ],
-    "type": "object"
-  }
-]New value: +[
+  {
+    "description": "Result of a pre-trade risk check.",
+    "properties": {
+      "audit_hash": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "description": "SHA-256 hash chaining this decision."
+      },
+      "audit_seq": {
+        "anyOf": [
+          {
+            "type": "integer"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "description": "Monotonic sequence number of this decision."
+      },
+      "calculated_notional_usd": {
+        "default": 0,
+        "description": "USD value of the proposed trade.",
+        "type": "number"
+      },
+      "decision": {
+        "default": "deny",
+        "description": "Final verdict. 'deny' is a hard stop.",
+        "enum": [
+          "allow",
+          "warn",
+          "deny"
+        ],
+        "type": "string"
+      },
+      "detail": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "description": "Human-readable detail accompanying `error`, if any."
+      },
+      "error": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "description": "If present, no verdict was produced. Treat as a hard stop; do not execute the trade."
+      },
+      "guidance": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "description": "Suggested next step accompanying `error`, if any."
+      },
+      "max_trade_usd": {
+        "default": 0,
+        "description": "USD ceiling for this tier.",
+        "type": "number"
+      },
+      "price_source": {
+        "default": "unavailable",
+        "description": "Where the price came from.",
+        "enum": [
+          "oracle",
+          "uniswap_v4",
+          "fallback_default",
+          "unavailable"
+        ],
+        "type": "string"
+      },
+      "price_usd": {
+        "default": 0,
+        "description": "Asset price used for the valuation.",
+        "type": "number"
+      },
+      "reasons": {
+        "description": "Human-readable reasons. Entries prefixed with 'ADVISORY:' are non-blocking context; all other entries drove the decision.",
+        "items": {
+          "type": "string"
+        },
+        "type": "array"
+      },
+      "request_id": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "description": "Echoed idempotency key, if provided."
+      },
+      "risk_score": {
+        "default": 100,
+        "description": "Composite risk score from 0 (safe) to 100 (blocked).",
+        "type": "integer"
+      },
+      "tier": {
+        "default": 1,
+        "description": "Tier the wallet was evaluated at (1-3).",
+        "type": "integer"
+      }
+    },
+    "type": "object"
+  },
+  {
+    "description": "x402 payment challenge returned when no proof is supplied.\n\nThe client is expected to settle this payment on-chain and retry the\ntool with the resulting proof carried in `payment_proof`.",
+    "properties": {
+      "amount": {
+        "description": "Amount in asset base units (6 decimals for USDG).",
+        "type": "string"
+      },
+      "asset": {
+        "description": "USDG contract address.",
+        "type": "string"
+      },
+      "description": {
+        "description": "Human-readable purpose.",
+        "type": "string"
+      },
+      "error": {
+        "default": null,
+        "type": "null"
+      },
+      "max_timeout_seconds": {
+        "description": "Payment validity window in seconds.",
+        "type": "integer"
+      },
+      "network": {
+        "description": "CAIP-2 network id, e.g. eip155:4663.",
+        "type": "string"
+      },
+      "pay_to": {
+        "description": "Recipient address for the payment.",
+        "type": "string"
+      },
+      "resource": {
+        "description": "Resource URL the payment unlocks.",
+        "type": "string"
+      },
+      "status": {
+        "const": "payment_required",
+        "default": "payment_required",
+        "type": "string"
+      },
+      "tier_granted": {
+        "description": "Tier the paid proof grants (2 for x402 paid access).",
+        "type": "integer"
+      }
+    },
+    "required": [
+      "network",
+      "asset",
+      "amount",
+      "pay_to",
+      "resource",
+      "description",
+      "max_timeout_seconds",
+      "tier_granted"
+    ],
+    "type": "object"
+  }
+]

AddedSep 20, 2026

TDQS

A4.4/5.0

Behavior5/5

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

Annotations only declare the safety profile (readOnly, idempotent, non-destructive). The description adds real behavioral context they cannot convey: the exact notional ceiling ($25,000), per-minute rate limits, the fact that no COLR holdings are required, and the full challenge/settle/retry payment lifecycle. This is genuinely more than the annotations provide.

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?

The purpose and tier constraints are front-loaded in the first paragraph, and the numbered FLOW is well-structured for a multi-call protocol. It is slightly verbose in places (restating the tier twice), but nearly every sentence earns its place given the two-step payment dance.

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 values need not be spelled out, and the description still names the two response shapes (PaymentRequiredOutput, EvaluateTradeOutput with tier=2) to connect the flow to its outputs. Combined with full parameter coverage and the safety annotations, an agent has everything needed to invoke it correctly.

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 description coverage is 100%, so the parameters are already fully documented. The description's payment_proof explanation largely restates what the schema already says ('Omit on the first call to receive the payment challenge'), and the tier/rate details are tool-level constraints rather than parameter semantics, so this sits at the baseline.

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 and resource: 'Pre-trade risk check gated by an x402 payment.' It then pins the exact service tier ('COLR Tier 2') and its limits, which cleanly distinguishes this paid variant from the free `evaluate_trade` sibling without needing to open either schema.

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 FLOW section gives unambiguous when-to-use guidance for the two call modes (omit `payment_proof` to get the challenge, then resend with the proof), which is essential for a two-step tool. It stops short of explicitly naming `evaluate_trade` as the free alternative, so the paid-vs-free routing choice is only implied by 'the on-chain payment is the credential.'

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

All Collar Guardrail — Pre-Trade Risk Layer 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.