# Show Stats Display

`Show_Stats_Display` renders KPI summary cards inside chat. Use it for metric rollups and compact executive summaries, not for trends, grouped comparisons, or leaderboards.

## When To Use

* Use `Show_Stats_Display` for short KPI grids, headline metrics, and scorecard-style summaries.
* Use `Show_Chart` when the output is primarily a `trend`, `comparison`, or `leaderboard`.
* Use the `govtribe-chart-graphics` shell skill when the output needs bespoke layout, chart annotations, or presentation polish.

## Contract

* Required top-level keys:
  * `id`
  * `stats`
* Optional top-level keys:
  * `title`
  * `description`
  * `locale`

## Stat Rules

* Each item in `stats` must be an object with:
  * `key`
  * `label`
  * `value`
* Optional per-stat keys:
  * `format`
  * `diff`
  * `sparkline`
* Unsupported keys are rejected instead of ignored.

## `value`

* `value` may be either:
  * plain text
  * a numeric JSON value
* If `format.kind` is `number`, `currency`, or `percent`, `value` must be a numeric JSON value, not a quoted string like `"42500000"` or `"37%"`.

## `format`

* `format` is an optional strict object, not a shorthand string and not an ad hoc bag of keys.
* Use `"compact": true` for large money or count values so KPI tiles stay compact, for example `$2.4B`, `$844.4M`, or `1.2K`.
* Supported shape:

```json
{
  "kind": "currency",
  "currency": "USD",
  "compact": true
}
```

* Supported `kind` values:
  * `text`
  * `number`
  * `currency`
  * `percent`
* Supported `basis` values for percent formatting:
  * `fraction`
  * `unit`

## `diff`

* `diff` is an optional strict object.
* Supported shape:

```json
{
  "value": 12.4,
  "decimals": 1,
  "label": "vs last quarter"
}
```

* The widget applies the sign and percent symbol automatically. Send `12.4` or `-0.8`, not `"+12.4%"`.

## `sparkline`

* `sparkline` is an optional strict object.
* Supported shape:

```json
{
  "data": [31, 34, 36, 39, 42]
}
```

* `data` must contain at least 2 numeric points.

## Canonical Example

```json
{
  "id": "capture-dashboard-kpis",
  "title": "VA IT Spending Snapshot",
  "description": "Compact KPI summary for the scoped market slice",
  "locale": "en-US",
  "stats": [
    {
      "key": "total-obligated",
      "label": "Total Obligated",
      "value": 192600000,
      "format": {
        "kind": "currency",
        "currency": "USD",
        "compact": true
      },
      "diff": {
        "value": 6.8,
        "decimals": 1,
        "label": "vs last month"
      },
      "sparkline": {
        "data": [50, 61, 113, 29],
        "color": "#125475"
      }
    },
    {
      "key": "peak-spend",
      "label": "FY2024 Peak Spend",
      "value": 113100000,
      "format": {
        "kind": "currency",
        "currency": "USD",
        "compact": true
      },
      "diff": {
        "value": 124.1,
        "decimals": 1,
        "label": "above FY2023 baseline"
      },
      "sparkline": {
        "data": [50, 113, 29],
        "color": "#2563eb"
      }
    },
    {
      "key": "set-asides",
      "label": "SDVOSB Set-Asides",
      "value": 0.91,
      "format": {
        "kind": "percent",
        "basis": "fraction",
        "decimals": 0
      },
      "diff": {
        "value": 4.2,
        "decimals": 1,
        "label": "of all set-aside awards"
      },
      "sparkline": {
        "data": [0.72, 0.81, 0.88, 0.91],
        "color": "#16a34a"
      }
    },
    {
      "key": "live-opps",
      "label": "Live IT Opportunities",
      "value": 32,
      "format": {
        "kind": "number",
        "compact": true
      },
      "diff": {
        "value": 10.3,
        "decimals": 1,
        "label": "active now"
      },
      "sparkline": {
        "data": [18, 21, 24, 32],
        "color": "#16a34a"
      }
    }
  ]
}
```

## Surface Selection

* Use `Show_Stats_Display` when the takeaway is a small set of headline metrics.
* Use `Show_Chart` when the user needs a chart grammar such as a trend, comparison, or leaderboard.
* Use `govtribe-chart-graphics` when the result needs bespoke graphics, multi-panel layout, or presentation-ready styling.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.govtribe.com/user-guide/mcp/tools/show-stats-display.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.