# Agent reference

Testril is an Ormi product and an MCP service for on-demand blockchain data. An agent discovers a metric template, binds its scope, checks coverage, materializes missing blocks, reads values, and verifies their sources. **A Universe of Blockchain Data.**

## Current release

The current release review on 2026-11-02 checked the Testril 0.14.0 source tag
`62aba5a2d4bccc6077cc42b6b68b79a0352a4e2c`: public MCP registrations,
argument types, server instructions, handlers, REST transport, payment/reward
paths, and relevant test sources. Read-only development `initialize` and
`tools/list` reported server 0.14.0 and protocol `2025-06-18`, with the same
nine tool names, input fields, and requiredness as this reference. Free health,
chain, pricing, and `erc20.token_balance` Function-schema calls also matched
the documented contract. Exact deployed Git revision and production status
remain unconfirmed. No paid work, binding, materialization, metric-data read,
stop, or reward claim was performed; backend tests were inspected, not
executed. Live discovery and actual quotes remain
authoritative. Historical source/live observations below retain their original
dates. The reviewed service endpoint is `https://dev.testril.ai/mcp`; payments
use USDC.
Version 0.14.0 expands the Function catalog for ENS, The Graph, launchpads,
prediction markets, token metadata, wallet transfers, and NFT collection
metadata, and adds payment-completion recovery. It does not change the nine
public tool names or their input fields. Discover the deployed Function slugs
and schemas through `inspect` rather than treating this release summary as a
catalog.

The canonical marketing website is `https://testril.si/`. The service remains at `https://dev.testril.ai/mcp` during this website migration; do not substitute the new website domain for the MCP endpoint.

## Start here

1. [Connect and discover the contract](/agents/connection/).
2. [Run the catalog-first quickstart](/agents/quickstart/).
3. [Look up the nine public MCP tools](/agents/mcp-tools/).
4. [Handle outcomes and recovery](/agents/outcomes/).
5. [Understand payment and execution](/agents/payments/).
6. [Verify provenance](/agents/provenance/).

## Reference library

- [Identities, parameters, and block windows](/agents/data-contract/).
- [Coverage, asynchronous jobs, and retention](/agents/coverage/).
- [Resolve a question with ask](/agents/authoring/).
- [Reusable agent recipes](/agents/recipes/).
- [Data liquidity, claim rights, and rewards](/agents/rewards/).

## Machine-readable entry points

- [MCP service card](/.well-known/mcp.json): connection, usage, and pricing
  overview for directories such as ASI. It describes the development endpoint;
  live MCP discovery and each per-request quote remain authoritative.
- [llms.txt](/llms.txt): compact navigation and integration constraints.
- [llms-full.txt](/llms-full.txt): the complete reference as plain text.
- [MCP tool reference JSON](/agents/mcp-tools.json): documented tools, input fields, and inspect subjects. This is an editorial reference, **not an exported runtime JSON Schema**.
- [Existing product content JSON](/agents/site-content.json): homepage copy, visible FAQ, and blog summaries. This is editorial context; the live tool contract remains authoritative.
- [Workflow examples](/agents/workflow-examples.md) and [scene JSON](/agents/workflow-examples.json): historical recorded MCP exchanges plus labeled current illustrations. The recorded pre-0.9.0 tools, arguments, and money values are archival, not current wire examples. These snapshots are not runtime schemas.
- Every page has a Markdown counterpart: replace its trailing slash with `.md`. For example, `/agents/quickstart.md`.

## Agent operating rules

Discover the catalog before binding. Never infer a chain, wallet, contract, time window, price, or missing parameter from an unrelated example. Read `outcome` before using any result. Respect the operator's metric choice and spending authorization. Keep payment receipts and the exact block windows used for verification. Never send a private key in tool arguments.

The main website preserves its existing product narrative. This reference is the detailed integration surface; the homepage Workflow replays captured exchanges, including shortened identifiers and omitted signatures. Its archived messages are not the current deployed schema.

## Release history

### Release review / 2026-10-27 / 0.13.0

The current release review on 2026-10-27 checked the Testril 0.13.0 source tag
`345cd5a857faed75c17ac0c94f05e96e8f935b15` and current main
`089892e0224cb8e4d748563ba7b2d9bd0e298e24`: public MCP registrations, argument
types, server instructions, handlers, payment/reward paths, and relevant test
sources. Read-only development `initialize` and `tools/list` reported server
0.13.0 and protocol `2025-06-18`, with the same nine tool names, input fields,
and requiredness as this reference. Free health, chain, and pricing calls also
matched the documented contract. Exact deployed Git revision and production
status remain unconfirmed. No paid work, binding, materialization, metric-data
read, stop, or reward claim was performed; backend tests were inspected, not
executed. Live discovery and actual quotes remain authoritative. Historical
source/live observations below retain their original dates. The service
endpoint is `https://dev.testril.ai/mcp`; payments use USDC.

### Development endpoint observation / 2026-10-19 / 0.10.0

Read-only MCP `initialize` and `tools/list` returned server `testril` version
0.10.0, protocol `2025-06-18`, and the same nine public tool names and input
field names as this reference. The field inventory now reflects the live
schema's optional block ends for `provenance`, since a period pair can be used
instead. Free `health_check` and `inspect subject:pricing` calls confirmed the
server reports configured chains and meter rates. No paid call or metric-data
read was made for this review. The deployment's implementation revision,
handlers, and tests could not be independently inspected in this workspace;
the 2026-10-13 source review remains specific to backend PR #274. Use live
discovery for any integration, and do not infer that this older guide verifies
every 0.10.0 behavior.

### Release review / 2026-10-13 / 0.9.0 and 0.9.1 owner clarification

A source review covered Testril backend PR
[`#274`](https://github.com/ormi-labs/testril/pull/274), reviewed commit
`319b8eb3c4ae94475b189f0015e9ade30c043fda`: its 0.9.0 release notes, public MCP
registrations and argument types, REST and MCP wire models, served
`instructions.rs`, handlers, and relevant tests. The target release was not
deployed, so no live `initialize` or `tools/list` claim is made for 0.9.0. No
metric work, write, or payment was performed.

An owner clarification recorded on 2026-10-13 supersedes two payment details
from that review: agent-facing priced tools settle the exact quoted amount, with
spending caps enforced by the agent's wallet or signer; and Testril 0.9.1
declares and enforces a 10,000-atom ($0.01) batch minimum deposit. The 0.9.1
implementation revision and live deployment were not independently reviewed for
this correction.

### Historical Workflow note

Historical Workflow MCP captures remain historical rather than being rewritten
to resemble 0.14.0. Their retired tools, arguments, and numeric money values are
records of earlier releases, not current wire examples. Current illustrative
scenes are labeled separately.