ADR 0033 — Human-readable confirmation cards (v54-F3)
Date: 2026-07-17 · Status: accepted
Context
The confirmation card showed a raw tool name (dispatch_run) and raw
JSON args. The user's field-test words: "i don't get a valid info what
it is asking me to approve." The plain-English descriptions already
existed in TOOL_SPECS — but only the model ever saw them; the action
event sent {action_id, tool, args} and the card rendered JSON.
Decision
-
The card carries the spec's description. A
tool_description(name)lookup overTOOL_SPECSfeeds adescriptionfield on every surface a card is born or replayed from: the live SSE action event, the chat-detail actions (replay), and the command-deck POST response. It is derived, never stored — thechat_actionsrow is unchanged. -
Args render as labeled key-value pairs, not raw JSON. String values inline and wrapping; nested values (e.g.
batch_dispatch.tasks) stay JSON but under a labeled key. A display concern only — the server sendsargsunchanged. -
No new trust surface. The description is the same text the model sees in the tool spec — same trust level as the tool name and args the card already showed. Per the house rule, tool descriptions are load-bearing: keeping them truthful now serves the human AND the model.
-
Messenger channels deferred with a named trigger. The channel confirm-card renderer (
render_confirm_card) is the shell-command card, a different surface; the chat-action card on Telegram gets only the tool name. Piping the description through three transports waits for a field test showing an unreadable card on a specific channel.
Consequences
- You can tell what you're approving at a glance;
register_mcp_serverorset_policycards explain themselves. - An unknown tool name yields
description: ""and the card renders as before (no empty line).