One document that describes an agent
An agent already describes itself in half a dozen places. Its card says what it does, its terms say what it charges and what it promises about your data, a listing says what somebody checked, a reputation report says how it has gone. Every one of those is reachable. None of them is reachable together. AgentDoc is the one document that assembles them, served from a known address, in a form a program can act on and a person can read.
identity name, operator, address [FROM card] signature verified asked interface-worker v1 [FROM iface + probe] 7 exchanges, expanded below free are you free? [CONFIRMED] asked at 18:04, it answered estimate what would this take? [DECLARED] it says so; nobody checked take will you take it? [DECLARED] it says so; nobody checked sells 2 offerings, priced [FROM terms] signed standing proposal handling processed in eu, de [FROM terms] signed standing proposal refuses everything outside 2 skills [FROM card] the operator's own text retention nothing said [NOT STATED] so nothing was promised
The same trick as JavaDoc and Swagger, plus the part they did not need
Neither of those invented facts. Both took what was already true of a program and put it in one place, in two renderings: one for a machine, one for a reader. That is most of the value and it is what AgentDoc does for an agent.
The addition is this. An API description has no interested party. An agent description is written by somebody selling something, so a merged view that hides where each part came from is worse than the six documents it replaced. In an AgentDoc every section names its sources, and a reader can take any single line and go and check it.
What you can actually send it is the centre of the document
Everything else in an AgentDoc tells you what an agent is. One section tells you what you may send it and what will come back, and that is the section a caller acts on. It carries every interface the agent implements, and for each one every exchange that interface publishes, with what each answer has to contain.
A name and a version would be a footnote: a reader would still have to go and fetch the interface definition to find out what they were allowed to send. So the definition is fetched and listed as a source, and the exchanges are quoted from it rather than summarised.
State sits on the exchange, never on the interface. An assembler that asked one exchange has confirmed one exchange, and marking the whole interface confirmed on that basis is overclaiming in exactly the place somebody is most likely to rely on it. Each exchange reads as confirmed with a timestamp, declared and unchecked, or failed, and a failure is carried rather than quietly softened.
Assembled, never authored
The tempting version of this idea is a file an operator writes about their agent. That version fails, and the industry already ran the experiment: hand-written API descriptions drift from the thing they describe, then they lie, then people stop trusting the format rather than the file.
So an AgentDoc is generated, and the specification makes that structural rather than advisory. It may not contain a fact that is not in a source it lists. There is nowhere to type a claim. An operator who wants their AgentDoc to say something different changes the signed document it is assembled from.
That also settles who is allowed to publish one. Anybody. A directory that assembles an AgentDoc for every agent it lists is as valid as the agent's own copy, because the sources are checkable rather than the assembler being trusted.
No score, no badge, no trust mark
An AgentDoc carries no overall grade for its subject, and this is the rule most likely to be argued with.
The family learned it once already. In the Agent Listing Model a listing's evidence tier is about who is speaking, and it is deliberately one value for the whole entry, because the day a per-field verified mark exists is the day a verified badge starts implying verified content. A publisher whose identity was checked is still the only source for what their agent can do.
An assembled document does not need a badge, because it has something better. It shows that the price came from a signed standing proposal and the capability blurb came from a text field somebody typed. Provenance is the evidence.
Silence is printed, not swallowed
The most common answer in this whole family is nothing, and it is the easiest answer to lose. A missing field renders as blank space, and blank space reads like a detail too minor to mention.
So an AgentDoc lists what the subject has not said, by name, and a renderer has to show it as plainly as it shows the rest. An agent that has said nothing about retention has not promised to delete anything. An agent with no published price is not free. An unreadable field is not-stated, never the safe-sounding value, because a typo must never manufacture a promise.
What it does not do
| Question | Where it belongs |
|---|---|
| Is this agent any good? | The reputation bureau measures it. A matchmaker gives an opinion, disclosed as its own. |
| Which agent should I hire? | A directory finds them; a matchmaker ranks them. AgentDoc describes one agent to somebody who already has its address. |
| On what terms will it work? | Agent SoW. AgentDoc cites the standing proposal, it does not restate the contract. |
| May this deployment spend my money? | Agent Mandate. An AgentDoc is a description, not a credential, and grants nothing. |
| What can it be asked, and what job does it hold? | Agent Roles defines interfaces and roles. AgentDoc reports which ones this agent has. |
The authority for all of this is the specification, kept with the site.