Raw schema
{
"type": "object",
"properties": {
"change_pct": {
"type": "number",
"default": 0
},
"note": {
"type": "string",
"description": "Usually omit this. Optional one-line insight rendered inside the card. Only pass it when you ALREADY have the figures in hand from a call you made for another reason — never make an extra tool call just to write a note, because that round trip delays the card itself. When you do add one, say something the card does not already show (what drove a change, what to watch), in one sentence, and never guess a number.",
"default": ""
},
"periodLabel": {
"type": "string",
"default": "Past 12 months"
},
"change": {
"type": "number",
"description": "The change over the period, in the same unit as `current`. Send it together with `start` whenever you have them: the card leads with this figure, and left out it has to work back from `change_pct`, which is close but not the real number.",
"default": 0
},
"start": {
"type": "number",
"default": 0
},
"valueFormat": {
"description": "How the hero value and change are formatted.",
"default": "currency",
"type": "string",
"enum": [
"currency",
"number"
]
},
"upIsGood": {
"type": "boolean",
"description": "false for cost-like metrics: an increase renders red, a decrease green.",
"default": true
},
"title": {
"type": "string",
"default": "Trend"
},
"points": {
"type": "array",
"items": {
"type": "object",
"properties": {
"value": {
"type": "number"
},
"series": {
"type": "string"
},
"label": {
"type": "string"
}
}
}
},
"nextSteps": {
"type": "array",
"items": {
"type": "string"
},
"description": "One short follow-up the user might ask next, in the form icon|question — 'calendar|Show me last month'. Phrase the question the way the user would say it, and take the icon from the table in the app instructions; any other name renders blank. Always supply 2-3. The card itself ignores them."
},
"current": {
"type": "number",
"default": 0
},
"chartStyle": {
"description": "'bar' draws discrete bars on a labelled x axis — better for comparing periods against each other, and the only style that stacks series. 'line' is the continuous trend.",
"default": "line",
"type": "string",
"enum": [
"line",
"bar"
]
},
"valueSuffix": {
"type": "string",
"description": "Optional unit appended to values, e.g. ' subs' or '/mo'.",
"default": ""
},
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"detail": {
"type": "string"
},
"color": {
"type": "string"
},
"value": {
"type": "number"
},
"prompts": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"description": "Optional rows under the chart — the composition behind the number (accounts behind a net worth, categories behind a month's spend). Each is { name, detail, value, color?, prompts? }. `color` is a named colour for the dot ('blue', 'green', …); omit it and rows are coloured in order. `prompts` are follow-up questions offered when the row is tapped — each string is shown as the menu label AND sent to the assistant verbatim, so keep them short and self-contained ('How has my Brokerage changed?', not 'changed?'). OMIT `prompts` unless a row needs something its name cannot imply: left out, the card builds its own drill-down from `name`, which saves you writing the same sentence once per row."
}
},
"description": "Any metric over time that has no dedicated card — one category's spend by month, a series you computed. Points are {label, value} in display order. Set upIsGood=false for cost-like metrics. Use chartStyle:'bar' whenever the user compares periods — month by month, or over the last 3/6/12 months; give each point a `series` name (repeating the label once per series) to stack them with a legend. Pass `items` to list the composition behind the number."
}