Skip to main content
Glama

inspect_receipt

Read-onlyIdempotent

Retrieve signed receipt records and Merkle inclusion proofs from a JSONL log after cryptographic verification, so you can audit specific tool invocations or export portable proofs.

Instructions

Retrieve individual signed receipt records, standalone RFC 6962 Merkle inclusion proofs, and optional AER-1 envelopes from an on-disk JSONL receipt log, whereas verify_receipt_log returns only a whole-log summary. Call when auditing a specific tool invocation or exporting portable inclusion proofs; do not use for a fast whole-file pass/fail check (use verify_receipt_log) or assistant reply checking (use verify_narration). Cryptographically verifies the entire log before returning data: filters seq, call_id, and tool combine via logical AND (omitting all three lists from seq=0 truncated to limit), while a missing/tampered file, key mismatch, or out-of-range seq returns isError=true.

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": {
      "log_path": "<log_path>"
    },
    "name": "inspect_receipt"
  }
}

Input Schema

NameRequiredDescriptionDefault
seqNoOptional exact zero-based log sequence index to retrieve.
toolNoOptional canonical tool name to filter receipts by.
limitNoMaximum number of matched entries to return (default: 20).
call_idNoOptional exact tool call identifier to filter by.
log_pathYesFilesystem path to the JSONL receipt log file.
pubkey_fileNoOptional path to a pinned public key JSON or hex file.
include_aer1NoWhen true, attach the canonical AER-1 interoperable receipt envelope to each matched entry (default: false).
expected_pubkey_hexNoOptional pinned 64-character hex Ed25519 public key.

Output Schema

NameRequiredDescriptionDefault
entriesYesMatched receipt records with standalone Merkle proofs.
log_validYesTrue after full-file signature and Merkle verification.
key_pinnedYesTrue when verified against expected_pubkey_hex or pubkey_file.
entry_countYesTotal entries present in the verified JSONL log.
match_countYesNumber of filtered receipt entries returned in entries.
merkle_rootYesHex-encoded 64-char RFC 6962 SHA-256 Merkle root of the log.
public_key_hexYesHex-encoded Ed25519 public key that signed the log.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.1.2
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "additionalProperties": false,
      +  "properties": {
      +    "entries": {
      +      "description": "Matched receipt records with standalone Merkle proofs.",
      +      "items": {
      +        "properties": {
      +          "aer1": {
      +            "description": "Canonical AER-1 envelope when include_aer1=true.",
      +            "type": "object"
      +          },
      +          "merkle_inclusion_proof": {
      +            "description": "Standalone O(log N) RFC 6962 inclusion proof.",
      +            "properties": {
      +              "leaf_index": {
      +                "description": "Zero-based leaf position in Merkle tree.",
      +                "type": "integer"
      +              },
      +              "leaf_sha256": {
      +                "description": "Domain-separated 0x00 leaf SHA-256 hex.",
      +                "type": "string"
      +              },
      +              "root_sha256": {
      +                "description": "Expected 64-char hex RFC 6962 Merkle root.",
      +                "type": "string"
      +              },
      +              "siblings": {
      +                "description": "Ordered sibling hashes from leaf to root.",
      +                "items": {
      +                  "properties": {
      +                    "sha256": {
      +                      "description": "64-char hex sibling digest.",
      +                      "type": "string"
      +                    },
      +                    "side": {
      +                      "description": "Sibling position (L or R).",
      +                      "enum": [
      +                        "L",
      +                        "R"
      +                      ],
      +                      "type": "string"
      +                    }
      +                  },
      +                  "required": [
      +                    "side",
      +                    "sha256"
      +                  ],
      +                  "type": "object"
      +                },
      +                "type": "array"
      +              },
      +              "tree_size": {
      +                "description": "Total leaf count in the Merkle tree.",
      +                "type": "integer"
      +              }
      +            },
      +            "required": [
      +              "leaf_index",
      +              "tree_size",
      +              "leaf_sha256",
      +              "siblings",
      +              "root_sha256"
      +            ],
      +            "type": "object"
      +          },
      +          "receipt": {
      +            "description": "Signed ToolReceipt fields (tool, args, ok, etc.).",
      +            "type": "object"
      +          },
      +          "seq": {
      +            "description": "Zero-based sequence index in the JSONL log.",
      +            "type": "integer"
      +          }
      +        },
      +        "required": [
      +          "seq",
      +          "receipt",
      +          "merkle_inclusion_proof"
      +        ],
      +        "type": "object"
      +      },
      +      "type": "array"
      +    },
      +    "entry_count": {
      +      "description": "Total entries present in the verified JSONL log.",
      +      "type": "integer"
      +    },
      +    "key_pinned": {
      +      "description": "True when verified against expected_pubkey_hex or pubkey_file.",
      +      "type": "boolean"
      +    },
      +    "log_valid": {
      +      "description": "True after full-file signature and Merkle verification.",
      +      "type": "boolean"
      +    },
      +    "match_count": {
      +      "description": "Number of filtered receipt entries returned in entries.",
      +      "type": "integer"
      +    },
      +    "merkle_root": {
      +      "description": "Hex-encoded 64-char RFC 6962 SHA-256 Merkle root of the log.",
      +      "type": "string"
      +    },
      +    "public_key_hex": {
      +      "description": "Hex-encoded Ed25519 public key that signed the log.",
      +      "type": "string"
      +    }
      +  },
      +  "required": [
      +    "log_valid",
      +    "entry_count",
      +    "merkle_root",
      +    "public_key_hex",
      +    "key_pinned",
      +    "match_count",
      +    "entries"
      +  ],
      +  "type": "object"
      +}
  2. Addedv0.1.1

TDQS

A4.8/5.0
Behavior5/5

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

Goes well beyond the annotations (which only declare read-only/idempotent/closed-world) by disclosing that the entire log is cryptographically verified before any data is returned, how the three filters combine (logical AND, with omission behaving as seq=0 truncated to limit), and the exact failure modes that produce isError=true (missing/tampered file, key mismatch, out-of-range seq). That is operationally critical context an agent cannot get from the annotations or schema.

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 single paragraph that front-loads the what and the sibling contrast before the behavioral caveats, and no sentence is filler. It is heavy with semicolon-chained clauses, which slightly hurts scannability for such a filter-rich tool.

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 an 8-parameter tool with an output schema (so return shape needn't be restated), the description covers selection, filtering semantics, verification behavior, and error conditions. Nothing an agent needs to call it correctly 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?

With 100% schema coverage the baseline is 3, but the description adds meaning the schema does not: the AND combination of seq/call_id/tool and the specific default fill behavior when all three filters are omitted. Limit, log_path, and pubkey_file behavior is otherwise left to the schema, which already documents them adequately.

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?

Specific verb ("Retrieve") plus three concretely named resources (signed receipt records, RFC 6962 Merkle inclusion proofs, AER-1 envelopes) and the source (on-disk JSONL receipt log). It also explicitly contrasts itself with verify_receipt_log's whole-log summary, so the agent can distinguish it from siblings without opening a 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?

Gives explicit when-to-use (auditing a specific tool invocation, exporting portable inclusion proofs) and explicit when-not-to-use, naming the correct alternatives: verify_receipt_log for a fast whole-file pass/fail and verify_narration for reply checking. Routing is fully determined.

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