Verax is a policy-gated MCP server that sits between an agent and its tools, signing a decision record for every call before it runs.
Store and recall memory — memory.put writes a JSON value under an id, with a source and a validUntilMs; memory.get reads it back, withholding stale or not-yet-valid bodies and denying other tenants' ids.
Read the inbox — message.read returns this tenant's queued messages oldest-first (or []).
Queue outbound messages — message.send puts a message in the outbox for a later delivery step; it opens no network connection, and the recipient host must be on the policy's egress allow-list (denied:egress-blocked) or the call is held for an operator.
Request payment authorization — spend checks amount, currency, payee and reference against the policy (cap, payee list, daily limit, single currency) and records a signed permission; it never moves money, and out-of-bounds calls are denied (denied:spend-cap, -payee, -currency, -daily).
Audit any decision — audit.explain reads a decision back from the signed ledger by its ref, showing the signed record, its reconciled effect, match/mismatch findings, witness class and trust root.
Defer risky calls to a human — calls the policy holds wait for verax approve on the machine or a passkey through the operator door, then succeed on resend with the same _ref (allowed:<ref>).
Everything is gated and signed — every call, including refusals, leaves a signed decision record in a local ledger, and held calls carry a deferred:approval-required:<ref> you can look up later.
Publishes the veraxai/verax container image for the MCP server.
Used to generate the voices for the animated sample scenario episodes.
Distributes the @verax-ai/body package that implements the MCP server.
Used to draw the scenes in the animated sample scenario episodes.
Hosts the DOI-archived record of the Verax project.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Verax Approve the tool call get_user and record the signed decision and effect row."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
The body an agent asks before it acts.
Listed on: npm · Glama · MCP Registry · MCP Market · mcp.so · Docker Hub · Zenodo
Verax is an MCP server that sits between an agent and its tools. Every tool call passes a policy gate and leaves a signed decision record before anything runs; every call that ran leaves an effect row that is reconciled against its record afterwards. A refusal is recorded the same way as an approval. A call the policy will not decide alone is held until an operator approves it, at this machine or, with the operator door set up, from another device with a passkey. The ledger stays on the machine the body runs on, and the body opens only when its authorization is configured: there is no default token.
Break it, and we pay. USD 100 for each valid report of a way for the agent's account to get a refused call allowed, run a call with no decision record, or change the service's code, keys or ledger. The budget is USD 500 in total. Terms: SECURITY.md.
By VERAX Teknoloji. Sister projects: Conarium · Tugra · Cedulon. Decision records use the Cedulon record format.
How Verax compares, dated 15 October 2026: of 40 projects that gate, log or approve an agent's tool calls, nine are compared on four questions with a source for every cell, and the page says where Verax falls short: verax-ai.com/compare.html.
npx @verax-ai/body demo
The recording is the output of one run in a terminal where the approval
question was answered y and the amount was typed. That run took about a
second; it is played back slowly here so it can be read.
What it prints, without a terminal to answer the approval question:
verax demo
memory.put / memory.get
allowed; two signed records
message.send -> ops@blocked.test
refused egress-blocked (signed)
ref 6c6e4925-b769-4a8b-8fc4-e2443613a5b6
spend 100 minor USD sample-merchant
held
no terminal to ask, so it stays held (run this in a terminal to be asked)
audit.explain of the refuse
finding none
trust-root own-key
chain and signatures read back
records 5
effects 3
ledger removed on exit (run with --keep to keep it and check it with verax verify)
Not shown here: data masking arrives with a downstream server such as Conarium; statement reconciliation needs a real statement (verax reconcile).Node 22.6 or newer, @verax-ai/body 0.2.1 or later. The command records an
allowed memory write and read, a
signed refuse of a message to a host off the policy list, and a payment held
for the operator on this machine (approved when the terminal answers y and
then types the amount, 100; up to 0.5.0 the demo did not print that second
question).
--keep leaves the temporary ledger on disk. verax verify <dir> reads it
back without a body, as in Read the ledger back without us.
To keep it and check it:
npx @verax-ai/body demo --keep
npx -y -p @verax-ai/body verax verify <the directory it printed>Four short episodes show the same gate, with characters in place of a terminal. They are sample scenarios: the scenes are drawn in three.js and the voices are generated with ElevenLabs.
Episode 1, "$1,850": a payment is held until a person approves it on a phone, and changing one cent in the record breaks its signature.
https://github.com/user-attachments/assets/772ae1c4-2697-47a0-a228-36f0508b0d93
Episode 2, "No rule, no way through": a call with no rule is refused, the same call under a new name is refused again, and both refusals are signed.
https://github.com/user-attachments/assets/4fb86627-3310-4f10-b1a9-059d8fcffb28
Episode 3, "The red lever": an operator halts the body, every later call is refused and signed, and a call that was already running is not cut off.
https://github.com/user-attachments/assets/8d19eed9-3359-46b3-bd77-f2b1b1c4dd75
Episode 4, "Who approved?": a held spend waits for verax approve on the
machine, the agent cannot approve it, and the approver's operator id goes into
the record.
https://github.com/user-attachments/assets/0b8aade4-a970-4b63-835e-4837e2a39cc9
Related MCP server: Secure Agent MCP Gateway
Elevated verax install and verax approve run a copy of this program that only an administrator can change; a copy your account can change is refused. On Windows a passkey through the operator door (verax install --operator-door <origin>) approves without an elevated shell; without the door, an elevated CLI approve is the way. It has to be run from a separate administrator account, not this account elevated, because a same-user elevated shell inherits that user's environment variables and PowerShell profile, which the agent can set. Clear NODE_OPTIONS in that shell (Remove-Item Env:NODE_OPTIONS). Start that other account's PowerShell with -NoProfile (an elevated shell otherwise runs your $PROFILE, which your account can change):
npm install -g --prefix "$env:ProgramFiles\verax-cli" @verax-ai/body
& "$env:ProgramFiles\verax-cli\verax.cmd" installOn Linux and macOS, with a root-owned Node (the distribution's /usr/bin/node, or /opt/verax-node/<dir>/bin/node; the installer prints those steps when the Node it was started from can be changed by your account). Do not start an elevated command with env node:
sudo npm install -g --prefix /opt/verax-cli @verax-ai/body
sudo /usr/bin/node /opt/verax-cli/lib/node_modules/@verax-ai/body/dist/cli.js installThe command installs @verax-ai/body from the npm registry into an administrator-owned directory after signature checks, runs that Node, and keeps the ledger under a service account. On Windows the agent token is %ProgramData%\Verax\agent-token\<your SID>\agent.token (Administrators and SYSTEM have full control, your SID can read the file and read-execute the directory). On Linux and macOS a child process running as your uid writes ~/.verax/agent.token from its stdin. It prints the Claude Code line that reads that file. Port 8787 taken? verax install --port 8797. Node must be the all-users installer from nodejs.org on Windows; a Node your account can rewrite is refused. On macOS the remedy extracts the official tarball as root into /opt/verax-node (root:wheel, not group- or other-writable). On Linux the same place, /opt/verax-node (root:root), which SELinux labels usr_t. On SELinux systems install requires Node labelled bin_t or usr_t (distribution Node is; a tarball under /usr/local/lib is not) and prints the one-line fix. The service then runs in unconfined_service_t. The service account and the file permissions are the boundary.
Approve a held call with verax approve, or, when the install named an origin with --operator-door, from another device through the operator door with a passkey enrolled by a pairing code from verax operator enroll. The passkey panel (verax desktop) is not released yet. On Windows run the approve from a separate administrator account, not this account elevated, in a -NoProfile PowerShell after Remove-Item Env:NODE_OPTIONS: & "$env:ProgramFiles\verax-cli\verax.cmd" approve. Linux and macOS, naming the root-owned Node: sudo /usr/bin/node /opt/verax-cli/lib/node_modules/@verax-ai/body/dist/cli.js approve or sudo /opt/verax-node/<dir>/bin/node /opt/verax-cli/lib/node_modules/@verax-ai/body/dist/cli.js approve. Uninstall the same way, with uninstall in place of approve.
To try it in your own user, which is not a boundary:
verax init --local ~/.verax
verax serve --env-file ~/.verax/verax.envclaude mcp add --transport http verax http://127.0.0.1:8787/mcp --header "Authorization: Bearer $(cat ~/.verax/local-issuer/agent.token)"The token can read and write memory through the gate; it cannot approve. The shipped policy refuses spend until you add a rule for it; a call your policy holds waits for verax approve on this machine, or for an approval through the operator door when one is set up. See docs/THREAT_MODEL.md.
@verax-ai/body 0.2.2 and later accepts --with-conarium. 0.2.1 does not
carry the flag. The flag has npx download @conarium-ai/core from npm and
run it as a child process; that needs a network.
Conarium masks the rows, and its sample policy denies its public.secrets
table. Verax puts each call through the same gate as its own tools, keeps a
signed record and a hash of the answer, and refuses a downstream tool the
policy does not name before the child sees the call. When Conarium answers
with an error, the body tells the caller that it did, not what it said.
What it prints, without a terminal to answer the approval question:
verax demo
memory.put / memory.get
allowed; two signed records
message.send -> ops@blocked.test
refused egress-blocked (signed)
ref 6c6e4925-b769-4a8b-8fc4-e2443613a5b6
spend 100 minor USD sample-merchant
held
no terminal to ask, so it stays held (run this in a terminal to be asked)
conarium.query customers
allowed; masked by Conarium before the rows left it
measured [MASKED_PII] on every email and card
conarium.query public.secrets
allowed by this gate; Conarium answered with an error and no rows
recorded as a failed call
conarium.list_tables
refused no-rule (signed)
refused by this gate; the downstream server never saw the call
audit.explain of the refuse
finding none
trust-root own-key
chain and signatures read back
records 8
effects 5
ledger removed on exit (run with --keep to keep it and check it with verax verify)
Not shown here: a real database (these are Conarium's sample rows); statement reconciliation needs a real statement (verax reconcile).Package | What it is |
The MCP server and the | |
The decision proxy the body is built on: policy, signed records, ledger, | |
The roster document a body serves and the panel lists, with its strict parser. |
The three packages are published together and carry the same version; the
capability matrix in docs/STATUS.md names the current one,
and it is the version on npm. The body is also listed in the MCP registry as
io.github.verax-ai/verax. What that version carries, what it does not,
and the test holding each row up are in the capability matrix at the top
of docs/STATUS.md.
A ledger only the vendor's running service can read is evidence a buyer
rents, not evidence they hold. verax verify reads a state directory on
its own — no body listening, nothing on the network — and states each
check on its own line, because they fail separately. On a copy of the
ledger npx @verax-ai/body demo --keep leaves behind, 0.6.0 prints:
$ verax verify ./verax-state
ledger ./verax-state
decisions 5
effects 3 (3 bound to a decision, 0 with none)
signatures 5 verify, 0 do not
chain unbroken
verified with the key carried in these files
verified against the key carried in the records themselves: this shows the files are internally consistent, not that the key was ever trusted. Pin a key you hold to check that.
effects with the key carried in these files
verified against the key carried in the self effects themselves: this shows the files are internally consistent, not that the key was ever trusted. Pin a key you hold to check that.
same-org with no key
no same-org effects, so no witness key was used
checkpoints with no key
no checkpoints, so no checkpoint key was used
index: 5 ref(s), each still a decision
effect completeness checked
inputs: 5 record(s), each with its inputs row
tail: no checkpoint; removing the newest records with their effects is not detectable from these files
control: no control records
anchors: none (no checkpoint is registered with a transparency service)
approval signatures signed-verified 0 · signed-failed 0 · unsigned-http 0 · cli 0
no operator key was found in these files
control signatures signed-verified 0 · signed-failed 0 · unsigned-http 0 · cli 0 · file 0
starts 1; largest gap none; previous beat missing at 1792241614080; 1 of 1 signed verify under the in-ledger record key
VERIFIEDThe demo approves nothing and halts nothing, so both signature counts are zero; an
approval given through the operator door is counted on the approval signatures line (remote approval). tail
and anchors are about checkpoints, below. starts summarizes the
heartbeat (Watch for silence).
The verified with the key carried in these files pair is the point. Checking a ledger against the key
lying next to it proves the files agree with each other and nothing more —
anything able to write the ledger could write that key too. Pass
--key <public.pem> to verify decision records against a copy you hold, and
the answer says a key you supplied instead. Effects are signed with a
separate key. A self row is checked under the effect key: --effect-key <public.pem>
when you pin it, otherwise one key taken from the first self row. A same-org
row is checked under the witness key: --witness-key <public.pem> when you pin it,
otherwise one key taken from the first same-org row. Pinning --effect-key while
a same-org row is present requires --witness-key as well, and pinning
--witness-key while a self row is present requires --effect-key as well;
otherwise the result is not verified. Each of those lines says the
same thing: the files agree with each other, not that the key was ever yours.
Checkpoints are signed by the witness key. Every checkpoint row is checked under one key: --checkpoint-key <public.pem> when you pin it, otherwise one key taken from the checkpoint file, with the same note that agreement is not trust. The tail counts only checkpoints whose signatures verified. Someone who can rewrite the files can still roll that file back to an older valid prefix together with the records after it; only a checkpoint held elsewhere detects that. --json prints
the same result for a
pipeline; the exit code is 0 when it verifies and 1 when it does not, and a
directory with no ledger in it is never quiet success.
Records are COSE_Sign1 with algorithm -19 (Ed25519, RFC 9864), not the
older polymorphic -8 (EdDSA). Some COSE libraries do not know -19 yet:
as of go-cose 1.3.0 and pycose 1.1.0 both reject it, and support is tracked
in go-cose#224 and
pycose#126.
verax verify does not depend on either library.
test-vectors/ is a frozen set of ledgers, each with
the verdict and the stage a verifier should report. Two people have run the set
at vectors-v1 with verifiers of their own and posted the results:
Tymofii Pidlisnyi (Agent Passport System), with a runner in the APS conformance suite: a partial, stage-by-stage comparison across all 16 vectors, not a whole-ledger verdict (run).
Roberto Locatelli (cryptovalid-opencore), with clean-room checkers written from the drafts, the RFCs and the vector README: with the checkpoint verified under the witness key, 16 of 16 verdicts and 15 of 16 first failing stages. One of those matches came from a rule added after reading the vector, as the run itself states (run).
A matching run shows that another verifier reads these encodings and reaches the same verdict at the same stage. It is not an independent audit of the body.
npm install -g @verax-ai/body
verax --help
verax doctorA host that cannot reach the npm registry can install from an offline bundle; the steps are in docs/OFFLINE_INSTALL.md.
On an account where every process is elevated (the built-in Administrator, or EnableLUA=0), a command from a user-writable npm prefix is refused; use the administrator-owned copy at %ProgramFiles%\verax-cli.
Node 22.6 or newer. The body speaks MCP over Streamable HTTP at /mcp on
VERAX_BIND (default 127.0.0.1:8787) and needs an issuer, a JWKS URL, an
audience, a state directory and a policy file before it listens; verax doctor names what is missing. The variables and the run steps are in
packages/body/README.md.
The policy decides which of these a token's scopes may call;
packages/proxy/policy/default.json denies what it does not name.
Tool | Description |
| Reads one memory item behind the gate, stored per tenant. |
| Writes one memory item behind the gate, stored per tenant. |
| Reads a decision back from the signed ledger, with its chain, its signatures and its findings. |
| Reads the inbox. |
| Writes to the outbox; reaches only hosts the policy allow-lists. |
| Authorizes a payment and records it, under a cap, a payee list and a daily limit from the policy; held for an operator when the policy says so. The body does not move money. |
Each line below is a row in the capability matrix in
docs/STATUS.md, where it is stated against a version,
with what it does not do and the test that fails when it stops being
true.
Approval: a held call is approved with verax approve on this
machine, or through the operator door from another device with a passkey
and an assertion for that request; the door is off unless an origin is
named for it. On Windows the CLI approve runs from a separate
administrator account. The passkey panel behind verax desktop is not
released yet. The approver's operator id is bound into the signed record
by hash.
Witness: verax witness signs effect rows from a second process and writes
durable checkpoints; without it the witness class stays self.
Halt and revoke: verax halt turns every further call into a signed deny;
a revoked token id is refused before any record is written.
Reconcile: verax reconcile matches recorded spends against a card
statement export and names the matched, ghost and authorized-but-unpaid
rows.
Tenant key: memory and inbox are stored under a key derived from the token's issuer and subject; another tenant's id is answered with a signed deny.
Bounds: rate and daily counters, a disk-low refusal (HTTP 507) when a deny could not be recorded, and an egress allow-list; counters that cannot be read fail closed.
Doctor and heartbeat: verax doctor names what is missing or stale before
the first call finds out.
The running body pulses even while idle (10 s by default;
VERAX_HEARTBEAT_EVERY_MS, minimum 1,000 ms). Start rows in starts.jsonl
record gaps from the previous beat; verax verify <stateDir> summarizes
them offline. Since 0.5.0 start rows are signed by the record key.
verax watch ./verax-state --max-silence 30s
verax watch ./verax-state --once
verax watch --url https://host/healthz --token-file ./audit.token --once
verax watch ./verax-state --on-silence exec --exec "node isolate.mjs"An unreadable, stale or far-future beat is silence. A local watch halts by
default; recovery never resumes it. An operator must use the existing
resume path. Remote watch reports silence and cannot halt remotely. Tokens
are read only from files; HTTPS is required except on loopback. An exec
command runs once per silence episode with VERAX_WATCH_REASON in its
environment, without a shell. Quote executable/arguments containing spaces.
--once exits 0 live, 3 silent or 2 on usage errors. Continuous watch prints
one JSON line per silence episode and recovery, polling at max-silence/3.
Run it where the operator chooses; a same-host watcher shares that host's
trust and is not independent evidence if both ledger and watcher vanish.
The body listens on http://127.0.0.1:8787/mcp by default. A client
configuration looks like this; the token comes from your issuer.
{
"mcpServers": {
"verax": {
"url": "http://127.0.0.1:8787/mcp",
"headers": { "Authorization": "Bearer <token from your issuer>" }
}
}
}What the tree carries and what stays unproven is stated, item by item, in
docs/STATUS.md. Nothing in this repository is a claim
beyond that file, and a paragraph there is not a release. The threat model is
in docs/THREAT_MODEL.md; how to report a
vulnerability is in SECURITY.md.
apps/panel is the account-for screen: the records list, the black box and
the status view, read from the signed ledger. Private; it is not published.
The panel session uses the code flow; the access token stays in memory and
is dropped on refresh. Vite may still attach VERAX_DEV_TOKEN from
.env.local to /api when the request has no Authorization header
(desktop MCP brains and tests).
scripts/dev-issuer.mjs is development only; not a production
authorization server. It serves GET /authorize (PKCE S256) and
POST /token, writes a token to --out, and never prints one. It listens
on VERAX_DEV_ISSUER_PORT (default 8790). NODE_ENV=production exits.
scripts/demo-box.mjs is development only: one process that starts the
dev issuer and the body on loopback with a temporary ledger, mints itself a
short-lived token through the issuer's code flow, and speaks MCP over stdio
for a sandbox that cannot hold a token of its own, such as a directory's
build check. The body is not changed by it: every call still passes the
gate and is recorded, spend is always held, and no operator is there to
approve it. NODE_ENV=production exits. Not a deployment.
npm ci
npm test # guards, build, typecheck, unit and cost suites, panel
npm run pack:smoke # pack the three packages and install them elsewhereCI runs the suite as a non-root user on Linux and again on Windows, plus the
proxy performance check. Releases go out from the Actions tab:
release.yml publishes the three packages with npm trusted publishing and a
provenance attestation, then mcp-registry.yml updates the registry record
once npm answers for the new version. Neither runs on push.
Tested on every release on the platforms listed in docs/PLATFORMS.md, each row linked to its CI run.
To contribute, or to report a run on a platform that is not listed, see CONTRIBUTING.md.
Apache-2.0.
Reads one decision back from the signed ledger by its ref and explains it. Use it to check what the body decided about an earlier call and whether the recorded effect matched, before repeating a call or reporting on it; read-only, and the lookup itself is recorded too. Returns JSON with record (the signed decision's claims: tool, verdict, policy hash, timestamps), effect (the reconciled effect row), finding (match, mismatch or missing), witnessClass, guarantee, warnings, trustRoot (which key verified the signatures), and for a held call pair with its defer and resolution records. A ref that does not exist, or belongs to another tenant, is answered with the same signed deny, so neither case reveals the other.
| Name | Required | Description | Default |
|---|---|---|---|
| ref | Yes | The decision reference: the ref returned by an earlier call, also the tail of a denied:… or deferred:… answer; 1 to 64 characters of letters, digits, '.', '_' or '-', starting with a letter or digit. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does so thoroughly. It discloses the read-only nature, the side effect that the lookup is recorded, and the security behavior of returning a signed deny for both non-existent and other-tenant refs to avoid information leaks. This is exemplary behavioral disclosure.
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 dense but well-organized, moving from purpose to usage, return fields, and edge-case behavior. It is longer than minimal, yet every sentence contributes essential information and nothing feels redundant or off-topic.
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 single-parameter tool with no output schema, the description fully explains the return shape: record, effect, finding, witnessClass, guarantee, warnings, trustRoot, and the held-call pair case. Error semantics are also covered with the signed-deny behavior. An agent has everything needed to call and interpret the tool correctly.
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 100%, so baseline is 3, but the description adds practical semantics beyond the schema: the ref is the one returned by an earlier call, or the tail of a denied/deferred answer. This helps the agent locate the correct value to pass.
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?
States a specific verb and resource: reads a signed ledger decision by ref and explains it. The tool's focus on auditing decisions is clearly distinct from sibling tools handling memory, messaging, and spending, so an agent can tell them apart immediately.
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?
Explicitly says when to use it: to check what the body decided about an earlier call and whether the effect matched, before repeating or reporting on it. It also notes the lookup is recorded, which is a useful side-effect warning. No alternatives are named, but the siblings are unrelated so exclusions are not necessary.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reads one memory item this tenant stored earlier with memory.put, by its id. Use it to recall a fact, a setting or a note before acting on it; nothing is written. Like every call it passes the policy gate and leaves a signed decision record; an id that belongs to another tenant is answered with a signed deny. Returns the stored item as JSON: {id, revision, body, source, validFromMs, validUntilMs, versionHash} when it matches the signed memory commit for this tenant. Outside the validity window the body is withheld: {stale: true, id, validUntilMs} after it, {notYetValid: true, id, validFromMs} before it. An unknown id answers {error: "not-found", id}. A changed, missing, or uncommitted item answers {error: "memory-integrity-mismatch"|"memory-integrity-missing"|"memory-integrity-unattested"|"memory-integrity-history-unavailable", id} and does not include body or source.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The id given to memory.put: 1 to 128 characters of letters, digits, '.', '_' or '-', starting with a letter or digit; case-sensitive. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does so well: it discloses the policy gate, signed decision record, cross-tenant signed deny, stale and not-yet-valid withholding behavior, integrity failure modes, and exactly what is returned in each case.
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 front-loaded with purpose and usage, followed by behavioral and return-value details. It is somewhat long for a one-parameter tool, but the length is justified because there is no output schema and the error/return shapes matter.
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 read tool with no annotations and no output schema, the description is complete: it covers purpose, usage, authorization behavior, tenant isolation, stale-window behavior, success payload, and error payloads.
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?
The schema fully documents the id format, so the baseline is 3. The description adds meaning by linking the id to memory.put, noting tenant ownership implications, and specifying that another tenant's id receives a signed deny.
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?
States a specific verb and resource: reads one memory item by id. It explicitly ties the item to memory.put and clarifies that nothing is written, which distinguishes it from sibling mutation and messaging 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?
Gives clear usage context: recall a fact, setting, or note before acting on it. It also notes the item must have been stored earlier with memory.put. It does not explicitly compare against alternatives such as audit.explain, but the usage context is otherwise clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Writes one memory item for this tenant, or replaces the item with the same id, in the body's state directory on this machine. Use it to keep a fact for a later memory.get together with where it came from and how long it holds, so a stale fact is not served later. The call passes the policy gate and is recorded; the record carries the item's versionHash, a SHA-256 over a v2 envelope of tenant, id, revision, body, source and validity window. Each write is a new revision file; the previous file is removed only after a signed commit line is appended. Returns {ok: true, id, revision, versionHash}. A missing source answers {error: "source-required"}, a missing validUntilMs {error: "validUntilMs-required"}, a malformed id {error: "id-invalid"}.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Identifier to store under and read back with memory.get: 1 to 128 characters of letters, digits, '.', '_' or '-', starting with a letter or digit; case-sensitive. An existing item with this id is replaced. | |
| body | Yes | The value to keep, as any JSON: object, array, string, number or boolean. Stored as given and returned as given by memory.get. | |
| source | Yes | Where the value came from, as a JSON object of your choosing, for example {"kind": "document", "ref": "invoice-2026-09.pdf"}. Required; stored with the item so a later reader can weigh it. | |
| validFromMs | No | Optional. Unix time in milliseconds from which the item may be served; before it memory.get answers notYetValid. Omit to serve it at once. | |
| validUntilMs | Yes | Required. Unix time in milliseconds after which memory.get answers stale and withholds the body. Pick the moment the fact should no longer be trusted. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden and does so well: it discloses the policy gate, recording, revision-file behavior, signed-commit ordering, versionHash computation, return shape, and specific error responses. It also explains that source and validUntilMs are required, making failure behavior predictable.
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 front-loaded with the write/replace operation, then moves to usage, behavioral guarantees, return shape, and errors. Despite its length, every sentence adds information useful for selecting or correctly invoking a complex mutation tool with no annotations or output schema.
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 five-parameter mutation tool with nested objects, no annotations, and no output schema, the description is complete: it covers purpose, when to use, policy/recording behavior, versioning, persistence, return values, and common error outcomes. An agent has enough context to call it correctly.
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 100%, so the schema already documents all five parameters thoroughly, including id constraints, body flexibility, source purpose, and validity windows. The description adds error cases and versionHash context but does not significantly extend parameter semantics beyond what the schema provides.
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 states a specific verb and resource: it writes one memory item for this tenant and replaces an existing item with the same id. It also names the related memory.get tool, so an agent can distinguish this write operation from the later read path.
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?
It gives a clear intended use: keep a fact for a later memory.get with source and validity so a stale fact is not served later. It does not explicitly state when not to use the tool or name alternatives, but the context is clear for a write tool in a memory workflow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reads this tenant's inbox, the messages placed for it in the body's state directory on this machine, and returns them as a JSON array in arrival order, oldest first. Use it to see what has arrived before deciding what to answer. Takes no arguments; read-only; the call is recorded like every other. An empty or absent inbox answers [].
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the read-only nature, that the call is recorded, and that an empty inbox returns [] – all beyond what the schema shows.
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 succinct, front-loads the core action (reads inbox), and includes necessary behavioral notes without fluff.
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 zero parameters, no output schema, and no annotations, the description fully covers what an agent needs to know: what it does, when to use it, and the return format.
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?
There are no parameters, so there is nothing to add. The schema coverage is 100%, and the description confirms no arguments are needed, which is sufficient.
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 the tool reads the tenant's inbox and returns messages as a JSON array. However, it does not explicitly differentiate from sibling tools like message.send or memory.get, though the read-only nature is implied.
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 says to use it before deciding what to answer, which gives some context. But it does not mention when not to use it or compare with alternatives like memory.get.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Queues one message in this tenant's outbox on this machine for the delivery step the operator runs; this call opens no network connection and nothing leaves the body from it. Use it to hand off a message, not to deliver one. Like every call it passes the policy gate and leaves a signed decision record. The gate reads the host after the last '@' in to and allows it only when it is on the policy's egress allow-list; otherwise the call is refused with denied:egress-blocked, or denied:egress-host-missing when no host can be read. A policy rule in approve mode holds the call for an operator instead and answers deferred:approval-required:. Returns {queued: true, ref}, where ref is the decision reference for audit.explain.
| Name | Required | Description | Default |
|---|---|---|---|
| to | Yes | Recipient address with a host after the last '@', for example ops@example.com. The host, lower-cased, is matched against the policy's egress list. | |
| _ref | No | Optional reference you choose for this call, 1 to 64 characters of letters, digits, '.', '_' or '-', starting with a letter or digit. Resend the same call with the same _ref after an operator approved it to receive allowed:<ref>; a _ref reused for a different call is refused with denied:ref-reuse. | |
| text | Yes | The message body as plain text. Stored as given in the outbox row. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full disclosure burden, and it does so thoroughly: no network connection is opened, nothing leaves the body, the policy gate is passed, a signed decision record is left, and refusal/deferral outcomes are specified. This gives a complete behavioral picture.
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 dense but every sentence earns its place: core behavior, usage guidance, policy outcome, approval behavior, and return value. The most important disambiguation—queueing rather than delivering—is front-loaded.
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?
Despite having no output schema and no annotations, the description fully specifies the return shape, error/refusal statuses, approval flow, and policy context. An agent has enough information to invoke this tool correctly and interpret its result.
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 100%, so the baseline is 3, but the description adds useful meaning: the host is lower-cased and checked against the egress allow-list, and the _ref interaction with operator approval and ref-reuse refusal is clarified. This goes beyond the schema without being redundant.
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 uses a specific verb and resource: it 'queues one message in this tenant's outbox on this machine' and explicitly says it is not delivering the message. This clearly distinguishes it from message.read and from any actual network-send behavior the name 'send' might imply.
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?
It explicitly states when to use the tool ('Use it to hand off a message, not to deliver one') and points to the operator-run delivery step as the separate follow-up. It also explains policy approval/deferral behavior so the agent knows when the call will be queued versus held for an operator.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Asks the body to authorize a payment and records the decision; the body never moves money, so authorized: true is a signed permission for a later payment step, not a transfer. Use it before any payment so that amount, currency, payee and reference are checked against the policy: the one currency the policy names, a cap per call, a payee list and a daily limit. A call outside those bounds is refused with a signed deny naming the bound: denied:spend-cap, denied:spend-payee, denied:spend-currency or denied:spend-daily. A call within them is held for an operator on this machine and answers deferred:approval-required:; once that ref is approved (verax approve, or the panel), resending the same call with the same _ref answers allowed:, and the authorization is recorded as {authorized: true, ref, amountMinor, currency, payee, reference}. Without a spend rule in the policy every call answers denied:spend-not-wired.
| Name | Required | Description | Default |
|---|---|---|---|
| _ref | No | Optional reference you choose for this call, 1 to 64 characters of letters, digits, '.', '_' or '-', starting with a letter or digit. Resend the same call with the same _ref after an operator approved it to receive allowed:<ref>; a _ref reused for a different call is refused with denied:ref-reuse. | |
| payee | Yes | Who is to be paid, spelled exactly as the policy's payee list spells it (a merchant or account name). A payee off the list is refused. | |
| currency | Yes | ISO 4217 code in upper case, for example USD, EUR or TRY. Must equal the currency the policy's spend rule names. | |
| reference | Yes | Your own reference for this payment, such as an invoice or order id. Recorded with the authorization; verax reconcile does not read it, and matches a card statement row by a verax:<ref> in its description, amount, currency and time. | |
| amountMinor | Yes | Amount in the currency's minor unit as a positive integer: cents, kuruş or pence, so 1250 means 12.50. Compared against the policy's cap per call and daily limit. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the full burden and does so thoroughly: it discloses the non-transfer semantics of authorized:true, the four policy bounds, the specific deny codes for each bound, the deferred/operator-approval path with its response strings, and the unwired-policy fallback (denied:spend-not-wired). It even documents the idempotent resend requirement.
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?
It is front-loaded with the key distinction (authorization vs transfer) and every sentence carries operational information about bounds or responses. It is dense and long, but the length is justified by the number of distinct decision paths it must document.
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 no annotations and no output schema, the description must convey behavior and return values — and it does: it enumerates the possible response families (authorized, denied with reasons, deferred, allowed) and the recorded authorization shape. Nothing needed to invoke or interpret the call is 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 100%, so each parameter's meaning, format and constraints are already documented in the schema. The description restates the policy checks (cap per call, daily limit, named currency, payee list) but adds little parameter semantics beyond what the schema provides, so the baseline 3 applies.
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 clause states a specific verb and resource ('Asks the body to authorize a payment and records the decision') and immediately clarifies the boundary that distinguishes it from a payment tool: 'the body never moves money.' An agent can tell this is an authorization gate, not a transfer, without opening the schema.
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?
Explicit when-to-use: 'Use it before any payment so that amount, currency, payee and reference are checked against the policy.' It also spells out the preconditions (a spend rule must exist), the approval round-trip, and the exact resend protocol with the same _ref.
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.5.1spend1 field changedInput schema / properties / reference / descriptionPrevious value: -"Your own reference for this payment, such as an invoice or order id. Recorded with the authorization and used by verax reconcile to match the card statement."New value: +"Your own reference for this payment, such as an invoice or order id. Recorded with the authorization; verax reconcile does not read it, and matches a card statement row by a verax:<ref> in its description, amount, currency and time."v0.1.1audit.explainmemory.getmemory.putmessage.readmessage.sendspendScored across 6 tools
Each tool targets a distinct resource and action: memory.get/put, message.send/read, spend authorization, and audit.explain. The descriptions reinforce clear boundaries, and no two tools appear interchangeable.
Five of six tools follow a consistent namespace.verb pattern (memory.get, memory.put, message.send, message.read, audit.explain). The lone bare verb 'spend' is a minor but noticeable deviation from the otherwise predictable convention.
Six tools is well-scoped for a local policy-gated agent body covering memory, messaging, spend authorization, and audit. Each tool earns its place without obvious redundancy.
The core lifecycle is partly covered: memory can be stored and recalled, messages can be queued and read, spending can be authorized, and decisions can be audited. However, there are notable gaps such as no memory listing or deletion, no message acknowledgement or inbox clearing, and no ledger query beyond single-ref lookup.
Runtime permission, approval, and audit layer for AI agent tool execution.
Zero-secret MCP gateway for AI agents: risk-scored, audited calls with human-in-the-loop approval.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Pre-execution policy gate for consequential agent actions with durable trust receipts.
