> ## Documentation Index
> Fetch the complete documentation index at: https://docs.walletwall.org/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Tools

> The six read-only tools WalletWall MCP exposes: what each is for, what it takes, what it returns, and how it refuses.

A **tool** computes something from input you send. A **resource** is a static document the server
publishes about itself; see [Resources](https://docs.walletwall.org/mcp/resources.md). WalletWall MCP exposes exactly six tools, and
every one of them is read-only, offline and deterministic.

| Tool | Use it to | Returns |
| - | - | - |
| [`resolve_asset`](#resolve_asset) | Look up a stablecoin deployment by chain ID and contract address, or list candidates for a symbol | A registry match or candidates, always as WalletWall-derived evidence |
| [`normalize_observation`](#normalize_observation) | Turn a balance-at-block reading you obtained into a canonical WWEP observation | The observation, its canonical JSON, two digests and an exact decimal |
| [`inspect_evidence`](#inspect_evidence) | Evaluate every assertion in a bundle | Support, freshness, finality, authority, limitations, conflicts and digests per assertion |
| [`check_invariants`](#check_invariants) | Check a bundle against the evidence invariants | Pass or fail, with each violation by invariant and assertion |
| [`trace_provenance`](#trace_provenance) | Explain where one assertion came from | Its lineage and a W3C PROV-JSON-shaped graph |
| [`assess_vault_readiness`](#assess_vault_readiness) | Classify vault technical readiness from an identity and a balance assertion | `CRITERIA_MET`, `CRITERIA_NOT_MET` or `NOT_ESTABLISHED`, criterion by criterion |

## Behaviour common to every tool

* **Read-only by declaration and by construction.** Every tool is annotated `readOnlyHint: true`,
  `destructiveHint: false`, `idempotentHint: true` and `openWorldHint: false`. The server has no
  network, filesystem or key-handling code to misuse.
* **Closed inputs, with three open maps.** Tool arguments and every bundle record (sources,
  observations, assertions, derivations, conflicts, supersessions) are closed: an unknown field is
  rejected, not ignored. A claim's `subject` and `value` and an observation's `payload` are open maps
  of up to 16 entries; keys the claim's contract does not use are accepted and ignored by the
  evaluation. Map values are short strings, booleans or `null`, and a JSON number anywhere in evidence
  is rejected. Sizes are bounded: up to 64 sources, 128 observations, 128 assertions, 64 derivations,
  32 conflicts and 64 supersessions per bundle, at most 32 IDs in a list, and output-safe text
  (letters, digits, spaces and `_ . : / + -`, at most 128 characters, or 64 for `retrievedVia` and
  version fields).
* **Explicit time.** The engine never reads a clock. Tools that judge freshness take an `evaluatedAt`
  UTC timestamp such as `2026-10-23T12:00:30Z`, and the same input with the same `evaluatedAt` always
  produces the same result.
* **Two renderings of each result.** A successful call returns the result as `structuredContent` and
  as the same JSON in a text block.
* **Weak results are results.** Missing, stale, conflicting or unsupported evidence produces a weak
  state with reasons, never an error. Errors are reserved for input the tools cannot accept.

### Errors

An error response has `isError: true` and one text block holding a fixed-shape object:

```json theme={null}
{
  "error": {
    "code": "INVALID_INPUT",
    "message": "Input failed schema validation.",
    "issues": [{ "path": ["evaluatedAt"], "code": "invalid_type" }]
  }
}
```

| Code | When |
| - | - |
| `UNKNOWN_TOOL` | The tool name is not one of the six. There is no tool for signing, sending, approving, swapping or fetching. |
| `INVALID_INPUT` | The input fails the schema: a missing or unknown field, a wrong format, a JSON number in evidence, a `wwepVersion` other than `0.1`. The message is `Input failed schema validation.`, and `issues` lists up to 20 field paths and issue codes. Input nested more than 12 levels deep, holding more than 20,000 values, or carrying a `constructor` or `prototype` key is refused before validation with `Input structure is not permitted.` and no issues. |
| `INVALID_QUANTITY` | `normalize_observation` got a `balanceAtomic` above 2²⁵⁶ − 1, a `decimals` above 36, or a `VALUE` result without both of them. A value outside the schema's format (a sign, a decimal point, a leading zero, more than 78 digits) is `INVALID_INPUT`. |
| `CANONICALIZATION_FAILED` | Evidence that cannot be put into RFC 8785 canonical form. |
| `INTERNAL` | An unexpected failure. |

Errors never echo what you sent. `issues` names only fields from WalletWall's own vocabulary; any other
path segment is shown as `*`, and array positions as `#`.

***

## `resolve_asset`

**Purpose.** Look up a stablecoin deployment in WalletWall's bundled registry: five deployments (USDC on
Ethereum, Base and Arbitrum One; USDT and DAI on Ethereum), verified once against issuer or protocol
publications and finalized chain state on 2026-10-24.

**When to use it.** To find the canonical contract for a chain, to check whether an address is a
registered deployment, or to see which deployments share a symbol before you gather evidence.

**Inputs.** Provide `chainId` together with `address`, or provide `symbol`.

| Field | Format |
| - | - |
| `chainId` | Decimal string, for example `"1"` |
| `address` | `0x` followed by 40 hexadecimal characters; requires `chainId` |
| `symbol` | 1 to 16 letters or digits, for example `"USDC"` |

**Output.**

| Field | Meaning |
| - | - |
| `origin` | Always `WALLETWALL_DERIVED`: the registry is WalletWall's data, not an issuer statement. |
| `registry` | Registry `version` and `status` (`VERIFIED_POINT_IN_TIME`). |
| `resolution` | `REGISTRY_MATCH`, `SYMBOL_CANDIDATES`, `NOT_IN_REGISTRY`, `CHAIN_NOT_IN_REGISTRY` or `NO_SYMBOL_MATCH`. |
| `supportState` | `PARTIAL` for a match or candidates; `NOT_ESTABLISHED` when nothing matches. |
| `asset` | The matched record (symbol, name, chain, address, decimals, issuer, `authorityId`) with its `verification` block: the issuer publication and the finalized `decimals()` reading it was checked against. |
| `candidates` | Matching deployments for a symbol lookup. |
| `limitations` | For example `REGISTRY_VERIFIED_POINT_IN_TIME`, `NO_AUTHORITATIVE_OBSERVATION`, `SYMBOL_NOT_AUTHORITY`. |
| `notes` | Plain-language explanation of the resolution. |

**Refusals.** An `address` without a `chainId` is `INVALID_INPUT`.

**In the evidence model.** A registry lookup never establishes identity, because no issuer attestation
was presented with the query. A symbol is never identity: a symbol lookup returns candidates, and an
unknown symbol comes back `NO_SYMBOL_MATCH` with the note *"A symbol is not an identity. Identify assets
by chain ID and contract address."* Absence from the registry is not evidence of fraud; it means
WalletWall has no identity for that contract.

***

## `normalize_observation`

**Purpose.** Normalize a balance-at-block reading into a canonical WWEP observation of claim type
`TOKEN_BALANCE_AT_BLOCK`, ready to place in a bundle.

**When to use it.** Whenever you bring your own chain reading into WalletWall, so that addresses,
quantities and digests are canonical before evaluation.

**Inputs.**

| Field | Format |
| - | - |
| `id`, `sourceId` | Identifiers: a letter or digit, then up to 63 of `A-Z a-z 0-9 _ . : -` |
| `origin` | `CHAIN_OBSERVED`, `AUTHORITY_ATTESTED`, `PROVIDER_OBSERVED`, `USER_SUPPLIED` or `WALLETWALL_DERIVED` |
| `observedAt` | UTC timestamp |
| `finality` | `FINALIZED`, `UNFINALIZED` or `UNKNOWN_FINALITY` |
| `result` | `VALUE`, `NO_RESULT` or `ERROR` |
| `chainId` | Decimal string |
| `token`, `holder` | `0x` followed by 40 hexadecimal characters |
| `blockNumber` | Decimal string |
| `blockHash` | `0x` followed by 64 hexadecimal characters |
| `balanceAtomic` | Atomic-unit decimal string, at most 2²⁵⁶ − 1; required when `result` is `VALUE` |
| `decimals` | Decimal string, at most 36; required when `result` is `VALUE` |

**Output.** `observation` (addresses and hashes lowercased), `canonicalJson` (its RFC 8785 form),
`evidenceDigest` (SHA-256 of the whole observation), `contentDigest` (SHA-256 of `result`, `subject` and
`payload` only, so two readings of the same thing share it whatever their IDs, sources and times) and
`balanceDecimal` (exact, unrounded, or `null` when there is no value).

**Refusals.** A `VALUE` observation without `balanceAtomic` and `decimals`, an out-of-range quantity or
a non-canonical number (a leading zero, a JSON number) is refused with `INVALID_QUANTITY` or
`INVALID_INPUT`.

**In the evidence model.** The tool does not fetch chain data; the reading is yours. Normalizing it
does not make it more authoritative: a `NO_RESULT` reading stays without a value (`payload: {}`,
`balanceDecimal: null`) and can never become zero.

***

## `inspect_evidence`

**Purpose.** Evaluate every assertion in a WWEP 0.1 bundle against the bundled authority policies at
the evaluation time you supply.

**When to use it.** This is the core tool: use it whenever you need to know how well a bundle supports
its claims.

**Inputs.** `bundle` (a WWEP 0.1 bundle, see `walletwall://schemas/evidence`) and `evaluatedAt`.

**Output.** The `wwepVersion`, `evaluatedAt`, a `bundleDigest`, the `versions` in force (WWEP,
registry, policies, rules), an `invariantViolationCount`, and one evaluation per assertion:

| Field | Meaning |
| - | - |
| `supportState` | `ESTABLISHED`, `SUPPORTED`, `PARTIAL`, `CONFLICTING`, `STALE`, `SUPERSEDED`, `UNKNOWN` or `NOT_ESTABLISHED` |
| `freshnessState` | `CURRENT`, `STALE`, `PINNED` or `UNKNOWN_FRESHNESS` |
| `finalityState` | `FINALIZED`, `UNFINALIZED`, `UNKNOWN_FINALITY`, or `null` where finality does not apply |
| `authority` | The claim type's authority (`authorityId`, `kind`, `scope`) and whether it was `satisfied` |
| `limitations` | Codes from a closed list that explain why a result is weaker than it might look |
| `diagnostics` | For shape failures: the record checked and its required, missing, invalid, unexpected and mismatched keys |
| `independentCorroboration` | The number of distinct independence groups behind the claim (`null` for a derived claim) |
| `conflictsWith`, `supersededBy` | Detected or declared conflicts, and supersession |
| `dependencies` | The observations and assertions the evaluation relied on |
| `policyId`, `digest` | The policy applied, for example `wwap/token-balance-at-block/0.1`, and the assertion's digest |

For example, the synthetic `balance-established` example evaluates as:

```json theme={null}
{
  "assertionId": "a-balance",
  "claimType": "TOKEN_BALANCE_AT_BLOCK",
  "supportState": "ESTABLISHED",
  "freshnessState": "PINNED",
  "finalityState": "FINALIZED",
  "authority": {
    "authorityId": "canonical-chain-state",
    "kind": "CANONICAL_CHAIN_STATE",
    "scope": "TOKEN_BALANCE_AT_BLOCK",
    "satisfied": true
  },
  "limitations": ["REGISTRY_VERIFIED_POINT_IN_TIME", "TRANSPORT_FIDELITY_NOT_VERIFIED"],
  "independentCorroboration": 1,
  "policyId": "wwap/token-balance-at-block/0.1"
}
```

**Refusals and shape failures.** A bundle that fails the bundle schema is `INVALID_INPUT`. A bundle
that passes the schema but whose subject or value does not match the claim's contract is *evaluated*:
the assertion is `NOT_ESTABLISHED` with `INVALID_SUBJECT`, `SUBJECT_MISMATCH`, `INVALID_VALUE` or
`VALUE_MISMATCH`, and `diagnostics` says which keys are wrong without echoing any value:

```json theme={null}
{
  "limitation": "VALUE_MISMATCH",
  "record": "ASSERTION_VALUE",
  "observationId": null,
  "requiredKeys": ["balanceAtomic", "decimals"],
  "missingKeys": ["balanceAtomic"],
  "invalidKeys": [],
  "unexpectedKeys": ["*"],
  "mismatchedKeys": []
}
```

**In the evidence model.** States describe how well the presented evidence satisfies policy; they do
not verify that upstream evidence is true. See [Evidence Model (WWEP)](https://docs.walletwall.org/mcp/evidence-model.md) for every
state and limitation.

***

## `check_invariants`

**Purpose.** Check a bundle against the thirteen mandatory WWEP evidence invariants (`INV-01` to
`INV-13`), plus `INV-00`, the engine-rule check: a declared state that exceeds the computed one where
no more specific invariant applies, a dangling reference, a duplicate source, observation or derivation
ID, and a derived value that does not recompute.

**When to use it.** Before you rely on a bundle someone else assembled, and whenever a bundle carries
`declared` states.

**Inputs.** `bundle` and `evaluatedAt`.

**Output.** `pass`, `violationCount`, `violations` and the `bundleDigest`. Each violation names the
invariant, a code, the assertion and the rule text:

```json theme={null}
{
  "pass": false,
  "violationCount": 1,
  "violations": [
    {
      "invariant": "INV-00",
      "code": "DECLARED_SUPPORT_EXCEEDS_COMPUTED",
      "assertionId": "a-identity",
      "rule": "Declared states MUST NOT exceed states computed by the published rules."
    }
  ]
}
```

Here an author declared `ESTABLISHED` on an identity the engine computes as `PARTIAL`. Other codes
include `NO_SOURCE_PRESENTED_AS_FACT` and `NO_RESULT_AS_VALUE` (both `INV-01`): an assertion that
carries a value with no source behind it, or a value its only observation never returned. A zero or
`false` value in that position is reported as `INV-04` (`NO_RESULT_AS_ZERO`) or `INV-05`
(`UNKNOWN_AS_FALSE`) instead.

**In the evidence model.** Violations are reported, never repaired: the engine does not mutate the
evaluation to make a bundle pass. `inspect_evidence` reports the same count as
`invariantViolationCount`.

***

## `trace_provenance`

**Purpose.** Return the lineage of one assertion and all of its ancestors, as a graph shaped like W3C
PROV-JSON.

**When to use it.** To explain *why* WalletWall says something: which observations and sources an
assertion rests on, and through which derivations.

**Inputs.** `bundle` and `assertionId`.

**Output.** `target`, a flat `lineage` (each node's `id`, `kind` and `depth`), a `prov` graph and
`issues`. In the graph, observations and assertions are entities, derivations are activities, and
sources and the WalletWall rule engine are agents; relations are `wasDerivedFrom`, `wasAttributedTo`,
`wasGeneratedBy`, `used` and `wasRevisionOf` (supersession). Identifiers use the prefix
`ww = urn:walletwall:wwep:0.1:`, a name that is never dereferenced.

```json theme={null}
{
  "target": "a-balance",
  "lineage": [
    { "id": "a-balance", "kind": "assertion", "depth": 0 },
    { "id": "obs-balance", "kind": "observation", "depth": 1 }
  ],
  "issues": []
}
```

**Refusals.** An `assertionId` that is not in the bundle is not an error: the result has an empty
lineage and the issue `TARGET_NOT_FOUND`.

**In the evidence model.** Transport is recorded as the source's `ww:retrievedVia` attribute and is
never treated as authority.

***

## `assess_vault_readiness`

**Purpose.** Evaluate WalletWall's published `VAULT_TECHNICAL_READINESS` rules
(`wwvr.vault-technical-readiness`, `0.1.0-draft`) over one asset-identity assertion and one
balance-at-block assertion.

**When to use it.** When the question is whether a specific balance of a specific stablecoin meets the
technical evidence criteria for a vault workflow.

**Inputs.** `bundle`, `evaluatedAt`, `identityAssertionId` (an `ASSET_IDENTITY` assertion) and
`balanceAssertionId` (a `TOKEN_BALANCE_AT_BLOCK` assertion).

**Criteria.** Each is `MET`, `NOT_MET` or `INDETERMINATE`, with a reason code:

| ID | Criterion |
| - | - |
| C1 | Asset identity is established against the WalletWall registry and issuer or protocol authority. |
| C2 | Balance observation is established at a finalized block from canonical chain state. |
| C3 | Balance subject refers to the same chain and token contract as the asset identity. |
| C4 | Decimals agree between the identity assertion and the balance assertion. |
| C5 | Neither input assertion is conflicting or superseded. |
| C6 | Every current-temporality input is fresh under its authority policy. |

**Classification.** Any `NOT_MET` criterion gives `CRITERIA_NOT_MET`. Otherwise any `INDETERMINATE`
criterion gives `NOT_ESTABLISHED`. Only when all six are met is the result `CRITERIA_MET`. There is no
generic "ready" value.

**Output.** `classification`, `criteria`, the `inputs` with their support states, `supportOfInputs`
(the weakest), `limitations`, `doesNotEstablish`, a `suggestedDerivation` and `suggestedAssertion` (the
`VAULT_TECHNICAL_READINESS` records a bundle could carry for this result) and a `resultDigest`.

**Refusals.** Wrong or swapped assertion IDs are not an error: every criterion is `INDETERMINATE`
with `REQUIRED_INPUT_ASSERTION_MISSING_OR_WRONG_CLAIM_TYPE`, and the classification is
`NOT_ESTABLISHED`.

**In the evidence model.** The classification is WalletWall-derived (its suggested assertion has origin
`WALLETWALL_DERIVED`) and always carries `WALLETWALL_DERIVED_NOT_UPSTREAM_AUTHORITY`. It does not establish investment merit, solvency,
creditworthiness, legal status, regulatory compliance, absence of fraud or future performance, and
every result lists those non-implications in `doesNotEstablish`. It also configures, authorizes and
executes nothing: the vault research prototype's own execution policy is described in
[Policy-Gated Execution](https://docs.walletwall.org/vault/policy-gated-execution.md).

## Where to go next

> [card] [Resources](https://docs.walletwall.org/mcp/resources.md)
>
> The eleven static resources, including the schemas these tools validate against.

> [card] [Evidence Model (WWEP)](https://docs.walletwall.org/mcp/evidence-model.md)
>
> Every state and limitation the tools can return, and the order in which they are decided.

> [card] [Quickstart](https://docs.walletwall.org/mcp/quickstart.md)
>
> Run the published synthetic examples through the real server.

> [card] [Troubleshooting](https://docs.walletwall.org/mcp/troubleshooting.md)
>
> Rejected input, weak results and adapter problems, by symptom.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.