Skip to main content
A read-only gateway decides what an agent may read. Documentation decides whether what it reads means anything. Column names don’t tell an agent that status = 3 means refunded, that orders.total excludes tax, that rows are soft-deleted so every query needs deleted_at IS NULL, or that users was superseded by accounts in a migration nobody finished. Without that, an agent writes confident, wrong SQL — and the first bad number costs more trust than a dozen right ones earn, because now there’s no way to tell which earlier answers were also wrong.

​
How documentation gets written

1

Profile

TeamDuo reads the schema and profiles the actual data: value distributions on low-cardinality columns, null rates, min and max on dates, distinct counts, orphan rates across declared foreign keys.This is where the value is. “status: integer, nullable” helps nobody. “status is one of pending | paid | refunded | disputed, and 94% of rows are paid” changes what an agent writes.
2

Generate

An agent drafts documentation per table from the schema and the profile.
3

Review

Drafts land as drafts. A human reads them and accepts the ones that are right. Nothing reaches a querying agent on the strength of having been generated.
4

Publish

Published documentation is served to every agent querying that database, through describe_datasource and search_docs.

​
Agents can write documentation too

An agent that just worked something out the hard way is the best possible author — that knowledge was learned in use rather than guessed from names. It’s also the one kind of documentation nothing can automatically check, which is why it lands as a draft. A section rewritten with write_documentation is pinned: regenerating the documentation leaves it alone. Correcting something by hand is not work you should have to do twice.
publish_documentation is not reversible in the sense that matters. Other agents will act on what you publish. Withdrawing it later doesn’t retract the queries written in the meantime — publish only what you’re confident is true of this database.

​
Writing documentation that helps

Say what the schema cannot:
subscriptions.status — one of trialing, active, past_due, canceled. past_due rows still count as active revenue until day 30.
Not what it already says:
subscriptions.status — a string column on the subscriptions table.
The second is a restatement of describe_datasource. The first is the reason an agent gets the number right.