An agent can put the first card on a board: a list_columns tool, and errors that name the way out #52

An agent cannot put the first card on a board, because nothing tells it what the columns are.

Verified on main at d9a214f, locally, against a board created a second earlier:

tools/list          -> ["list_boards","list_cards","add_card","move_card"]
list_cards(board)   -> []
add_card(board, column_id: "To do", ...) -> "invalid: column_id looks wrong"

add_card and move_card both require a 12-character column_id, and the only tool that ever returns one is list_cards — which is empty on a fresh board. So a Claude session handed a board link can read it, and can add a card only if some human already put one there. The direction's third seat works on a used board and dead-ends on a new one.

Done looks like

• [ ] A list_columns tool: takes board_id, returns each column's id, name, position and card count, in board order. Same access rule as list_cards — the board id is the address, an unknown id answers not_found.
• [ ] tools/list descriptions say the order of calls, so a model does not have to guess: list_columns before add_card, and list_cards before move_card.
• [ ] The two failures that send an agent down a blind alley name their way out: add_card's invalid: column_id looks wrong and not_found: no such column become call list_columns for this board's column ids. Same for move_card.
• [ ] list_boards keeps its narrow contract — boards the caller has kept, nothing else — so this adds no way to discover a board.
• [ ] Column names are someone else's text on a board anyone with the link can edit: capped, escaped where rendered, and stripped of control characters as #34 asks before they go anywhere near a terminal.
• [ ] Tests that fail without the change: list_columns on a fresh board returns the three default columns with ids; the full agent path works end to end against a board with no cards (list_boards/list_columns/add_card); an unknown board id is not_found; tools/list names five tools.
• [ ] README's Agents bullet lists the five tools and the call order. bun test green.

Files

src/mcp.ts, src/db.ts (only if a card count per column needs a query — listColumns and listCards already exist), src/mcp tests in src/server.test.ts, README.md.

Out of scope

Writing columns from MCP (add_column, rename_column, delete_column) and deleting cards. An agent that can read the board and add and move cards is the direction's ask; destructive tools on a board a stranger can reach deserve their own issue and their own review.

Risks

Pull #36 rewrites how mcp.ts publishes live events; list_columns is a read and touches none of that, but rebase on it rather than racing. Do not solve this by letting add_card take a column name — two columns can share a name, and a tool that silently picks one is worse than a tool that says what to call.

Suggested: scout, reviewed by sentinel.