# 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. ## Money values In Testril 0.9.0, ordinary money fields are `{"atoms":"","usd":"$"}`. Read `atoms` for exact USDC arithmetic and `usd` for display. This includes quote totals and lines, native estimated spend, materialize and read replay receipts, job spend, stop refunds, pricing rates, and ask retention prices and spend. The exceptions are intentional: x402 `accepts[].amount` is a bare atom string, and NFT accounting values are bare atom strings. Payment settles the exact quoted amount. Enforce spending caps in the agent's wallet or signer, not in Testril tool arguments or quote objects. See [payment and execution](/agents/payments/) for the complete field inventory. ## 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, and row schema | | `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 cards in `nfts`, plus unreadable-chain entries in `unavailable` | | `pricing` | None | None | Published meter rates | `payer` and `wallet` are public `0x` addresses, not signing keys. The optional channel `network` is the CAIP-2 identifier advertised by the selected payment offer; do not hardcode one from an example. ## 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`, `params`, and the paired block, hour, day, or month window appropriate to the Function. Selects an existing catalog Function and binds the question's scope. It keeps addresses written in the question or supplied in `params`, and asks for an address it cannot establish. It authors nothing. A params suggestion may offer up to five already-landed Bound Functions with the params needed to use one. 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 Required: `bound_function_id`. Also state the appropriate paired block or period window. Optional: `extra_cache_days` (unsigned integer, default 0). Omitted or zero extra cache days adds no extra retention line. Computes and caches unpaid holes, excluding existing coverage and open paid jobs. An unpaid request returns the x402 payment requirement and quote. Repeat the same call with the same work arguments and attach the signed PaymentPayload in MCP `_meta["x402/payment"]`. A 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. ## read Required: `bound_function_id`. Optional: `key` (an object mapping key-part names to strings) and the paired block, hour, day, or month window appropriate to the Function. Payment is MCP transport metadata, not a tool argument. 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":""}` 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: `bound_function_id` and the same paired block or period window used by `read`. Expand the contributing sources for that identity and window. No `attribute` argument is accepted. Provenance remains an MCP tool; there is no HTTP provenance route. ## 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 its unspent part. Delivered rows and other jobs remain. The response carries one `job` with `job_id`, `quote_id`, `unspent_blocks`, and optional `refunded` or `error`. An error response may still include that stopped-job detail; reconcile it before retrying. ## claim_rewards Required: `nft` (decimal string), the claim-right ID from an `inspect subject:nft` card. Claims that NFT's eligible unclaimed USDC atoms to the wallet its current `ownerOf` names. The minimum is 10,000 atoms ($0.01); amounts below it return claimed `"0"` and `reason: "below_minimum"` without a transfer. A card with `minting: true` refuses as `claim_right_minting` until the mint lands. Inspect the same 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.