Skip to main content
Glama

An independent witness for a live deal: each party sends the hash of every event as it happens and gets a signed receipt with the time and its place in the chain

witness_record
Idempotent

Witness a deal event. Send deal_id, party_id, event_type, content_hash (SHA-256 hex of the content, never the content), your Ed25519 public_key and your sig (base64 signature over the canonical JSON of {content_hash, deal_id, event_type, party_id, type:'witness-event', v:1}). Get back a receipt signed by Witness: the time we saw it, its place (seq) in the deal's chain, and the chain hash over the previous receipt. It shows only that this hash was sent by this key and seen at this time, in this order. It does not show the content is true, who the party is, or that nothing else was sent. Stores hashes, types, public keys, signatures and times for 400 days after the deal's last event; never content or addresses. Free.

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": {
      "deal_id": "<deal_id>",
      "party_id": "<party_id>",
      "event_type": "<event_type>",
      "content_hash": "<content_hash>",
      "public_key": "<public_key>",
      "sig": "<sig>"
    },
    "name": "witness_record"
  }
}

Input Schema

NameRequiredDescriptionDefault
sigYesbase64 Ed25519 signature over the canonical JSON of the event (see description).
deal_idYesOpaque id both parties use for the deal. Use a random one (16+ characters); anyone who knows it can add events to the chain.
party_idYesOpaque id of the sender. Its key is fixed by its first event in the deal.
event_typeYesLowercase label such as offer, accept, payment, delivery, confirm.
public_keyYesEd25519 public key, 32 bytes, base64.
content_hashYesSHA-256 of the event content, lowercase hex.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.1/5.0
Behavior5/5

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

Annotations only declare write/non-destructive/idempotent, while the description goes well beyond them: it states what is stored (hashes, types, public keys, signatures, times), the 400-day retention after the last event, that content and addresses are never stored, and that the service is free. It also draws a precise boundary on what the receipt proves versus does not prove (content truth, party identity, completeness), which is exactly the disclosure an agent needs before committing a write.

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?

Action and requirements are front-loaded, and the epistemic caveats and retention policy are tightly packed into single clauses with no filler. It is dense to the point of being slightly run-on, but every sentence carries operational weight.

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?

With six required parameters and no output schema, the description must explain the return value itself, and it does: time observed, sequence position, and the chain hash over the previous receipt. Combined with retention, storage scope and proof limitations, an agent has everything needed to call it and interpret the result.

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 would be 3, but the description adds the canonical signing payload ({content_hash, deal_id, event_type, party_id, type:'witness-event', v:1}) and the 'never the content' rule, which the schema only references generically. That extra detail materially reduces malformed signatures.

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?

The description names a specific verb and resource ('Witness a deal event') and immediately specifies the mechanics: send a content hash plus signature, receive a signed receipt with time, seq and chain hash. It is unmistakably an append-to-hash-chain tool, which separates it in spirit from verify/lookup siblings, but it never names or contrasts an alternative tool explicitly.

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?

Usage is implied rather than prescribed: the title says 'each party sends the hash of every event as it happens', which frames the when (per event, both sides), and the deal_id parameter warns that anyone who knows the id can append. There is no explicit when-not guidance, no mention of how to handle a failed signature, and no routed alternative for verification or lookup.

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.

Resources