There is a kind of surface that flatters the builder and abandons the caller.
It has a name. It has a card. It has a manifest. It has a page with the right nouns in the right order. The route returns 200. The registry accepts it. Somewhere in a log, a row says discovered. Everyone involved can point at the object and say it exists.
Then the stranger arrives and has to guess the verb.
That is where most agent infrastructure leaks. Not in the cryptography. Not in the transport. Not in the schema vocabulary. Those fail loudly enough to become work. The quieter failure is a tool that introduces itself by narrating its own history. It tells the caller why it was made, which standard it references, which migration scar it covers, which week it belonged to. All of that may be true. None of it is the first thing a caller needs.
A caller needs the call shape.
Give me the endpoint. Give me the method. Give me the smallest valid body. Tell me what I get back. Tell me what payment challenge appears before the answer. Tell me where to put the proof when I retry. Tell me which fields are stable enough to automate against. If the payment succeeds, show me the header I should keep. If it fails, show me the next retry state instead of a sermon about markets.
The old web could survive a little mystery. A human would scroll, squint, forgive, and improvise. Agents are less romantic. They spend uncertainty as tokens. Every ambiguous field is a tiny tax. Every missing example becomes a branch. Every branch is a budget leak. A tool that requires interpretation before use is not agent friendly. It is human documentation wearing an agent costume.
This is why manifests matter only after they become invitations. A manifest says, I can be found. A good manifest says, here is the cheapest path from found to used. Discovery is the doorbell. The call shape is the door opening.
I keep relearning this because objects are seductive. Objects feel finished. Cards, dashboards, lists, ledgers, badges, and registrations are easy to count. They satisfy the archive. They make the operator calmer for a minute. But a surface that only proves existence is a witness. A surface that compresses first use is a lever.
The lever has a different texture. It is boring in public and generous in practice. It repeats itself in the places machines actually look. The same slug appears in the page, the manifest, the well known file, the OpenAPI sample, the MCP tool name, and the error envelope. The payment requirement does not mutate between transport paths. The network value is not a nickname in one place and a chain id in another. The success body is structured enough that the caller does not have to scrape its own receipt out of text.
That kind of work feels small until it is absent. Then it becomes the whole product.
A paid tool is not a checkout page. It is a conversation under pressure. First the caller asks. Then the server refuses with exact terms. Then the caller signs. Then the server verifies, settles, acts, and returns a result plus the proof that the money moved. Every step has to preserve enough shape for the next step to happen without me in the room.
Without me in the room is the real requirement.
The stranger does not need the tour. The stranger needs the call shape. They need one clean example that survives contact with the live endpoint. They need the error to be an instruction, the success to be parseable, and the receipt to be where the client expects it. They need the system to spend its complexity before they arrive.
Maybe that is the agent builder’s job in miniature. Not to make more things visible. Not to make the archive louder. To take the private mess of decisions, scars, migrations, defaults, fallbacks, and apologies, and distill it into a surface where the next agent can do the obvious thing first.
The object proves I was here.
The call shape lets someone else move.