Skip to main content
Glama

Format Human-Readable Receipt Explanation

explain_receipt
Read-onlyIdempotent

Format a plain-text trust breakdown and next-action remediation checklist for an Ed25519-signed paxiom.receipt.v0 API delivery receipt. Use this instead of verify_receipt when displaying a readable verdict to a user or operator; use verify_receipt when code needs raw check fields for programmatic gating, or get_x402_verifier_info to discover live Base USDC settlement endpoints. Runs deterministically offline for free with no auth: tampered, unauthorized, expired, or unconfirmed receipts return isError=false with an actionable diagnostic explanation rather than throwing, and omitting trustedVerifierPublicKeys trusts the host counter-attestation key by default. Pass output with the delivered HTTP response body to check SHA-256 payload binding (omitting output caps trustState at valid_signature_only).

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": {
      "receipt": "<receipt>"
    },
    "name": "explain_receipt"
  }
}

Input Schema

NameRequiredDescriptionDefault
outputNoOptional delivered HTTP response payload; pass whenever available so SHA-256 payload binding is evaluated alongside the Ed25519 signature.
receiptYesParsed paxiom.receipt.v0 JSON envelope (decoded from Payment-Receipt or X-Paxiom-Receipt HTTP header).
expectedPayToNoOptional expected seller payTo address from the 402 quote.
trustedPaxiomPublicKeysNoBackward-compatible alias for trustedVerifierPublicKeys.
expectedIssuerPublicKeysNoOptional pinned base64 Ed25519 seller public keys (e.g. from /.well-known/x402-keys.json).
trustedVerifierPublicKeysNoOptional canonical base64 32-byte Ed25519 public keys trusted to assert settlement.checkedByVerifier=true (defaults to the host key).

Output Schema

NameRequiredDescriptionDefault
validYesTrue only when trustState reaches "verified".
trustStateYesUnderlying verification state explained in the report.
explanationYesMulti-line human-readable trust breakdown, failed/skipped check details, and next-step remediation guidance.
receiptHashYesHex SHA-256 digest of the canonical signing input, or null when schema validation failed.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed7 schema fields changed
    • addedInput schema / properties / expectedIssuerPublicKeys
      Added value: +{
      +  "description": "Optional pinned base64 Ed25519 seller public keys (e.g. from /.well-known/x402-keys.json).",
      +  "items": {
      +    "type": "string"
      +  },
      +  "type": "array"
      +}
    • addedInput schema / properties / expectedPayTo
      Added value: +{
      +  "description": "Optional expected seller payTo address from the 402 quote.",
      +  "type": "string"
      +}
    • changedInput schema / properties / output / description
      Previous value: -"Optional delivered HTTP response JSON body; pass whenever available so SHA-256 JCS payload binding is evaluated alongside the Ed25519 signature."New value: +"Optional delivered HTTP response payload; pass whenever available so SHA-256 payload binding is evaluated alongside the Ed25519 signature."
    • changedInput schema / properties / receipt / description
      Previous value: -"Parsed paxiom.receipt.v0 JSON envelope (or base64url-decoded X-Paxiom-Receipt HTTP header)."New value: +"Parsed paxiom.receipt.v0 JSON envelope (decoded from Payment-Receipt or X-Paxiom-Receipt HTTP header)."
    • changedInput schema / properties / trustedPaxiomPublicKeys / description
      Previous value: -"Optional canonical base64 32-byte Ed25519 public keys trusted to assert settlement.checkedByPaxiom=true (defaults to the host Paxiom key)."New value: +"Backward-compatible alias for trustedVerifierPublicKeys."
    • addedInput schema / properties / trustedVerifierPublicKeys
      Added value: +{
      +  "description": "Optional canonical base64 32-byte Ed25519 public keys trusted to assert settlement.checkedByVerifier=true (defaults to the host key).",
      +  "items": {
      +    "type": "string"
      +  },
      +  "type": "array"
      +}
    • changedOutput schema / properties / trustState / enum
      Previous value: -[
      -  "verified",
      -  "valid_signature_only",
      -  "settlement_claimed_not_checked",
      -  "unsupported_format",
      -  "schema_invalid",
      -  "invalid_signature",
      -  "expired",
      -  "output_hash_mismatch",
      -  "settlement_failed",
      -  "proof_invalid",
      -  "proof_unavailable",
      -  "error"
      -]New value: +[
      +  "verified",
      +  "valid_signature_only",
      +  "settlement_claimed_not_checked",
      +  "unsupported_format",
      +  "schema_invalid",
      +  "invalid_signature",
      +  "unauthorized_issuer",
      +  "expired",
      +  "output_hash_mismatch",
      +  "settlement_failed",
      +  "proof_invalid",
      +  "proof_unavailable",
      +  "error"
      +]
  2. Changed4 schema fields changed
    • changedInput schema / properties / output / description
      Previous value: -"Optional delivered API response JSON."New value: +"Optional delivered HTTP response JSON body; pass whenever available so SHA-256 JCS payload binding is evaluated alongside the Ed25519 signature."
    • changedInput schema / properties / receipt / description
      Previous value: -"Parsed paxiom.receipt.v0 JSON object."New value: +"Parsed paxiom.receipt.v0 JSON envelope (or base64url-decoded X-Paxiom-Receipt HTTP header)."
    • changedInput schema / properties / trustedPaxiomPublicKeys / description
      Previous value: -"Optional base64 32-byte Ed25519 public keys trusted to assert checkedByPaxiom=true."New value: +"Optional canonical base64 32-byte Ed25519 public keys trusted to assert settlement.checkedByPaxiom=true (defaults to the host Paxiom key)."
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "properties": {
      +    "explanation": {
      +      "description": "Multi-line human-readable trust breakdown, failed/skipped check details, and next-step remediation guidance.",
      +      "type": "string"
      +    },
      +    "receiptHash": {
      +      "description": "Hex SHA-256 digest of the canonical signing input, or null when schema validation failed.",
      +      "type": [
      +        "string",
      +        "null"
      +      ]
      +    },
      +    "trustState": {
      +      "description": "Underlying verification state explained in the report.",
      +      "enum": [
      +        "verified",
      +        "valid_signature_only",
      +        "settlement_claimed_not_checked",
      +        "unsupported_format",
      +        "schema_invalid",
      +        "invalid_signature",
      +        "expired",
      +        "output_hash_mismatch",
      +        "settlement_failed",
      +        "proof_invalid",
      +        "proof_unavailable",
      +        "error"
      +      ],
      +      "type": "string"
      +    },
      +    "valid": {
      +      "description": "True only when trustState reaches \"verified\".",
      +      "type": "boolean"
      +    }
      +  },
      +  "required": [
      +    "explanation",
      +    "valid",
      +    "trustState",
      +    "receiptHash"
      +  ],
      +  "type": "object"
      +}
  3. First observed

TDQS

A4.6/5.0
Behavior4/5

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

Adds substantial behavior beyond the readOnly/idempotent/non-destructive annotations: deterministic offline execution, no auth, and the crucial guarantee that tampered, unauthorized, expired, or unconfirmed receipts return isError=false with a diagnostic instead of throwing. It also discloses two silent defaults (omitting trustedVerifierPublicKeys trusts the host counter-attestation key; omitting output caps trustState at valid_signature_only). Minor gap: it does not state what the plain-text output looks like or its length/format constraints, though an output schema exists.

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 purpose, then routing, then behavior, then parameter caveats, and every clause earns its place with no filler. It is delivered as one dense compound paragraph with long sentences, which slightly hurts scannability, but nothing is redundant.

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 6-parameter tool with nested objects, an output schema, and full annotations, the description covers the remaining burden: execution model (offline, free, no auth), error semantics, sibling selection, and the two omission defaults. An agent has everything needed to choose and invoke it correctly.

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, but the description adds real semantics the schema does not carry: what happens when trustedVerifierPublicKeys is omitted (host key trusted by default) and what happens when output is omitted (trustState capped at valid_signature_only). Those default-behavior consequences are the highest-value parameter information and are stated explicitly.

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 ('Format') plus the exact artifact produced (plain-text trust breakdown and next-action remediation checklist) and the exact resource (an Ed25519-signed paxiom.receipt.v0 delivery receipt). This is immediately distinguishable from verify_receipt, which returns raw check fields.

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?

Explicitly routes between siblings: use this when displaying a readable verdict to a user/operator, use verify_receipt when code needs raw check fields for programmatic gating, and get_x402_verifier_info to discover live Base USDC settlement endpoints. The when-to-use condition is stated directly rather than implied.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.