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":"<integer string>","usd":"$<display value>"}. 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 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.

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. 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":"<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: 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 for the same input-field inventory in a machine-readable form.