Provenance envelopes for tool results, plus an anti-inflation gate for the tool surface itself.
Two small, composable pieces for any tool surface — an MCP server, an RPC layer, an agent tool-call loop:
-
Stamp every tool result with a provenance envelope so the answer travels with its reasoning and its trust level:
Envelope key Contents _toulmina Toulmin argument — claim/grounds/warrant/qualifier/rebuttal_tagsfour provenance dimensions — scope/signal_type/attribution/uncertainty -
Triage the surface MECE into
{real_dispatch, read_only, native_only}and gate it withdrift_check, so no exposed tool is ever unclassified or double-counted.
A tool surface returns answers; a governed tool surface returns answers plus the reasoning and the trust level that let a caller filter, escalate, or audit them — and it never overstates what it can do. This library makes both structural with one ~250-line, zero-dependency package:
- Every result self-describes.
stamp(result, toulmin=…, tags=…)is non-destructive — the payload passes through untouched and the envelope is added — so retrofitting provenance onto an existing surface is a one-line wrap, not a schema migration. - The surface can't inflate.
drift_check(registry, classification)fails CI the moment a tool is exposed but unclassified, or appears in two buckets. The honest "how many tools actually execute" count (real_dispatch + read_only) is derived, not asserted — so "we expose N tools" can never quietly mean "N tools that look like they do something." The three buckets are a fixed contract; the tools are entirely yours.
pip install -e .Zero runtime dependencies — pure standard library, Python 3.9+. The envelope value objects (a Toulmin argument and a four-dimension tag block) are vendored under _vendor/ (see KERNEL_SYNC.md).
from mcp_tool_provenance import (
stamp, make_tags, ToulminArgument, QualifierLevel, DataAvailability,
triage, drift_check, assert_no_drift, surface_summary,
)
# 1) Stamp a tool result — non-destructive.
out = stamp(
{"records": [1, 2], "count": 2},
tool_name="read-records",
toulmin=ToulminArgument(
claim="Two records matched", grounds="Key resolved to two rows",
warrant="A key matching N rows returns them", qualifier=QualifierLevel.CERTAIN,
rebuttal="A row could be soft-deleted after this read",
data_availability=DataAvailability.SUFFICIENT,
),
tags=make_tags(scope="tenant_specific", signal_type="operational",
attribution="read-records-tool", uncertainty="low"),
)
out["_toulmin"] # 5 keys out["_tags"] # 4 keys out["records"] # untouched
# 2) Triage the surface and gate it.
registry = ("create-record", "read-record", "list-records", "draft-guidance")
surface = triage(
real_dispatch=("create-record",),
read_only=("read-record", "list-records"),
native_only=("draft-guidance",),
)
assert_no_drift(registry, surface) # raises if any tool is mis/unclassified
surface_summary(registry, surface)["executes_server_side"] # honest "really does something" countstamp(result, *, toulmin, tags, tool_name="")/is_stamped(result)— the non-destructive envelopeToulminArgument,QualifierLevel,DataAvailability,ArtifactTags,make_tags— vendored envelope value objects, re-exportedtriage(real_dispatch=, read_only=, native_only=)— build a MECE surface mapdrift_check(registry, classification)/assert_no_drift(...)— the anti-inflation gate (report / raise)surface_summary(registry, classification)— the honest, reportable splitBUCKETS,DriftReport,DriftError
Full reference: docs/API.md. Adapting it to your surface: docs/FORKING.md. Why it matters: docs/MOAT.md.
MIT — see LICENSE.
Powerweave Skunkworks is the AI R&D division of Powerweave Software Services — a rapid-innovation lab that turns real-world product feedback into working, reusable, open-source building blocks. Working in parallel to the main engineering backlog, a lean, cross-functional team of product and technology specialists (UX, data, software engineering, and AI) fast-tracks high-priority ideas into validated modules ready for full-scale build-out.
mcp-tool-provenance is one such building block — a de-domained, MIT-licensed, dependency-light component extracted from Powerweave's internal R&D and engineered to be forked into any SaaS or enterprise product.
- 🧪 Powerweave Skunkworks on GitHub — https://github.com/skunkworks-powerweave
- 🌐 Powerweave — https://powerweave.com
- 💼 Powerweave on LinkedIn — https://www.linkedin.com/company/powerweave
Powerweave Software Services Pvt. Ltd. is a digital-transformation company founded in 2001 and headquartered in Mumbai, India. With 25+ years of experience, 1,700+ professionals, and 350+ global customers, Powerweave builds platforms, processes, and teams across enterprise eCommerce, AI-powered procurement, Microsoft Dynamics ERP, business services, and sustainability — with a strong focus on cutting-edge AI automation that streamlines workflows, reduces manual errors, and accelerates decision-making. Powerweave is ISO 27001:2013 certified.
Explore Powerweave
- 🌐 Website — https://powerweave.com
- 💼 LinkedIn — https://www.linkedin.com/company/powerweave
- 𝕏 Twitter / X — https://twitter.com/powerweave
▶️ YouTube — https://www.youtube.com/channel/UCE1t_rg38z4n5BAg29PDZFA- 📘 Facebook — https://www.facebook.com/PowerweaveSoftwareSolutions/
- 🛒 Enterprise eCommerce — https://www.powerweave.com/solutions/enterprise-ecommerce/
- 📦 AI-Powered Procurement — https://www.powerweave.com/solutions/procurement/
- 🧮 Microsoft Dynamics ERP — https://www.powerweave.com/solutions/microsoft-dynamics-erp/
- 🌱 Snowkap — Sustainability — https://www.snowkap.com/
- 🎨 Powerweave Studio — https://www.powerweavestudio.com/
- 🧑💼 About Us & Leadership — https://www.powerweave.com/about-us/
- 🚀 Careers — https://www.powerweave.com/careers/
Keywords: mcp · provenance · tool · governance · audit · toulmin · tagging · drift · Powerweave · Powerweave Skunkworks · AI R&D · open source · MIT · Python · forkable.