model-council

# Model Council

<!-- mcp-name: io.github.Totti0135/model-council -->

English | [简体中文](README.zh-CN.md)

An MCP server that seats other LLMs at your table. Your assistant asks them,
reads their answers as tool results, relays those answers back and forth for
critique, and gives you one merged conclusion — inside a single normal
conversation, with no copy-paste.

Your assistant chairs the council. Any number of members, from any mix of
OpenAI-compatible and Anthropic-compatible endpoints — a hosted API, a
self-run gateway, a local server, or several of each.

## Tools

| Tool | What it does |
|------|--------------|
| `ask(model, prompt, materials?)` | Ask one member by id |
| `ask_all(prompt, models?, rounds?, guests?, materials?, steelman?)` | Ask everyone (or a named subset) the same prompt in parallel, answers side by side. `rounds=2` turns it into a discussion; `steelman` seats a standing objection that argues back every round; `guests` seats answers you already have; `materials` hands them a file to read |
| `revise(prompt, answers, round?, materials?)` | Run one more round yourself: show the members everything said last round — including answers only you can produce — and get them back revised |
| `revision_prompt(prompt, answers, seat, materials?)` | The prompt to hand your own seat for the next round, word-for-word what the members got. No network calls |
| `list_council()` | The roster: ids, endpoints, weights, what each member can be shown, the route each takes out, call budget, and whether it is ready. No network calls |
| `probe_models(model?)` | Ask a provider's `/models` route what ids it really exposes |

Members are stateless and cannot see your conversation, so the chair passes
everything they need in each call. That is exactly what makes cross-review work:
it puts one member's answer inside another's `prompt`.

### Giving the council something to read

A question is usually about something — a spec, a log, a diff, a screenshot. The
obvious way to include it is to paste it into `prompt`, and that is the expensive
one, in the place nobody watches: `prompt` is an argument the chair *writes*, so
a long document costs a full copy of itself in generated tokens on every call,
and what reaches the members is whatever the chair managed to reproduce. For
forty pages that is not reliably the document. A council reviewing a paraphrase
is not reviewing the thing, and nothing in the transcript would say so.

`materials` names it instead:

```
ask_all(
  prompt="Where would this break under load?",
  materials=[
    {"label": "The design", "path": "/abs/path/design.md"},
    {"label": "Latency graph", "path": "/abs/path/p99.png"},
    {"label": "My summary", "text": "…something with no file behind it…"},
  ],
  rounds=2,
)
```

The server reads each one and puts it ahead of the question, in the same place
for every member and every round. The position is not presentation:

- **Identical bytes.** Every member argues with the same copy, which is what
  makes their disagreement about the document rather than about which version
  each was given.
- **A prefix that can be cached.** Everything up to the end of the material is
  the same in every call of a discussion. The Anthropic format is told so
  explicitly, with one `cache_control` breakpoint at that boundary; endpoints
  that cache by prefix on their own get the shape they need either way. Set
  `"cache": false` on a member whose gateway rejects the field.
- **The chair pays once.** A path costs the chair a line, not a copy of the
  document, and `ask_all` carries the material into round 2 and 3 by itself.

**Images are the case that matters most.** Without them the chair has to describe
the screenshot in prose — and then every member reads the *same* description, so
anything the chair misread is misread by the whole council at once, and
cross-review cannot recover it. It is the one input where passing it badly
quietly removes the independence the council is for. Png, jpeg, gif and webp go
to every member whose model can see; a member that cannot should be configured
`"vision": false`, and it then sits out the calls that carry an image rather than
answering about text alone as though it had seen the picture. The transcript
names who sat out.

**How to tell which members those are:** a member that cannot see rarely says so.
One Anthropic-compatible gateway tested while building this accepted the image
blocks, discarded them, and the model then named a colour — not "I was sent no
image", which the prompt had explicitly asked for in that case. Text material
through the same endpoint arrived intact, so nothing about the call looked wrong.
Show a member one unambiguous picture and ask what is in it; a confidently wrong
answer is the symptom, and `"vision": false` is the fix.

Two limits worth knowing. A material that cannot be read **stops the call** — a
council asked about a document it never received will answer anyway, fluently,
and read exactly like one that had. And `revision_prompt` *names* your files
rather than pasting them back, at the position the members were given them, so
open them for your own seat before you hand it the rest.

Whether this server will read a path at all depends on how it was started; over
HTTP it will not, unless its operator [named a directory](#material-over-http).
`list_council` says which, in a line above the table.

### Rounds

`ask_all(prompt, rounds=2)` runs that cross-review for you. Round 1 is the usual
parallel ask. Round 2 goes back to each member carrying the question plus every
answer from round 1 — its own and the others', verbatim — and asks it to revise:
take what is right, correct what is not, and say where it still disagrees and
why. The transcript comes back round by round, so you can see who moved and who
held their ground.

Carrying the previous round back is the whole mechanism. Members remember
nothing between calls, so without it a second round is just the same question
asked twice. Up to 3 rounds; each one costs another call per member and a longer
prompt than the last, so 1 is right for a survey of opinion and 2 for a question
where the disagreement is the interesting part.

**`rounds` is chosen before anything has been asked**, which is the one thing
wrong with it: you commit to a second round without having read the first, and a
council that turns out to agree costs exactly what one still arguing would. Ask
with `rounds=1` when you would rather look first, then buy the next round with
[`revise`](#a-subagent-as-a-full-member) — it runs exactly one more, as many
times as you judge it worth, and has no ceiling of its own. Reading before you
buy is usually the cheaper side: another round is a full call per member, while
`revise` costs you only the answers written back into it. The 3 on `ask_all` is a
ceiling on what one call will spend, not on what the discussion can have, and the
transcript says so when you reach it.

Members can also carry different [weights](#weights), for the common case where
the council is not a council of equals.

### The standing objection

A council mostly agrees, and its agreement is the least informative thing it
produces. Everything above works *against* convergence — the members are
anonymous to each other, they are never told the weights, and the closing
instruction tells them not to cave — but none of it creates any pressure to
diverge. The strongest objection to a plan is not volunteered by members who
think the plan is fine.

`steelman` seats one:

```
ask_all(prompt, rounds=3, steelman={})
```

One member writes the strongest case against whatever the table has converged on,
each round, and it goes back to everyone as an ordinary anonymous answer. In the
next round they have to deal with it.

**No member is told to argue a side it does not hold.** That is the line, and it
is what separates this from a debate mode. What the members say is still what
they think; the assignment lives in one extra call they are never told about.
Handed a seat marked "arguing against", a model discounts the argument instead of
answering it — so the provenance goes to you, in a note at the end of the
transcript, and the argument goes to them.

**It speaks every round, not once.** This is the part that looks like a detail
and is not. An objection that cannot reply to its own rebuttal is *quoted* rather
than represented: it cannot correct a misreading of itself, so by the third round
the table is arguing with its paraphrase and calling that an answer. `tenure`
buys fewer rounds than the default, and when the seat is retired early the
transcript says it was retired by configuration — because an unexplained silence
reads exactly like a position abandoned.

The mirror of that is worth as much: the last thing the objection says is the
last thing in the transcript, so nobody has been asked to take it on, and the
transcript says that too. **An objection nobody answered is not a point that
stood — it is a point that was never examined.** With `rounds=2` that is true of
everything it said, which is why the note names the setting that fixes it rather
than leaving you to notice after paying.

Read what it produces as the strongest objection this council can make to order,
never as evidence that anyone holds it. A point of its that survives being
answered is worth something; the same point in the round it appeared is worth
nothing yet.

By default the first member being asked writes it, and also answers as itself —
the two calls are unrelated as far as it knows. Name another with
`steelman={"model": "glm"}`.

### Seating an answer you already have

Your assistant is not only the chair — it can answer too, and in Claude Code or
Codex it can spawn a subagent to answer as well. Those answers used to sit
*beside* the council's, compared by hand at the end. `guests` puts them *in* it:

```
ask_all(
  prompt="What are the traps in this plan?",
  guests=[{"label": "Subagent", "text": "<what your subagent answered