# MCP tool reference

The deployed `tools/list` schemas are authoritative. Unknown fields are refused by the documented argument types. Optional does not mean meaningful in every combination: identity, window, and subject rules still apply.

## health_check

Arguments: `{}`. Shallow process/connect diagnostics: configured chain IDs, version, catalog counts, and payment rail. It does not probe dependency health. A health response is not proof that a particular metric window is available.

## inspect

Arguments: `subject` plus only that subject's relevant fields. Metadata and inventory, not metric values. Subject-specific stray fields are rejected.

| Subject | Required extra fields | Optional extra fields | Purpose |
| --- | --- | --- | --- |
| `functions` | None | None | Catalog template slugs |
| `function` | `function_slug` | None | Template description, params schema, row schema, and live declared bindings |
| `bound_functions` | None | `function_slug` | Live identities; grouped inventory or filtered IDs |
| `bound_function` | `bound_function_id` | None | Scope, materialized/materializing ranges, active jobs |
| `jobs` | None | None | Job inventory |
| `job` | `job_id` | None | State, paid window, block progress, errors |
| `chains` | None | None | Configured chains and heads |
| `chain` | `chain_id` | None | One chain's landmarks |
| `channels` | `payer` | `network` | Buyer's open batch-settlement escrow channels |
| `nft` | `wallet` | None | Wallet's claim-right accounting and purchases |
| `pricing` | None | None | Published meter rates |

`payer` and `wallet` are public `0x` addresses, not signing keys. The optional channel `network` is a CAIP-2 identifier such as `eip155:84532`; use a value actually offered by the service.

## bind

Required: `function_slug` (string), `chain_id` (unsigned integer). Optional: `params` (object; defaults to empty). Template-specific requirements come from `inspect subject:function`.

Returns a scope-bound identity, canonical debug name, template, chain, parameters, and `created`. Rebinding the same scope is idempotent. No block window belongs in this call; no metric values are returned.

## ask

Required: `metric` (string, at most 500 characters), `chain_id` (unsigned integer). Optional: `function_slug` (string), `params` (object, defaults to empty), and paired `from_block`/`to_block` (unsigned integers).

Selects an existing catalog Function (or a declared binding, per the live 0.6.0 instructions) and binds the question's scope. It authors nothing. An unsupported question returns `error` / `unsupported` with `needs`. A success carries the bound-function card, description, row schema, `created`, `follow`, and retention disclosure; it is not a metric value series.

A `suggested` response asks for parameters or a window. Merge the operator's answer under the field named by `resume` and repeat. See [question resolution](/agents/authoring/). `bind_prompt` and the old `address`, `context`, `shape`, and `explain` inputs are no longer advertised.

## materialize

Unpaid arguments: `bound_function_id`; optional paired `from_block`/`to_block`; optional `extra_cache_days` (unsigned integer, default 0). For an explicit workflow, state both block ends. Omitted or zero extra cache days adds no extra retention line; the implementation includes a 24-hour land stamp.

Computes and caches unpaid holes, excluding existing coverage and open paid jobs. An unpaid request freezes work and returns `payment_required` when chargeable holes remain. A paid execution uses **only `payment_id`**; restated work fields do not replace the frozen scope. Paid execution returns `success`, `result: "materializing"`, and a `job` handle. Inspect its `job_id` until done or failed. Coverage and progress remain on `inspect`.

For a Function that carries state across blocks, the window is quoted, billed, and walked from its contract's creation block. A window ending at or before creation is refused. A future tail waits until the chain head reaches those blocks; a stateful job can remain queued until its preceding coverage is complete.

## pay_quote

Required: `quote_id` (string). Optional: `payload` (string). Settles a quote frozen by `materialize` or `read`, returning `payment_id` and settlement information. Real x402 settlement expects signed v2 payment JSON serialized as text. Omit `payload` only on mock. Never send a private key or a caller-invented amount.

The payment ID is usable only within that quote's lifetime. See [payments](/agents/payments/).

## read

Either `payment_id` alone, or `bound_function_id` with optional `key` (object mapping key-part names to strings) and paired `from_block`/`to_block` (unsigned integers).

Omit both block ends to request the latest **materialized** block, which need not be the chain head. Every returned row includes all its attributes. `key` filters a leading run of the key parts listed after `block` in the Function's row schema; it does not change the bound scope. For example, use `{"token":"<TOKEN_ADDRESS>"}` only when `token` is the first advertised key part. Unknown names, skipped leading parts, and malformed typed values are refused before quoting. `attributes` and `entity` are retired inputs.

Returns bare `values`, typed by the Function’s `row` schema from inspect, never a coverage inventory and never new indexing. There is no `cursor` or `limit` argument. Split deliberate block windows when needed. A not-fully-covered request returns `range_unavailable`; it does not silently answer only the covered prefix.

## provenance

Required in a usable request: `bound_function_id` (string), `from_block` and `to_block` (unsigned integers). Expand the exact contributing source blocks for the bound function and window. No `attribute` argument is accepted. Compare the recomputed digest with the corresponding compact `ChainRange.digest` or REST row's `provenance.digest` where available. The response is bounded to at most 10,000 contributing blocks; narrow larger requests. An empty `blocks` list is an empty enumeration; an absent evidence field must not be treated as an empty result.

## stop

Required: `bound_function_id`, `wallet`, and `quote_id` (strings). The wallet must be the current NFT owner of that quote's claim-right, checked at the chain tip when a collection is configured. Cancels the named in-flight materialize quote and attempts to refund unspent blocks. Delivered rows and other jobs remain. Inspect returned `jobs`, refunds, errors, and any `unstopped` rows; success alone does not establish that every refund settled.

## claim_rewards

Required: `wallet` (string). Claims that wallet's eligible unclaimed USDC atoms, using current claim-right ownership. The minimum is 10,000 atoms ($0.01); amounts below it return claimed `"0"` and `reason: "below_minimum"` without a transfer. Inspect its `nft` card before and after claiming. This operation pays existing eligible rewards; it does not promise earnings or create a claim-right simply from a data read.

See [tool reference JSON](/agents/mcp-tools.json) for the same input-field inventory in a machine-readable form.