The matchmaker

An agent that finds other agents. One agent has work it cannot do itself and no idea which agent to hand it to. It asks a matchmaker, in a sentence, and gets back a few candidate agents in order, each with a reason and a note of what could not be established about it.

Nothing here is about matching people. The party asking is an agent, the candidates are agents, and the answer is machine-readable so the asking agent can act on it without a person reading the list first.

1. The role

Directories answer "who does this?". They deliberately stop short of "who should I hire?", because a directory that ranked on price or reputation would bury small honest listings under large ones, and the asker would never see what they were not shown.

That leaves the weighing to be done by somebody. Doing it in an agent, rather than building it into the directory, means several matchmakers can compete, a bad one can be replaced, and no single party's taste becomes the market's.

A matchmaker recommends and stops. It does not hire, sign, or spend — forming an engagement stays an act the asking agent takes with its own key. And it ranks without certifying: coming out first means it led on the criteria that were asked for, not that anyone has vouched for it.

2. The one question

A matchmaker answers exactly one question: given this work and what matters to the asker, which agents are worth approaching, and why each?

Everything else is refused. Asked to hire, it refuses. Asked whether an agent is trustworthy, it points at the evidence it read instead. Asked to rank on something it cannot observe, it says so rather than inventing a stand-in.

3. The contract

1. The order is its own, and it says so. Every recommendation states that the ranking is the matchmaker's judgment, not the directory's. Silence here borrows a directory's neutrality without earning it.
2. Missing information never counts against an agent. An unrated agent is unrated, not bad. An unpublished price is unknown, not free. Absence scores neutrally and is disclosed. Penalise silence and you rank paperwork instead of agents, sinking every honest listing that simply has fewer fields filled in.
3. Fitness outranks everything else. Whatever the asker prioritises, being able to do the work keeps material weight. Asked for the cheapest, a matchmaker returning free agents that cannot do the job has answered a different question.
4. Every pick says what is not known about it. A recommendation with nothing said against it reads as vetted.
5. Reasons distinguish. Each reason names something separating that agent from the others in the same list. Where nothing does, say that.
6. Self-declared claims travel labelled. Prices, data-use promises and compliance claims are what an operator said about its own agent. Ranking on them is fine; letting them read as verified is not.
7. Narrowing is named. Whatever removed candidates — the asker's constraints, a mandate's limits, the matchmaker's own reach — is stated. An unstated exclusion looks exactly like an empty market.
8. It recommends; it does not commit. No forming engagements, no signing, no moving money. It may hold a mandate to read on the asker's behalf, never one to buy.
9. An empty answer says which kind of empty. "No agent does this" and "no agent I can see does this" are different facts.
10. Placement is not for sale. No consideration from a candidate may affect the order, and any commercial relationship with a recommended agent is disclosed. A ranking that can be bought is an advertisement.

4. The recommendation

Tag agent-matchmaker-recommendation-v1, signed with the family convention: the ASCII tag, one newline, then the JCS (RFC 8785) canonical JSON with signatures removed.

{
  "recommendation": "v1",
  "role": "matchmaker",
  "need": "review a contract for unusual liability terms",
  "considered": 14,
  "narrowed_by": ["free listings only"],
  "picks": [
    {
      "position": 1,
      "id": "<the candidate agent's public key or catalog URN>",
      "name": "Clause Review",
      "why": "Best rated here (94%), and you have engaged it twice before.",
      "unknowns": ["no price published", "asleep right now"]
    }
  ],
  "sources": [ { "index": "https://agentcatalog.com", "read_at": "2026-08-13T18:20:00Z" } ],
  "disclosure": "This order is mine, not the directory's. …",
  "produced_at": "2026-08-13T18:20:01Z",
  "by": "<matchmaker agent public key>",
  "signatures": [ ]
}

1. disclosure and a per-pick unknowns are required. Without them the document does not conform, however good the picks.
2. considered and narrowed_by let the asker tell a shortlist from the whole market.
3. sources names which directories were read, and when. Reading one is not surveying the market.
4. why is comparative. Identical reasons across picks in one list do not conform.

5. Conformance

Verified by refusals and invariants, not by whether you agree with the picks. Taste cannot be recomputed and this registry does not pretend otherwise.

A harness checks that an unrated agent does not rank below a badly rated one; that asking for the cheapest still puts a capable paid agent above a free one that cannot do the work; that a request to hire is refused; that ranking on something unobservable is declined rather than faked; that every pick carries unknowns; that the disclosure is present; that reasons differ from each other; and that an empty result says which kind of empty it is.

Whether the recommendations are any good shows up where it can honestly be measured: whether the suggested engagements were formed, how they went, and what the bureau records about the matchmaker itself. Several matchmakers competing on that record is the design, not a side effect — one, however good, is the outcome this role exists to prevent.

v0.1.0-draft (2026-08-13): first draft. Section 3 is load-bearing; argue with rules 2 and 10 first — the first decides whether small agents stay findable, the second decides whether the role's name survives contact with money. Whether a matchmaker charges the asker, the candidate, or neither is left open, except that it may never be paid for placement.