Choosing how an answer looks: render hints
Text, CardList, Table, Detail or Confirmation — the render hint a capability declares decides its shape everywhere it's used, and the model never draws it from scratch.
A capability's rendering section decides how its answer appears on screen — and it decides it once, for every channel that capability answers on. That's the whole point of declaring it here rather than leaving it to the model: the same balance card that renders on your website renders as plain text with reply buttons on WhatsApp, because the widget and the channel adapters both read the same hint.
The five hints
- Text — a sentence, with numbers and dates still drawn from a template, never typed freely.
- CardList — one card per item. Past four results, the website widget renders it as a swipeable rail on its own; that's a widget-level accessibility decision (no auto-advance, no timer), not something you configure per capability.
- Table — a real
<table>with real headers, for anything genuinely tabular (usage by day, a rate schedule). This exists specifically because a wall of numbers in a paragraph fails a screen reader in a way a table doesn't. - Detail — a single record shown in full, for a capability that returns exactly one thing.
- Confirmation — for a write capability: what's about to happen, shown before it happens, never after.
Template, item template, and numeric fields
- Template governs the top-level shape for a single result.
- Item template governs one item's shape inside a list — set this when the hint is CardList.
- Numeric fields is the list of output fields that must be rendered as numbers rather than prose. Declaring a field here is what lets the render pipeline draw it straight from your data — the model chooses that this template applies, and writes the sentence around it, but the digits themselves never pass through anything the model authored.
Leave template and item template blank if a sensible default fits your hint — they're optional, and the placeholder in the Studio says so. What isn't optional is getting the hint itself right: it's read by every channel, so a capability rendered as CardList shows up as a card on the widget and as reply-buttoned plain text on WhatsApp, automatically, with no separate authoring per channel.
Getting it wrong is visible immediately
The draft-verdict panel beside the authoring form compiles the same tool the assistant would receive, live, as you type — so a rendering choice that doesn't fit the contract's fields (a numeric field name that doesn't exist in the output schema, for instance) shows up before you save, not after a resident sees a broken card.
If you're not sure which hint fits, look at what the capability is: one fact → Text or Detail; several similar things → CardList; rows and columns of real numbers → Table; an action about to happen → Confirmation.