This server lets you hash local files, verify blockchain timestamp proofs locally, explain proof metadata, and create ProofLedger-anchored proofs for files.
Compute file hashes: compute_file_hash hashes a local file with SHA-256 by default, or another hashlib algorithm, without uploading it.
Verify files against proofs: verify_file recomputes a file's hash and checks it against a proof JSON, including Merkle-root recomputation when present.
Verify known hashes: verify_hash checks an existing hash against inline proof JSON or a proof file path.
Explain proofs: explain_proof describes what a proof asserts, its blockchain/transaction/time/service metadata, and how to check it on a block explorer.
Create proofs: create_proof computes a file hash locally and submits only the digest to ProofLedger, anchoring it on Polygon, with optional Bitcoin anchoring and optional filename labeling; this is the only networked/account-requiring tool and needs PROOFLEDGER_API_KEY.
Allows verifying that a file's SHA-256 hash matches a blockchain-anchored timestamp proof on Bitcoin, confirming the file existed at a specific time.
Allows verifying that a file's SHA-256 hash matches a blockchain-anchored timestamp proof on Ethereum, confirming the file existed at a specific time.
Allows verifying that a file's SHA-256 hash matches a blockchain-anchored timestamp proof on Polygon, confirming the file existed at a specific time.
Check a blockchain timestamp proof on your own machine, and make one through an API.
verify-proof recomputes a file's SHA-256 hash and checks it against a proof bundle, so you can confirm that this exact file existed by the time it was anchored and has not changed by a single byte since. Verification is pure computation: it needs the file and the bundle, no account and no network call. Creating a proof is the one command that goes online, through ProofLedger's API with a free key. Free, MIT licensed, Python standard library only.
Also available for Node.js:
npm install verify-proof, a zero-dependency port sharing the same proof format and semantics, tested against the same fixtures. Seejs/.
The sections below are the questions people ask, each answered with the shortest code that does it.
How do I verify a timestamp proof offline, without trusting the service?
How do I add a timestamp step to a Zapier, Make or n8n workflow?
How do I prove what an AI agent did without storing what it saw?
Is there a GitHub Action or GitHub App that timestamps release artifacts?
Use it from an AI assistant (MCP server, Claude Code, Cursor)
pip install verify-proofThe base install pulls no dependencies (it uses only the Python standard library) and gives you a verify-proof command:
verify-proof --helpTo use it as an MCP server for Claude Desktop or Cursor, install the optional extra instead (details below):
pip install "verify-proof[mcp]"Prefer to run from source? Clone it; the CLI works the same:
git clone https://github.com/Fulcrum-Enterprises/verify-proof.git
cd verify-proof
python verify_proof.py --helpRelated MCP server: Web Resource Ledger
Hash the file locally, anchor the hash in a public blockchain transaction, and keep the record of that transaction next to the file. The transaction's block time is the "no later than" date; the hash ties it to these exact bytes. The file itself never leaves your machine.
This package does the hashing and the verifying; ProofLedger does the anchoring, on Polygon, usually within a minute, with a free API key (100 API proofs a month on the Free plan):
Get a free key at proofledger.io
From the command line:
export PROOFLEDGER_API_KEY=sk_... # Account > API Keys
verify-proof create contract.pdf
verify-proof create contract.pdf --no-filename # send only the hashOnly the 64-character SHA-256 digest leaves your machine, plus the filename unless you pass --no-filename. Then save the proof's bundle next to the file; the offline verify command below works on it from then on, without ProofLedger:
curl -H "Authorization: Bearer $PROOFLEDGER_API_KEY" \
"https://proofledger.io/api/v1/proof/42/bundle?download=1" -o contract.pdf.proof.jsonFrom Python, with the small API client the package carries (standard library only):
from proofledger_api import submit_proof, get_bundle
from verify_proof import hash_file
import json
proof = submit_proof(hash_file("contract.pdf"), filename="contract.pdf",
external_id="contract-2026-10") # key from PROOFLEDGER_API_KEY
print(proof["id"], proof["certificate_url"])
bundle = get_bundle(proof["id"]) # once the anchor has landed
json.dump(bundle, open("contract.pdf.proof.json", "w"), indent=2)From Node.js:
import { hashFile, ProofLedger } from "verify-proof";
const pl = new ProofLedger({ apiKey: process.env.PROOFLEDGER_API_KEY });
const proof = await pl.createProof({ sha256: hashFile("contract.pdf"), externalId: "contract-2026-10" });
const bundle = await pl.getBundle(proof.id); // once the anchor has landedOr straight at the API: POST https://proofledger.io/api/v1/proof with {"sha256": "<64 hex>"} and a Bearer sk_... header. The API is documented at proofledger.io/api, with an OpenAPI spec at /openapi.json.
external_id is your own record id: sending the same one again returns the existing proof instead of making a new one, so a retried job never double-anchors.
verify-proof verify contract.pdf --proof bundle.json
# VERIFIED: File matches the proof bundle. The bundle says it was anchored on polygon at 2026-10-15T02:11:09.512Z in transaction 0xabc123.... Look that transaction up on a block explorer to confirm it: https://polygonscan.com/tx/0xabc123...The check runs locally: it hashes the file, compares the result with the hash in the bundle, computes the Merkle root if the bundle has a path, and reports the transaction to look up on a block explorer. It does not read the chain, so until you look that transaction up, the anchor is what the bundle says. Nothing is sent anywhere, so it works the same whether or not the service that issued the proof still exists.
The same check from Python:
from verify_proof import hash_file, load_proof, verify_proof
result = verify_proof(hash_file("contract.pdf"), load_proof("bundle.json"))
print(result["verified"], result["tx_id"], result.get("explorer_url"))And from Node.js: verifyProof(hashFile("contract.pdf"), loadProof("bundle.json")).
A test you can run on any vendor's proof: block the vendor's domain, then verify. If the check still passes, the proof is yours; if it needs the vendor's server to say "valid", you are relying on them staying in business.
verify-proof hash contract.pdf
# SHA256: a1b2c3d4e5f6...
# File: contract.pdfA successful verify prints one line to stderr saying where to make proofs like it. It is suppressed whenever the output is piped or redirected, so scripts never see it, and stdout is unchanged either way. To silence it everywhere:
export VERIFY_PROOF_NO_HINT=1A Merkle path is the list of sibling hashes between your leaf (the file's hash) and the root that was recorded on chain. Validating it means folding your hash up through the siblings and comparing the result with the root in the transaction. The rule this package uses, in full:
import hashlib
def merkle_root(leaf_hex: str, path: list[dict]) -> str:
current = leaf_hex
for step in path: # [{"hash": "<hex>", "position": "left" | "right"}, ...]
sibling = step["hash"]
combined = sibling + current if step.get("position") == "left" else current + sibling
current = hashlib.sha256(bytes.fromhex(combined)).hexdigest()
return currentEach level concatenates the two hashes as raw bytes, in the order the position says, and hashes the result with SHA-256. verify_proof() runs exactly this when a bundle carries a merkle_path, returns the root as merkle_root, and prints it so you can compare it with the root recorded in the transaction. The comparison with the chain is yours to make: this package never reads the chain.
On Polygon, ProofLedger anchors each proof in its own transaction, so merkle_path is empty and the hash in the transaction is your file's hash directly. Bitcoin-anchored proofs from other services, and the few ProofLedger proofs anchored on Bitcoin before 2026-10-15, carry a path.
Up to 100 hashes in one call, each with your own external_id, so a re-run returns the proofs that already exist instead of anchoring twice:
from proofledger_api import submit_batch, get_proof_by_external_id
from verify_proof import hash_file
result = submit_batch([
{"sha256": hash_file("invoice-1001.pdf"), "external_id": "invoice-1001", "filename": "invoice-1001.pdf"},
{"sha256": hash_file("invoice-1002.pdf"), "external_id": "invoice-1002"},
])
print(result["summary"]) # created / exists / invalid counts
for item in result["items"]:
print(item["result"], (item.get("proof") or {}).get("id"))
later = get_proof_by_external_id("invoice-1001") # None if you never anchored itNode.js: await pl.createProofs(items) takes the same list, and pl.getProofByExternalId(id) looks one up. From an AI assistant, the create_proofs_batch MCP tool does this for a list of files, using each file's name as its record id.
Items are checked first and written together; a batch is Polygon only. For plain request retries there is also an optional Idempotency-Key header on the creating endpoints (the same key and body within 24 hours replays the stored response), but external_id is the simpler way to make submissions safe to retry.
Register a public https URL once; ProofLedger then POSTs a signed JSON event, proof.polygon.anchored, when a proof's Polygon anchor lands. The event carries the proof's bundle, so your handler can save it next to the file with nothing further to fetch.
import { ProofLedger, verifyWebhookSignature } from "verify-proof";
const pl = new ProofLedger({ apiKey: process.env.PROOFLEDGER_API_KEY });
const hook = await pl.registerWebhook("https://example.com/proofledger", ["proof.polygon.anchored"]);
// hook.secret is shown once; keep it for the check belowCheck every delivery before trusting it. The header is ProofLedger-Signature: t=<unix>,v1=<hex HMAC-SHA256> over t + "." + raw body; pass the body exactly as received:
from proofledger_api import verify_webhook_signature
ok = verify_webhook_signature(secret, request.headers["ProofLedger-Signature"], request.get_data())Node.js: verifyWebhookSignature(secret, header, rawBody). Both are pure computation, no network. Failed deliveries are retried seven times over almost two days, then the endpoint is switched off and the account emailed. Webhooks fire only for proofs created after the endpoint was registered. Management endpoints: POST /api/v1/webhooks, GET to list, DELETE /api/v1/webhooks/:id, POST /api/v1/webhooks/:id/test.
Yes. ProofLedger Community is the same proof core as an open-source (AGPL-3.0) Node + SQLite server you run with your own Polygon key: the same v1 API shapes (single and batch proofs with external_id, bundles, lists, public verify, certificates, signed webhooks, Idempotency-Key, per-key rate limits), writing the same transaction shape as proofledger.io, so this tool checks its bundles the same way.
git clone https://github.com/Fulcrum-Enterprises/proofledger-community.git
cd proofledger-community
cp .env.example .env # set PUBLIC_BASE_URL, POLYGON_RPC_URL and POLYGON_PRIVATE_KEY
docker compose up -d # pulls ghcr.io/fulcrum-enterprises/proofledger-community
docker compose exec proofledger node src/cli.js user add you@example.com
docker compose exec proofledger node src/cli.js key create you@example.com "laptop"Then point this package at it: --base-url https://proofs.example.com on the CLI, base_url= in Python, baseUrl in Node. The hosted service at proofledger.io is a separate product (managed signer, backups, branding, the integrations and support) and is not open source.
All three produce ordinary ProofLedger proofs, so the bundles verify with this tool like any other.
n8n: the community node n8n-nodes-proofledger (installed from Settings > Community Nodes). The ProofLedger node hashes a binary field inside n8n and sends only the hash, or takes a hash you already have, one at a time or 100 per call; it reads proofs back, fetches bundles, verifies and manages webhooks. The ProofLedger Trigger registers the webhook itself and checks every delivery's signature. Source: github.com/Fulcrum-Enterprises/n8n-nodes-proofledger. It is a community node, not an n8n-verified one.
Zapier: a private integration, by invite link only until Zapier lists it: join here. Trigger Proof Anchored (signature-checked), creates Create Proof From Hash and Create Proof From File (hashed inside the Zap run; only the hash reaches ProofLedger), searches Find Proof by External ID and Verify Hash.
Make: a custom app, by invite link only: install here. Modules for creating a proof from a SHA-256 hash, getting one by id or external id, fetching a bundle, verifying a hash, listing proofs, and an instant trigger, Watch anchored proofs. There is no file module on Make; hash the file first.
With an agent run receipt: a hash chain over the steps of one run. Each step keeps only a SHA-256 fingerprint of its content (salted with a per-run secret), its type, its time and an optional short label. The chain head is anchored on ProofLedger as one ordinary proof, and the bundle is saved into the receipt. Anyone holding the receipt can recompute the chain and check the head against the bundle offline; nobody can read the prompts, tool calls or outputs from it.
from agent_receipt import RunReceipt
r = RunReceipt("support-ticket-48213", agent={"name": "support-bot", "model": "claude-sonnet-5-5"})
r.prompt(customer_message, label="customer message")
r.tool_call(json.dumps(call), label="lookup_order")
r.tool_result(result_text)
r.output(reply, label="reply sent")
r.anchor() # one API proof; waits for the Polygon anchor (key from PROOFLEDGER_API_KEY)
r.save("ticket-48213.receipt.json")verify-proof receipt verify ticket-48213.receipt.json # offline: chain + bundle
verify-proof receipt verify ticket-48213.receipt.json --step 0 --content customer-message.txt
verify-proof receipt show ticket-48213.receipt.json # labels and fingerprints, never content
verify-proof receipt anchor ticket-48213.receipt.json # anchor a saved, unanchored receiptRemove the secret field before handing a receipt to a third party: the chain still verifies, and nothing in the file can be guessed; checking a step against its content then needs your secret (--secret). The format is proofledger-agent-run-receipt/1; examples/receipt.json is a sample the Python and Node ports both verify, and examples/langchain_receipt_callback.py is a LangChain callback handler that builds a receipt from a run. The chain rule is in the module docstring of agent_receipt.py, so it can be recomputed in any language. Node.js has the same RunReceipt, verifyReceipt and verifyStep.
A receipt shows that this exact sequence of steps existed by the anchor time and has not changed since, and, given a step's content and the secret, that the step was made from that content. It does not show that the agent was right, or who ran it.
Both, from the same account.
The Action, ProofLedger Release Timestamp in the GitHub Marketplace, hashes the artifact on the runner (the file never leaves it), submits the hash, waits for the Polygon anchor, writes the proof into the release notes and attaches the bundle (<label>.proof.json) to the release, which is what this tool verifies the file against later:
name: Timestamp Release
on:
release:
types: [published]
jobs:
timestamp:
runs-on: ubuntu-latest
permissions:
contents: write # needed to update the release body and attach the proof bundle
steps:
- uses: actions/checkout@v4
- name: Build release artifact
run: zip -r dist/release.zip src/
- name: Timestamp with ProofLedger
uses: Fulcrum-Enterprises/proofanchor-github-action@v2
with:
api-key: ${{ secrets.PROOFLEDGER_API_KEY }}
file: dist/release.zip(The repository kept its old name; uses: lines stay as above.)
The App, github.com/apps/proofledger, needs no workflow: install it on a repository, connect it to a ProofLedger account once, and every release published there is anchored on its own, one proof per release file from the SHA-256 GitHub reports (no file is downloaded), with a proof table in the release notes and the bundle attached once the hash is on Polygon. It holds Contents read and write on the chosen repositories and nothing else. It installs from that page; it is not in the GitHub Marketplace. Docs: proofledger.io/api.html#sec-github.
verify-proof ships an optional Model Context Protocol server, so MCP-compatible AI clients (Claude Desktop, Cursor and others) can verify blockchain timestamp proofs directly in a conversation. The file never leaves your machine: hashing and verification run locally, and only the resulting hash is ever compared against the proof.
pip install "verify-proof[mcp]"The base install stays dependency-free; the [mcp] extra adds the MCP SDK and installs a verify-proof-mcp command (a stdio server).
Tool | What it does |
| Compute the SHA-256 (or other) hash of a local file |
| Verify a local file against a proof JSON file |
| Verify a known hash against inline or file-based proof data |
| Describe, in plain language, what a proof asserts and how to check it on a block explorer |
| Anchor a file's hash on ProofLedger to create a new proof. Uses the network and needs an API key |
| Anchor up to 100 files in one API call; file names double as external ids, so re-running on unchanged files returns their existing proofs. If a file changed but kept its name, you get its old proof back, so rename it or anchor it with |
| Current anchoring status of one of your proofs. Network, API key |
| Download a proof's bundle (this package's proof format) and save it next to the file, so verification needs nothing from ProofLedger later. Network, API key |
| Start an agent run receipt file (fresh secret, no steps). Offline |
| Fingerprint one step (prompt, tool_call, tool_result, output, note) into the receipt; the content is only hashed. Offline |
| Anchor the receipt's chain head as one proof and save the bundle into the receipt. Network, API key |
| Recompute the chain and check it against the bundle, optionally checking one step's content. Offline |
This repository is also a Claude Code plugin marketplace. The proofledger plugin bundles the MCP server (started with uvx, so it needs uv and nothing else) and three skills, /proofledger:anchor, /proofledger:verify and /proofledger:receipt:
/plugin marketplace add Fulcrum-Enterprises/verify-proof
/plugin install proofledger@proofledgerThen ask: "Anchor dist/app-1.4.0.zip and save its proof next to it." Creating proofs reads PROOFLEDGER_API_KEY from the shell that starts Claude Code; verifying needs no key. Details in claude-plugin/.
Add this to your claude_desktop_config.json (see examples/claude_desktop_config.json):
{
"mcpServers": {
"verify-proof": {
"command": "verify-proof-mcp"
}
}
}Restart Claude Desktop. If verify-proof-mcp isn't found on your PATH, use the Python module form instead: "command": "python", "args": ["-m", "verify_proof_mcp"].
One click, with uv installed (Cursor starts the server with uvx, nothing to pip install):
Or add it by hand to ~/.cursor/mcp.json (or a project's .cursor/mcp.json):
{
"mcpServers": {
"verify-proof": {
"command": "uvx",
"args": ["--from", "verify-proof[mcp]", "verify-proof-mcp"]
}
}
}Creating proofs reads PROOFLEDGER_API_KEY from the environment Cursor runs in; verifying needs no key. The claude-plugin/ folder also carries a Cursor plugin manifest (.cursor-plugin/plugin.json, mcp.json, the same three skills), so the repository can be imported as a Cursor marketplace.
Then ask the assistant things like:
"Verify ~/contract.pdf against ~/contract-proof.json."
"What does this proof file actually prove?"
"Timestamp this file and save its bundle next to it."
The verification tools need no account and make no network calls. To confirm the anchor itself, look up the transaction on any block explorer. The create, batch, status and bundle tools are the exception: they send hashes and file names, never files, to ProofLedger with your API key.
A bundle is one JSON document. Abridged:
{
"format": "verify-proof/1",
"service": "proofledger",
"hash": "a1b2c3d4e5f6...",
"algorithm": "sha256",
"blockchain": "polygon",
"tx_id": "0xabc123...",
"anchored_at": "2026-10-15T02:11:09.512Z",
"merkle_path": [],
"proof_id": 42,
"certificate_url": "https://proofledger.io/cert/42"
}If a Merkle path is present, verify computes the Merkle root and prints it (see How do I validate a Merkle proof in code?). Compare it with the root recorded in the transaction:
"merkle_path": [
{"hash": "def456...", "position": "right"},
{"hash": "789abc...", "position": "left"}
]examples/ holds a format sample: sample.txt and a proof.json that carries its hash. The transaction in it is made up and does not exist on Polygon, so a block explorer finds nothing. It shows the file format only, not a real anchor.
verify-proof computes the SHA-256 hash of your local file
It reads the proof JSON to get the originally anchored hash
If the hashes match, the file hasn't been modified since timestamping
If a Merkle path is present, it computes the Merkle root and prints it; compare it with the root recorded in the transaction
It does not read the chain: look the transaction up on any block explorer to confirm the anchor (for Polygon, the verdict prints the polygonscan link)
A proof shows that a file with this exact SHA-256 fingerprint existed by the anchor time, and that the file has not changed since. The record sits on a public chain rather than in any one company's database, so anyone can check it without an account and without seeing the file.
It does not show who made the file, it is not a copyright registration, and it does not stop anyone copying the file.
This tool verifies proofs created by:
ProofLedger: proof of existence as an API. Send a hash, get a Polygon-anchored certificate anyone can verify without us. Free plan with 100 API proofs a month.
ProofLedger Community: the same proof core as an open-source (AGPL-3.0) server you host with your own Polygon key. Same API and bundle format; point this tool at it with --base-url (Python base_url=, Node baseUrl).
Any service producing SHA-256 hash proofs with blockchain transaction references.
MIT License. Free to use, modify, and distribute.
Built by Fulcrum Enterprises LLC, building tools for blockchain-verified proof of existence.
Compute the cryptographic hash of a local file.
The file is read and hashed locally; its contents are never uploaded or transmitted. SHA-256 (the default) is the algorithm used by Bitcoin, Polygon, and blockchain timestamp services such as ProofLedger. Use this to obtain the fingerprint that a timestamp proof anchors, or to confirm a file has not changed.
Args: file_path: Path to the file on the local machine. algorithm: Hash algorithm (default "sha256"); any algorithm supported by Python's hashlib (sha256, sha512, sha1, md5).
Returns: The hex-encoded hash digest.
| Name | Required | Description | Default |
|---|---|---|---|
| algorithm | No | sha256 | |
| file_path | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral disclosure burden. It does well by stating that the file is hashed locally and never uploaded, that SHA-256 is the default, and that the result is a hex-encoded digest. It does not discuss edge cases like large-file handling, but for this tool the core behavior is well covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with purpose first, followed by Args and Returns. The blockchain context sentence is somewhat extra but still relevant to the intended use case, and the overall length is appropriate.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter tool, the description covers everything needed to call it correctly: the file path, optional algorithm, default behavior, local-only processing, and return format. The output schema exists, so the return value description is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must fully explain the parameters, and it does. It explains file_path as a local path and algorithm with its default and valid Python hashlib options, adding substantial meaning beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action and resource: computing the cryptographic hash of a local file. It even provides use cases (obtaining a proof fingerprint, confirming a file has not changed), but it does not explicitly differentiate itself from siblings like verify_hash or verify_file beyond the implied compute-vs-verify distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives concrete scenarios for when to use the tool: obtaining the fingerprint for a timestamp proof or confirming a file has not changed. It does not explicitly mention when not to use it or name alternative tools, but the context is clear enough to guide selection among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a blockchain timestamp proof for a local file, via ProofLedger.
This is the only tool here that uses the network, and the only one that needs an account. Use it when the user wants to PROVE a file exists as of now, rather than check an existing proof. The file's SHA-256 is computed locally and only that digest is sent - the file itself never leaves the machine. The hash is anchored on Polygon (included on every plan, free tier included); Bitcoin anchoring is metered per anchor.
Requires a ProofLedger API key in the PROOFLEDGER_API_KEY environment variable. If it is missing, this returns the steps to get a free one - show them to the user rather than treating it as a failure.
Args: file_path: Path to the file to timestamp. bitcoin: Also request Bitcoin anchoring. Metered per anchor, so the proof returns marked REQUIRED until that anchor is paid for. send_filename: Send the filename as a label so the proof is findable in the dashboard. Set false to send only the hash.
Returns: A plain-text summary of the created proof: its id, status, and the URLs for its certificate and public verification page.
| Name | Required | Description | Default |
|---|---|---|---|
| bitcoin | No | ||
| file_path | Yes | ||
| send_filename | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure, and it does so thoroughly. It reveals that the tool uses the network, requires an account/API key, computes the SHA-256 locally, sends only the digest, anchors on Polygon or metered Bitcoin, and returns a proof that may be REQUIRED until Bitcoin anchoring is paid. This is far more transparent than a typical 'create proof' one-liner.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is organized into clear, front-loaded sections: purpose, usage condition, privacy, auth, parameters, and returns. Although detailed, every sentence adds operational value—network/account requirements, local hashing, billing, missing-key behavior, and parameter effects—so the length is justified and there is no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and a schema with zero property descriptions, this description is unusually complete. It covers prerequisites, network and account implications, privacy safeguards, billing behavior, parameter semantics, missing-key fallback, and return format, so an agent has everything needed to invoke the tool correctly and interpret its output.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the Args section fully compensates by explaining all three parameters: file_path, bitcoin, and send_filename. It goes beyond the schema's types and defaults by describing billing consequences, the REQUIRED status, and privacy/display implications, giving the agent the semantic context needed to set each parameter correctly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Create a blockchain timestamp proof for a local file, via ProofLedger.' It also differentiates this tool from its siblings by stating it is the only one that uses the network and the only one that needs an account, so an agent can immediately tell it apart from compute/verify/explain tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Use it when the user wants to PROVE a file exists as of now, rather than check an existing proof,' giving a clear selection condition. It also contrasts this tool with checking/verifying existing proofs and notes that it is the only network- and account-requiring sibling, which routes the agent correctly. The missing-API-key handling further clarifies expected behavior.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Explain, in plain language, what a blockchain timestamp proof contains.
Does not require the original file. Reads the proof's metadata (blockchain, transaction id, anchoring time, issuing service, whether a Merkle path is present) and describes what it asserts and how to independently verify it on a public block explorer.
Args: proof_json: The proof as a JSON string, OR a path to a proof JSON file.
Returns: A plain-language description of the proof.
| Name | Required | Description | Default |
|---|---|---|---|
| proof_json | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the transparency burden. It discloses a read-only behavior ('Reads the proof's metadata'), says the original file is not needed, and implies it does not perform verification itself ('how to independently verify'). It omits error handling details, but for a simple explainer this is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description front-loads the core purpose, then adds a compact metadata summary and clean Args/Returns sections. Every sentence earns its place without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With a single well-documented parameter, a clear return description, and an output schema present, an agent has everything necessary to select and invoke the tool correctly. The only minor gap is explicit sibling routing, already covered in usage_guidelines.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% — the schema only says proof_json is a string. The description's Args section fully compensates by explaining the string can be a JSON payload OR a path to a proof JSON file, adding essential meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence names a specific verb ('Explain') and resource ('blockchain timestamp proof'), and the rest clarifies it reads metadata and describes verification. This clearly distinguishes it from sibling tools that compute or verify hashes/files.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context by noting it 'does not require the original file' and works by reading proof metadata. However, it does not explicitly name alternative tools or state when not to use it, so it falls short of a full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Verify a local file against a blockchain-anchored timestamp proof.
Recomputes the file's hash locally and checks it against the hash recorded in the proof JSON. If a Merkle path is present, it recomputes the Merkle root. Confirms a blockchain transaction reference is present. A passing result means the file is byte-for-byte identical to the file that was timestamped, and the proof points to a public transaction (on Polygon or Bitcoin) that anyone can check on a block explorer.
Args: file_path: Path to the local file to verify. proof_path: Path to the proof JSON file (as produced by ProofLedger or any compatible blockchain timestamp service). algorithm: Hash algorithm (default "sha256").
Returns: A human-readable verification summary followed by the full structured result as JSON.
| Name | Required | Description | Default |
|---|---|---|---|
| algorithm | No | sha256 | |
| file_path | Yes | ||
| proof_path | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full transparency burden and does well: it discloses the local hash recomputation, Merkle-root recomputation when applicable, transaction-reference confirmation, and what a passing result does and does not mean. It stops short of stating whether any network access occurs or how failures/mismatches are surfaced.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: purpose first, then verification mechanics, then parameter definitions, then return-value note. Every sentence contributes useful information, and there is no redundant restating of the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with an output schema and only three simple string parameters, the description is nearly complete. It explains the verifier's behavior, parameter roles, and return structure. Remaining gaps are minor: no explicit failure/error behavior and no statement about whether the tool contacts the blockchain network.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must fully document parameters. It does: file_path is the local file, proof_path is the proof JSON produced by ProofLedger or a compatible service, and algorithm has its default noted. This adds real meaning beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb-resource pairing: 'Verify a local file against a blockchain-anchored timestamp proof.' It then explains exactly what verification involves (recomputing the file hash and comparing to the proof), which clearly distinguishes this from siblings like compute_file_hash or verify_hash.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The intended use case is clear: use this when you have a local file plus a proof JSON and want to confirm byte-for-byte integrity against a timestamped anchor. It provides useful context but does not explicitly state when-not-to-use or name alternatives, so it falls just short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Verify a known file hash against inline proof data.
Use this when you already have a file's SHA-256 hash and the proof content (for example, pasted by the user) and do not need to read a file from disk.
Args: file_hash: The hex-encoded SHA-256 hash of the file. proof_json: The proof as a JSON string, OR a path to a proof JSON file.
Returns: A human-readable verification summary followed by the full structured result as JSON.
| Name | Required | Description | Default |
|---|---|---|---|
| file_hash | Yes | ||
| proof_json | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it does disclose the input style, the operation, and the return format ('human-readable verification summary followed by the full structured result as JSON'). However, it does not mention failure modes, error conditions, or whether the tool is strictly non-mutating beyond what the operation inherently implies.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded with the primary purpose, followed by a clear usage condition, parameter details, and returns. Every sentence contributes value without repetition or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter tool with an output schema, the description covers the decision context, parameter semantics, and expected return shape. No critical information for invoking the tool correctly appears to be missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description fully compensates. It specifies file_hash as 'hex-encoded SHA-256 hash' and proof_json as 'a JSON string, OR a path to a proof JSON file', adding meaningful format and alternative-value semantics not present in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and object: 'Verify a known file hash against inline proof data.' It further clarifies the scope by noting the agent already has the hash and proof content and does not need to read a file from disk, which distinguishes it from siblings like verify_file and compute_file_hash.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use the tool: 'Use this when you already have a file's SHA-256 hash and the proof content... and do not need to read a file from disk.' This gives a clear usage context and an implicit when-not condition, but it does not name alternative sibling tools explicitly, so the guidance isn't quite at the level of directly routing to an alternate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.1create_proofv0.1.0compute_file_hashexplain_proofverify_fileverify_hashScored across 5 tools
Most tools have distinct actions: compute, explain, create, verify. The only real ambiguity is between verify_file and verify_hash, which both verify a proof and differ mainly in whether input is a file path or a precomputed hash; a weak agent might select the wrong one.
All tool names follow the same lowercase verb_noun pattern: compute_file_hash, explain_proof, create_proof, verify_file, verify_hash. The repeated verify verb is consistently disambiguated by the object (file vs hash).
Five tools is well-scoped for the domain of blockchain timestamp proofs. Each tool covers a meaningful step in the workflow and none feels redundant or unnecessary.
The set covers hashing, proof creation, explanation, and verification, but there is a notable integration gap: create_proof returns only a summary and URLs, while verify_file, verify_hash, and explain_proof all require a proof JSON file. A user who creates a proof cannot directly verify it within the toolset unless they obtain the proof JSON externally.
Prove a web page or document existed on a date: public SHA-256 registry anchored in Bitcoin. Free.
Mark: stamp files with a signed, timestamped provenance record. Hash locally; verify free.
Timestamp & verify evidence on-chain, free. Proofpack: a portable BEEF+BUMP proof bundle per txid.
Stamp or notarize data into a public witnessed transparency log. Proves timing, not truth.
