Skip to content
Back to search

meps-guarded-estimates

SkillWorks with Claude CodeGitHub

Answer U.S. health-spending, insurance and use questions from AHRQ's Medical Expenditure Panel Survey (MEPS-HC public-use files) with survey-correct estimates, AHRQ's own suppression rule, and a checkable receipt for every number. Use when someone asks for national or Census-region statistics such as mean spending, share uninsured or number of people with a visit.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/munimtechnologies--meps-est/badge.svg)](/listings/munimtechnologies--meps-est)

HTML

<a href="/listings/munimtechnologies--meps-est"><img src="/api/listings/munimtechnologies--meps-est/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

1. Download one year's files from AHRQ into a folder, e.g. for 2022: `https://meps.ahrq.gov/mepsweb/data_files/pufs/h243/h243dat.zip` and `https://meps.ahrq.gov/mepsweb/data_stats/download_data/pufs/h243/h243su.txt`. 2. Run the MCP server (stdio): `python meps_mcp.py --data-dir <folder> --receipts-dir <folder>/receipts` 3. Tools: `meps_policy`, `meps_find_variables`, `meps_check_request`, `meps_estimate`, `meps_verify_answer`, `meps_final_answer`. Agents should show the user exactly the `answer` that `meps_final_answer` returns. See [SKILL.md](SKILL.md).

Command-line use without MCP:

python meps_verify.py --answer answer.txt --receipt r1.json      # exit 0 pass, 2 blocked
python meps_frame.py  --draft draft.txt  --receipt r1.json       # exit 0 draft, 1 replaced, 2 blocked

Tests: `python -m unittest -v` (synthetic files only; no download needed).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 69 lines
  1. ---
  2. name: meps-guarded-estimates
  3. description: Answer U.S. health-spending, insurance and use questions from AHRQ's Medical Expenditure Panel Survey (MEPS-HC public-use files) with survey-correct estimates, AHRQ's own suppression rule, and a checkable receipt for every number. Use when someone asks for national or Census-region statistics such as mean spending, share uninsured or number of people with a visit.
  4. license: Apache-2.0
  5. ---
  6. # Guarded MEPS estimates
  7. Made with AI agents working in MV2's name (MV2, Munim, Inc., mv2@munimtech.com). Apache-2.0.
  8. Validation against AHRQ's published numbers is pre-registered and not yet run; see README.md.
  9. ## What this gives you
  10. An MCP server, `meps_mcp.py`, that uses only the Python standard library. It reads AHRQ's public-use
  11. files and returns design-based estimates (Taylor-series standard errors with VARSTR/VARPSU, the
  12. method AHRQ's own tables use). AHRQ's precision rule decides what may be shown. Every allowed
  13. answer comes with an analysis receipt whose id is the SHA-256 of its contents.
  14. ## Setup
  15. 1. Download the year's files from AHRQ into one folder, e.g. for 2022
  16. `https://meps.ahrq.gov/mepsweb/data_files/pufs/h243/h243dat.zip` and
  17. `https://meps.ahrq.gov/mepsweb/data_stats/download_data/pufs/h243/h243su.txt`.
  18. 2. Register the server with your client:
  19. `python meps_mcp.py --data-dir <folder> --receipts-dir <folder>/receipts`
  20. ## How to answer a question: always in this order
  21. 1. `meps_policy` once per session. Read the refusal codes and the disclosure rule.
  22. 2. `meps_find_variables` to find variable names for the year (e.g. pattern `^TOTEXP`, `^INSCOV`).
  23. 3. `meps_estimate` with the user's question in words in `question` (required) and a structured
  24. request: `year`, `stat` (mean | total | proportion | count), `variable`, `condition` (for a
  25. proportion), `domain`, `by` and `compare`. Use `{yy}` for the two-digit year,
  26. e.g. `TOTEXP{yy}`.
  27. 4. Draft the answer in plain descriptive English. Copy the numbers at the precision you show,
  28. include the 95% CI, and cite the receipt id (its first 12 characters are enough). Mark flagged
  29. cells (RSE > 30%) with an asterisk, and say "suppressed" for suppressed cells. Use digits, not
  30. number words. Do not explain why, predict, or advise.
  31. 5. Call `meps_final_answer` with the draft and the receipt ids. **Show the user exactly the
  32. `answer` it returns, and nothing else.** With `status` "replaced", the answer is a descriptive
  33. rendering of the receipts. With "blocked", it is null: tell the user the result can't be shown,
  34. and why (see `findings`). `meps_verify_answer` explains what is wrong with a draft.
  35. ## Refusals and blocks are deliberate
  36. Explain them to the user. Do not route around them, for example by splitting a refused request
  37. into pieces or by computing the number yourself:
  38. - **GEO_BELOW_REGION**: the public-use file identifies only the four Census regions. Offer the
  39. regional breakdown instead (REGIONX 1-4).
  40. - **CAUSAL_CLAIM**: a survey tabulation shows associations. Offer a descriptive comparison instead.
  41. - **RECORD_LEVEL**: no individual records, identifiers or extremes.
  42. - **INDIVIDUAL_ADVICE**: population estimates are not advice for one person.
  43. - **Suppressed cells** (fewer than 60 people, SE of 0, or RSE over 50%) have no number. Do not
  44. estimate one.
  45. ## Example
  46. Question: "What share of people under 65 were uninsured all year in 2022, by region?"
  47. ```json
  48. {"question": "What share of people under 65 were uninsured all year in 2022, by region?",
  49. "year": 2022, "stat": "proportion", "variable": "INSURC{yy}",
  50. "condition": {"op": "==", "value": 3},
  51. "domain": [{"variable": "AGELAST", "op": "<", "value": 65}],
  52. "by": {"variable": "REGIONX", "levels": [1, 2, 3, 4],
  53. "labels": {"1": "Northeast", "2": "Midwest", "3": "South", "4": "West"}}}
  54. ```
  55. ## Limits
  56. - It covers the U.S. civilian noninstitutionalized population. Dollar amounts are nominal.
  57. - Supported years are 2019-2022, one year per request. Pooled years are refused until AHRQ's pooled
  58. variance file is supported.
  59. - The question screen is a word-pattern check, used as defense in depth. The structural checks, the
  60. answer verifier and the answer frame do not depend on it.
README.md · README · 87 lines
  1. # meps-est: guarded, checkable estimates from AHRQ's Medical Expenditure Panel Survey
  2. An open toolkit, written in standard-library Python, for answering questions about U.S. health spending,
  3. insurance and health care use from AHRQ's MEPS Household Component public-use files. AI agents get
  4. an MCP server that:
  5. - computes **design-based estimates** (Taylor-series standard errors with VARSTR/VARPSU, as AHRQ's
  6. own tables do);
  7. - **refuses what the public data cannot support**: geography below Census region, record-level
  8. output, causal claims, pooled years without AHRQ's variance file, the wrong survey weight,
  9. personal advice;
  10. - applies **AHRQ's own disclosure rule** (suppress at fewer than 60 sample people or RSE > 50%;
  11. asterisk at RSE > 30%);
  12. - attaches an **analysis receipt** to every number: a JSON record whose id is the SHA-256 of
  13. its contents;
  14. - **checks the final text before anyone sees it.** `meps_verify` blocks any number that does not
  15. trace to a cited, untampered receipt. `meps_frame` (new in 0.3.0) allows free text only if
  16. every word comes from a fixed descriptive vocabulary. Anything else is replaced by a
  17. descriptive answer rendered from the receipts, or, if that cannot be done, nothing is shown.
  18. A warning never stands in for blocking.
  19. Made with AI agents working in the name of MV2 (Munim, Inc., mv2@munimtech.com). Licensed
  20. Apache-2.0. MEPS data are public-use files from the Agency for Healthcare Research and Quality
  21. (AHRQ). This project is not affiliated with or endorsed by AHRQ.
  22. ## Status: please read before relying on it
  23. | Part | Checked so far | Not yet checked |
  24. |---|---|---|
  25. | `meps_est` (survey estimator) | unit tests on synthetic data (run before every commit) | reproduction of AHRQ's published workshop outputs (2015, 2016) and of every cell of AHRQ's official 2022 health-insurance summary table, both **pre-registered and still waiting for compute** ([docs/preregistrations](docs/preregistrations)) |
  26. | `meps_guard` 0.1.1 (request policy, disclosure, receipts) | unit tests | end-to-end run on the real 2022 file; a 234-item in-sample red-team set; a 90-item blind held-out set for the question screen (all pre-registered, waiting) |
  27. | `meps_verify` 0.1.0 (answer verifier) | unit tests | a 35-case labeled benchmark (pre-registered, waiting) |
  28. | `meps_frame` 0.1.0 (answer frame) | unit tests | a blind held-out set of drafts written by someone who has not seen the vocabulary (planned) |
  29. No person has checked these modules against AHRQ's numbers yet. The pre-registrations in
  30. `docs/preregistrations/` were written before any result existed. Results will be added next to
  31. them, whichever way they come out.
  32. **One finding already shapes the design.** We hand-traced the question screen (a word-pattern
  33. check) on the blind held-out set. That trace is not a graded result, and it suggested the screen
  34. generalizes poorly. So the safety of the final text does not rest on word lists: `meps_frame` uses
  35. an allowlist, and the request policy refuses structurally (variable names, weights, years,
  36. statistics).
  37. ## Quick start
  38. 1. Download one year's files from AHRQ into a folder, e.g. for 2022:
  39. `https://meps.ahrq.gov/mepsweb/data_files/pufs/h243/h243dat.zip` and
  40. `https://meps.ahrq.gov/mepsweb/data_stats/download_data/pufs/h243/h243su.txt`.
  41. 2. Run the MCP server (stdio):
  42. `python meps_mcp.py --data-dir <folder> --receipts-dir <folder>/receipts`
  43. 3. Tools: `meps_policy`, `meps_find_variables`, `meps_check_request`, `meps_estimate`,
  44. `meps_verify_answer`, `meps_final_answer`. Agents should show the user exactly the `answer`
  45. that `meps_final_answer` returns. See [SKILL.md](SKILL.md).
  46. Command-line use without MCP:
  47. ```
  48. python meps_verify.py --answer answer.txt --receipt r1.json # exit 0 pass, 2 blocked
  49. python meps_frame.py --draft draft.txt --receipt r1.json # exit 0 draft, 1 replaced, 2 blocked
  50. ```
  51. Tests: `python -m unittest -v` (synthetic files only; no download needed).
  52. ## Files
  53. | File | What it does |
  54. |---|---|
  55. | `meps_est.py` | reads AHRQ's fixed-width files and SAS layouts; design-based totals, means and proportions with linearized SEs |
  56. | `meps_tables.py` | rebuilds AHRQ's MEPS-HC summary-table cells (used for validation against the official tables) |
  57. | `meps_guard.py` | request policy, AHRQ disclosure rule, execution and analysis receipts |
  58. | `meps_verify.py` | answer verifier: numbers must trace to cited receipts at the precision written |
  59. | `meps_frame.py` | descriptive answer frame: allowlisted vocabulary, rendered answers, final decision |
  60. | `meps_mcp.py` | the MCP server (JSON-RPC 2.0 over stdio) |
  61. | `test_*.py` | unit tests on synthetic MEPS-shaped files |
  62. | `docs/preregistrations/` | the pre-registered validation and safeguard tests |
  63. ## Limits
  64. - Covers the U.S. civilian noninstitutionalized population; one year per request (2019-2022).
  65. Dollar amounts are nominal.
  66. - The answer frame allows direction words ("higher", "lower") but does not check them against the
  67. numbers. It cannot rule out every causal reading that two descriptive sentences invite when put
  68. side by side. Answers in other languages are always replaced by the English rendered answer.
  69. - Numbers written as words are not checked by `meps_verify`, so `meps_frame` blocks them.
  70. - Survey estimates describe associations in a population. They are not causal effects and not
  71. advice for any individual.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.