# Bonus · Live data tools

The context library deliberately holds no live numbers. Files give ballpark figures and say where the current number lives. This supplement is about that "where": a small set of data tools any assistant can call for member counts, dues, engagement, or one organization's record.

At NHIA these are the `nhia-data` tools. This file describes how they're built, as patterns you can copy, and a smaller path if you don't have a data platform.

## What staff get

A staff member asks their assistant "How engaged is Acme Health this year, and who should I talk to there?" The assistant calls two tools, one for the organization's engagement and one for its people, and answers with the figures, what each one measures, and its as-of date. No report request, no spreadsheet, no free access to the database.

## The layers

Each layer rests on the one below. You can build them in this order and stop at any layer that already answers your questions.

| # | Layer | What it does |
|---|---|---|
| 1 | **Source systems** | Where data is created: membership database, learning system, online community, email platform, conference registration. |
| 2 | **Data platform** | Pulls each source on a schedule and refines it in three stages. |
| 3 | **Semantic models** | One model per subject (membership and dues, engagement, education, email, conference) with agreed definitions of each measure. |
| 4 | **A catalog of named questions** | Pre-written, reviewed queries against those models, each with a name, a description, and notes on what it measures. |
| 5 | **Scoped tools over MCP** | A small server that offers each question, or a small group of them, as a tool any assistant can call. MCP (Model Context Protocol) is the open standard Claude, ChatGPT and Copilot use to connect to tools. |
| 6 | **Staff sign-in** | Staff connect with their existing work accounts. Nobody else gets in. |

### 2 · The data platform: bronze, silver, gold

The common name for this is a **medallion** layout:

- **Bronze** is a copy of each source as it arrived, untouched, stamped with where and when it came from. If something downstream goes wrong, you can rebuild from here.
- **Silver** is cleaned and joined: correct data types, one row per organization or person, IDs that match across systems, duplicates resolved.
- **Gold** is shaped for questions: monthly engagement per organization, dues by year, conference spend by year.

Lessons worth copying:

- **Keep history for things that change.** If the source only shows today's member status, save a dated copy each time you pull it. Otherwise you can never answer "how many members did we have in March?"
- **Check each load before you trust it.** End every load with a step that counts rows, checks totals against the source, and fails loudly. Data platforms fail silently by default; a pipeline can report success with no new data.
- **Totals aren't enough.** A total can match while dollars sit under the wrong organization. Check that keys line up, and send anything that doesn't match to a person instead of an "Other" bucket.

### 3 · Semantic models

A semantic model is where "member," "active," "dues revenue" and "engaged" get defined once. Every report, dashboard and tool reads the same definitions, so the assistant's number matches the dashboard's number. If you already have dashboards (Power BI, Tableau, Looker), this layer may already exist.

### 4 · The catalog of named questions

This is the part that makes the tools safe and dependable. Instead of letting an assistant write its own database queries, you write and review the queries once:

- Each entry has a name (`org_dues`, `engagement_overview`), a plain description, and the query.
- Each entry carries its **measure and basis**: billed or paid, calendar or membership year, lifetime or this year. The tool returns that note with every answer.
- Queries are tested against known answers before they're published. When a figure is questioned, you fix the query once and every assistant gets the fix.

### 5 · Scoped tools over MCP

The tools are small and specific. NHIA's fall into three groups:

- **Organization-wide:** membership overview, dues outlook, engagement overview, education and conference statistics, email performance and reach, a spend leaderboard.
- **One organization:** find an organization by name, then its profile, dues, spend, engagement and people.
- **Self-describing:** a glossary of terms and a list of the questions the tools can answer.

**Design rules:**

- **One organization per call.** Tools that return an organization's record take one organization at a time.
- **Row caps.** Every list has a hard maximum, enforced in the server, whatever the assistant asks for.
- **No bulk export.** There is no tool that returns a full member list or a full table.
- **No free-form SQL.** The assistant can only run the reviewed questions in the catalog.
- **Self-describing.** The glossary tool keeps "member" meaning the same thing every time; the list of questions tells the assistant what's possible before it guesses.
- **Every answer names its measure, basis and as-of date.**
- **One access tier today.** Everyone who signs in can use every tool. That's a deliberate starting point. Add tiers (for example, finance tools for finance staff) when you need them.

**Lessons from running it:**

- **Put the routing in the first sentence of each tool's description.** Assistants choose tools from their descriptions. Say whether the tool covers one organization or everyone, and what to use instead.
- **Aim for one or two calls per question.** If the log shows an assistant calling a per-organization tool 20 times in a row, it's building a ranking you didn't provide a tool for. Add that tool.
- **Test the claims your design rests on.** If the design says "row-capped, no bulk export," try to break it, with data at production size. Small test data passes for the wrong reasons.
- **Know what a change touches.** Changing a query in the catalog is different from changing a tool. Check which one you changed and confirm the change actually reached staff.
- **Review usage monthly.** Log each call (tool, success or failure, time taken). Look for failed questions, slow tools and repeated calls; they show you what to fix or add next.
- **Adoption needs a nudge.** Each person connects the tools to their own assistant. Plan a short session where staff connect and ask one real question.

### 6 · Staff sign-in

Put the tool server behind your existing identity system (Microsoft Entra ID, Google Workspace, Okta), so staff sign in with their work account and nobody else can reach it. Require multi-factor authentication. Have someone review the security of the sign-in and the server before staff get access, and again before you widen access.

## Start smaller

Most associations don't have a data platform, and don't need one to start.

1. **Point, don't copy.** In your context library, every file that mentions a changing number names where the current number lives: "Current member count: the membership database, Reports > Active Members." That alone stops assistants from quoting stale figures.
2. **Use your systems' own connectors.** Many membership, learning and email platforms now offer an MCP server or an AI connector. Check what yours has before building anything. Apply the same rules: read-only, scoped, signed-in.
3. **Publish a few saved reports.** Pick the five questions staff ask most. Build each as a saved report or spreadsheet that refreshes on a schedule, in a place your assistants can already read. Name and describe each one the way you would a catalog entry, and list them in a library file such as `04-systems/data-sources.md`.
4. **Build the catalog before the platform.** Write down your top 10 questions, the exact definition behind each answer (billed or paid, which year), and where it comes from. That list becomes your glossary, your catalog, and the spec for whatever you build later.
5. **Add a tool server when the questions outgrow the reports.** A small MCP server that runs a handful of reviewed queries against one source is a reasonable first build. Keep the design rules above from day one; they're much harder to add later.

## What to put in AGENTS.md

Add a routing row and a short rule:

```text
| Live numbers: member counts, dues, engagement, one organization's record | the <data tools>, not this library |

Never quote a live figure from this library. Files give ballpark figures only.
If the session has no data tools, say so and name where the number lives. Don't estimate.
```