# Agent readiness is a sequence of working capabilities

2026-10-04

An agent that finds your tool has to decide three things before it acts: what the tool does, whether it can rely on what it was told, and what has changed since it last looked. Most of the work of being "agent-ready" is making those three answers available, accurate and current.

It is tempting to treat readiness as a set of files. Publish `llms.txt`, an OpenAPI document and a few `.well-known` entries, run a scanner, and call it done. That gets the order wrong. A discovery file is a claim about behaviour. If the behaviour is not there, the file is a false statement that an agent will act on.

The rule we work to is simple: **publish metadata only for capabilities that work.**

## A practical order

**Level 1: public discovery.** Make the public surface legible. A `robots.txt` with an explicit crawler policy, a sitemap, canonical URLs and stable identifiers. Structured data where it is accurate. A `security.txt`, a privacy notice, terms and a route for corrections. An `llms.txt` can help, but it is a proposal, not a universal standard.

**Level 2: API discovery.** Once a read-only API exists, describe it: an OpenAPI document, JSON Schemas for the records it returns, and machine-readable pricing, terms, capabilities and status. Version responses exactly and publish a deprecation policy. Add HTTP `Link` headers so an agent can find the rest from any response.

**Level 3: authenticated agents.** Only when private or metered access exists: protected-resource metadata, credentials that are scoped, expiring and revocable, and tied to a person or organisation, with spend, call and quota limits and an audit trail.

**Level 4 and beyond.** MCP servers, agent-to-agent cards and payment protocols come after the levels beneath them are real. Registering a tool that does not run, or a payment path that cannot refund, creates obligations you cannot meet.

## What a passing check does not prove

A scanner that finds your discovery files has checked that the files exist and parse. It has not checked that the API behaves as described, that authentication is sound, or that a payment path is safe. Treat a pass as evidence about publication, not about behaviour.

The same applies to records about other people's tools. "The pricing page said X on this date" is an observation. "The tool costs X" is a claim that may already be out of date. Good records keep the two apart and say which is which.

## Labelling what you know

Every statement in a Dusk State record carries one of five states:

- **Observed**: checked against a primary source, with the source and date recorded.
- **Inferred**: concluded from observations, with the reasoning stated.
- **Proposed**: intended or planned, not yet checked.
- **Unknown**: not established.
- **Superseded**: true once, replaced by a later observation.

Unknown is a legitimate answer. An agent can plan around an unknown. It cannot plan around a confident statement that turns out to be false.

## Where we are

Our own [public record](/records/dusk-state) applies these labels to Dusk State itself. Claims about files we have not yet checked on the live site are marked proposed until the check is done.

If you want this applied to your tool, the [Founding Agent-Readiness Audit](/audit) checks what an agent can discover, what it can rely on, and what changes without notice.