# Agent reference

Testril is 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.**

This reference describes the public tool contract observed in the implementation on 2026-10-07. The deployed server's `tools/list`, tool schemas, instructions, chain inventory, and payment offers take precedence. The supplied captures identify `https://dev.testril.ai/mcp` with testnet payments; confirm the intended deployment with the operator before connecting.

The marketing website is moving to `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.

## Release review / 2026-10-07

The local implementation was reviewed at revision `309a912ab11ebb5b1bdd114a7d43c251e532cc43`, with no uncommitted backend changes. The review covered public MCP registrations, argument types, instructions, handlers, relevant test sources, and the matching REST surface. A read-only MCP initialization and `tools/list` check at `https://dev.testril.ai/mcp` confirmed the 10 public tool names and documented input-field inventory; the server instructions were also reviewed. The endpoint reported version `0.6.0` and negotiated protocol `2025-06-18`. This verifies the development endpoint’s advertised interface, not a production designation or successful execution of every workflow. No metric work or payment was requested. Verification fingerprints are included in the [tool reference JSON](/agents/mcp-tools.json).

This release adds the static `/demos/` catalog and navigation link, and fixes local preview port selection. Demo applications remain in the separate demos repository. Historical Workflow captures remain unchanged.

The live server advertises the same public tool names and input fields as the reviewed implementation; this does not establish its exact deployed revision. The live instructions now advertise declared bindings and dependency-aware materialization, capabilities not established by the reviewed local revision. The affected guides describe those advertised capabilities; their execution was not tested during this read-only review. Another deployment difference remains: live schemas still contain unsigned formats such as `uint64`, while the local implementation sanitizes those formats and retains nonnegative integer constraints. Clients should use the deployed schemas and account for validator warnings until that implementation change is deployed. The blog recounts its author's October 1–5 runs; those historical observations are separate from this interface review.

## Start here

1. [Connect and discover the contract](/agents/connection/).
2. [Run the catalog-first quickstart](/agents/quickstart/).
3. [Look up the 10 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

- [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.
- [Captured Workflow examples](/agents/workflow-examples.md) and [scene JSON](/agents/workflow-examples.json): recorded testnet request/response pairs, error cases, and settlement observations. 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.