Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@resplens-mcp How reliable is the last month of flu data for South Carolina?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Reliability-aware AI tools for US respiratory surveillance data (COVID-19, influenza, RSV).
Public health surveillance numbers are revised after publication, some weeks rest on few reporting hospitals, and some sudden jumps are reporting artifacts. An AI assistant that reads these numbers at face value will state wrong trends with confidence. resplens gives language models tools that return every value with its reliability flag, summarize what can and cannot be trusted, and reconstruct what was known on any past date.
The data come from ObsAwareData (CC BY 4.0): weekly CDC hospital admissions (NHSN), emergency department visits (NSSP), and wastewater (NWSS) for the 50 states and DC, with a flag on every value and the full revision history.
Stage | Contents | State |
A1 | Data tools and MCP server | Done |
A2 | Retrieval over data documentation; retrieval versus whole corpus in context | Done |
A3 | Agent that answers trend and reliability questions, with a task evaluation | Planned |
B1 | Real-time forecasting benchmark on as-of data | Planned |
B2 | Fine-tuned small model for tool calling | Planned |
A4 | Deployed service | Planned |
Related MCP server: OpenFDA FastMCP Server
Tool | What it returns |
| Measures, the pathogens and region types each is published for, and the reliability flag codes |
| Coverage dates, flag thresholds, ED regions, and wastewater sites for a state |
| Weekly values of one measure with a flag on every week |
| Recent data quality across hospital, ED, and wastewater sources, with plain-language caveats |
| How one week's value changed across CDC releases |
| A series exactly as it had been published on a past date |
Example: check_reliability(state="SC", pathogen="influenza", weeks=4) on the 2026-10-16 release returns, along with per-source counts:
"caveats": [
"Smoothed ED percent had an unusually large change in: 2026-09-19, 2026-09-26, 2026-10-03.",
"Wastewater influenza covers influenza A only."
]Tools never average, fill in, or reinterpret values. Invalid requests (an unknown measure, a measure that is not published for the requested region type, a date before the revision history starts) return an error message that tells the model how to correct the call.
Requires uv.
git clone https://github.com/jiandewu/resplens.git
cd resplens
uv syncClaude Code:
claude mcp add resplens -- uv run --directory /path/to/resplens resplens-mcpOther clients: run uv run --directory /path/to/resplens resplens-mcp as a stdio server.
A corpus of 28 public documents (about 74,000 words) explains the three surveillance systems: CDC dataset descriptions, reporting protocols, methodology pages, FAQs, two MMWR reports, and the ObsAwareData documentation. corpus/ keeps every source file unchanged with its URL, retrieval date, and SHA-256, plus the extracted text.
Retrieval was evaluated on a hand-reviewed set of 40 questions, each with verbatim evidence from the documents; 15 were used for tuning and 25 were held out. The four test configurations were fixed before the held-out run. On the 21 answerable held-out questions, with 300-token chunks:
Configuration | Recall@5 | Recall@10 | MRR | Latency (median) |
BM25 | 0.48 | 0.52 | 0.38 | 1 ms |
Dense ( | 0.62 | 0.76 | 0.48 | 9 ms |
Hybrid (BM25 + dense) | 0.57 | 0.71 | 0.47 | 10 ms |
Hybrid + cross-encoder rerank | 0.86 | 0.86 | 0.50 | 206 ms |
Hybrid retrieval with reranking found the evidence in the top five for 8 more questions than BM25 and none fewer (sign test p = 0.008). No configuration was reliably better at putting the evidence first. Method, findings, and failure analysis: docs/retrieval-eval.md.
The whole corpus is about 131,000 tokens and fits in a long-context model, so retrieval has to earn its place. The same generator (gemma4:31b, local) answered the 25 held-out questions twice: from the top 5 retrieved chunks, and from all 28 documents in context. An LLM judge from a different model family (qwen3:235b-thinking) graded the answers against the reviewed references and the source documents; on 15 answers graded blind by the author, the judge agreed on all 15.
Retrieval (top 5) | Whole corpus in context | |
Correct, of 21 answerable | 17 (18 counting one answer the judge could not grade) | 20 |
Unanswerable questions correctly declined | 4 of 4 | 4 of 4 |
Facts stated that are not in the corpus | 0 | 0 |
Prompt tokens per question (median) | 1,273 | 130,005 |
Seconds per question (median, one H100) | 1.7 | 125.5 |
The difference in correctness is not reliable at this sample size (3 questions to 1, p = 0.63). The long-context prompt was about 100 times larger and each answer about 73 times slower; with this model and runtime the shared document prefix could not be reused from cache. Every retrieval error came from the evidence not being retrieved, and in each case the model said the documents did not answer instead of inventing one. Details, judge calibration, and failure analysis: docs/answer-eval.md.
All data are read from one tagged ObsAwareData release (DATA_TAG in src/resplens/data.py, currently v2.0.0+2026-10-16), so answers are reproducible.
Files are downloaded on first use to ~/.cache/resplens/ (override with RESPLENS_CACHE) and checked against the release's published SHA-256 checksums.
A state's revision history is downloaded the first time get_revisions or get_as_of is called for it (about 15 MB compressed for South Carolina).
uv run pytest # offline tests on a small synthetic mirror
RESPLENS_NETWORK_TESTS=1 uv run pytest -k real # also check against the real releaseRetrieval experiments use the models extra (sentence-transformers) and, for some embedding models, a local Ollama server:
uv sync --extra models
uv run --extra models python -m resplens.retrieval.evaluate --split dev --retriever hybrid --embed-model BAAI/bge-m3 --rerankRebuilding the corpus from its sources: uv run --extra corpus python -m resplens.retrieval.corpus.
ObsAwareData is licensed under CC BY 4.0. Cite it as described in its CITATION.cff. Measure and flag descriptions in src/resplens/tools.py are adapted from its data dictionary.
CDC documents in corpus/ (Source: CDC) are public domain under CDC's Use of Agency Materials policy and are available at no charge from cdc.gov and data.cdc.gov; MMWR material is public domain under the MMWR series terms. One CMS memorandum and one National Cancer Institute (SEER) page are also included. Each document's source URL and retrieval date are in corpus/manifest.csv; files in corpus/text/ are text extracted from the originals without changes to their content.
This project is independent. Its use of these materials does not imply endorsement by CDC, ATSDR, HHS, CMS, NCI, or the United States Government.
Code: MIT. Corpus documents keep their original terms, listed above.
Summarize recent data quality across hospital, ED, and wastewater sources, with plain-language caveats.
| Name | Required | Description | Default |
|---|---|---|---|
| end | No | Last week of the window, YYYY-MM-DD; defaults to the latest hospital week. | |
| state | Yes | Two-letter postal code, e.g. "SC" or "DC". | |
| weeks | No | Number of weeks to look back. | |
| pathogen | Yes | Pathogen. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses a useful behavioral trait — that output includes plain-language caveats and spans three source types — but omits that this is a read-only operation, how missing/sparse sources are handled, and what happens when the requested window exceeds available hospital data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence with zero filler, front-loading the action and the source scope. Nothing to trim and nothing buried.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The schema is fully documented and a rich output schema exists, so return values needn't be explained. The description covers what is aggregated and the caveat framing, leaving only the 'recent' window semantics and cross-source confidence behavior lightly implicit — minor gaps for a read-only summary tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with state, pathogen, weeks, and end all documented including defaults and bounds, so the schema does the heavy lifting. The description adds nothing about parameters — notably it never clarifies that 'recent' is user-controlled via weeks/end — so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Summarize') and a specific resource ('recent data quality across hospital, ED, and wastewater sources') plus the output style ('plain-language caveats'). This clearly distinguishes it in kind from data-fetching siblings like get_series or get_revisions, though it never names an alternative explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied: an agent can infer this is the tool to consult before trusting a series, but the description never says when to call it versus get_series, get_revisions, or get_as_of. No prerequisites, no exclusions, no routing language.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the measures (with their source, pathogens, and region types) and the reliability flag codes.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the disclosure burden. 'List' implies a read-only reference operation and the description names the returned content categories, but it does not explicitly state that it is non-mutating or discuss any side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded sentence that names the resource and its included metadata without filler. Every clause contributes useful scope information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter reference-listing tool with an output schema, the description adequately identifies what is listed. It could be slightly more complete by clarifying the relationship to the reliability-checking sibling, but the core content scope is present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline is 4. There are no parameter semantics to add or compensate for.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and resource ('measures') and enumerates the included metadata: source, pathogens, region types, and reliability flag codes. It does not explicitly distinguish this reference-listing tool from siblings such as check_reliability or describe_state, so it stops short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives like describe_state or check_reliability, and no stated exclusions or prerequisites. The reference-lookup intent is only implied by 'List'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Coverage dates, flag thresholds, ED regions (HSAs), and wastewater sites for one state.
| Name | Required | Description | Default |
|---|---|---|---|
| state | Yes | Two-letter postal code, e.g. "SC" or "DC". |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden; 'describe' plus the metadata content list reasonably conveys a read-only informational tool with no side effects. It does not explicitly state that it is read-only or what happens with an invalid/unknown state code, but with an output schema present the response contents need not be restated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single compact sentence with the content categories front-loaded and no filler. It is slightly noun-phrase-like rather than verb-led, but nothing is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter metadata tool with a fully documented schema and an output schema, this is close to sufficient: the agent knows what it returns and what it takes. The remaining gap is routing guidance relative to describe_measures and the other siblings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the single 'state' parameter is documented with a two-letter postal code example, so the schema does the heavy lifting. The description only adds the implicit scoping of 'one state' — no extra semantics beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Names the resource precisely (per-state coverage metadata) and enumerates the four content areas it returns: coverage dates, flag thresholds, ED regions (HSAs), and wastewater sites. The implicit verb 'describe' is clear from the name, but it does not distinguish itself from siblings like describe_measures, so an agent must infer that this is state-level rather than measure-level metadata.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied: an agent can guess this is the lookup to run before requesting series for a state, but the description never says when to call it, what it precedes, or how it differs from describe_measures.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The series exactly as it had been published on a past date, for real-time backtests and audits.
| Name | Required | Description | Default |
|---|---|---|---|
| as_of | Yes | Publication date, YYYY-MM-DD. History starts 2025-04-04 (NHSN), 2025-08-15 (NSSP), 2026-08-07 (NWSS). | |
| start | No | Week ending date (Saturday), YYYY-MM-DD. | |
| state | Yes | Two-letter postal code, e.g. "SC" or "DC". | |
| measure | Yes | Measure name from describe_measures, e.g. "hospital_admission_count". | |
| pathogen | Yes | combined is ED visits only; not_applicable is ED participation_status only. | |
| max_weeks | No | Keep at most this many of the most recent weeks. | |
| region_id | No | HSA code or wastewater site ID (e.g. ID:113) from describe_state; required unless region_type is state. | |
| region_type | No | state; sub_state_hsa for an ED region; sampling_site for a wastewater site. | state |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the full burden and it discloses almost nothing: no permissions, no pagination/truncation behavior despite max_weeks defaulting to 104, no note that older as_of dates may be unavailable. Only the vague hint of snapshot semantics is conveyed; the availability windows live in the schema, not the description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single tight sentence with no waste and the core concept front-loaded. It is arguably too terse rather than bloated, which is a completeness issue rather than a structure one.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Eight parameters, a date-partitioned history with per-source start dates, and a default row cap of 104 weeks: this is a non-trivial tool with zero annotations and no output-schema explanation of the vintage semantics. The one sentence does not prepare an agent to call it correctly across region_type and pathogen combinations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents as_of, start, max_weeks, region_id and the pathogen enum constraints. The description adds no parameter meaning at all, leaving the baseline of 3 unmet; it merely restates the concept the as_of field already explains.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific resource (the series) and a specific temporal qualifier (as published on a past date), which is meaningfully distinct from get_series and get_revisions. It doesn't explicitly name those siblings, so the differentiation is implied rather than stated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'For real-time backtests and audits' gestures at when to use it, but never says when to use get_series or get_revisions instead. The agent must infer the boundary, and no prerequisites or exclusions are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
How one week's value changed across CDC releases: first value, latest value, and each change.
The first call for a state downloads its revision history, which can take a minute.
| Name | Required | Description | Default |
|---|---|---|---|
| week | Yes | Week ending date (Saturday), YYYY-MM-DD. | |
| state | Yes | Two-letter postal code, e.g. "SC" or "DC". | |
| measure | Yes | Measure name from describe_measures, e.g. "hospital_admission_count". | |
| pathogen | Yes | combined is ED visits only; not_applicable is ED participation_status only. | |
| region_id | No | HSA code or wastewater site ID (e.g. ID:113) from describe_state; required unless region_type is state. | |
| region_type | No | state; sub_state_hsa for an ED region; sampling_site for a wastewater site. | state |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It does disclose a genuinely useful trait — the first call for a state downloads revision history and may take a minute, implying per-state caching — but says nothing about read-only semantics, result ordering, or failure behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, both earning their place: the first defines the output shape, the second front-loads the latency caveat before the agent commits. No filler or restatement of the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists and parameter documentation is complete, so the description only needs to frame intent and cost — both are covered. The one remaining gap is not positioning this against the sibling tools that answer related revision questions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with week format, state code format, measure sourcing, pathogen enum meanings, and region_type semantics all documented in the schema. The description adds no parameter-level meaning beyond what is already structured, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific resource and scope: one week's value tracked across CDC releases, returning first value, latest value, and each change. That is concrete enough to distinguish it from a plain series fetch or an as-of snapshot, though it never names get_series or get_as_of to make the boundary explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied rather than stated: an agent can infer 'use this when you need to see how a reported figure was revised.' There is no explicit when-not guidance and no routing to siblings such as get_as_of or get_series, which cover adjacent questions about the same data.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Weekly values of one measure, latest published versions, with a reliability flag for every week.
start and end bound the weeks returned (inclusive).
| Name | Required | Description | Default |
|---|---|---|---|
| end | No | Week ending date (Saturday), YYYY-MM-DD. | |
| start | No | Week ending date (Saturday), YYYY-MM-DD. | |
| state | Yes | Two-letter postal code, e.g. "SC" or "DC". | |
| measure | Yes | Measure name from describe_measures, e.g. "hospital_admission_count". | |
| pathogen | Yes | combined is ED visits only; not_applicable is ED participation_status only. | |
| max_weeks | No | Keep at most this many of the most recent weeks. | |
| region_id | No | HSA code or wastewater site ID (e.g. ID:113) from describe_state; required unless region_type is state. | |
| region_type | No | state; sub_state_hsa for an ED region; sampling_site for a wastewater site. | state |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries the behavioral burden and does disclose key traits: weekly cadence, latest published versions only, reliability flag per week, and inclusive start/end bounds. However, it omits other behavior such as default max_weeks, region requirements, and error conditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short and front-loads what the tool returns before adding the date-bound detail. Every sentence serves a purpose and there is no redundant filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With a rich input schema and an output schema, the description does not need to explain every parameter or return field. Still, for a tool with revisions/as-of siblings and complex region options, it is somewhat thin on usage context and behavioral edge cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all eight parameters in detail. The description adds a small amount of semantics by saying start and end bound weeks inclusively, but otherwise defers to the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the resource: weekly values for one measure, with latest published versions and a reliability flag. It implies a contrast with revision/as-of tools but does not explicitly name them, so sibling differentiation is only partial.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It does not state when to use this tool versus get_revisions, get_as_of, or check_reliability. The phrase 'latest published versions' hints at the use case, but there is no explicit guidance or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0check_reliabilitydescribe_measuresdescribe_stateget_as_ofget_revisionsget_seriesScored across 6 tools
The tools mostly have clearly distinct roles: metadata discovery, state metadata, series retrieval, reliability summaries, revisions, and point-in-time snapshots. However, get_series, get_revisions, and get_as_of all return series-like values and require careful reading to choose correctly.
All names use snake_case and are generally verb-first, making the set readable and predictable. The verbs vary between describe, get, and check, and get_as_of is slightly less parallel than the other names.
Six tools is well-scoped for a focused public-health data server. Each tool covers a distinct stage of the workflow: discovery, retrieval, quality assessment, revision history, and historical backtesting.
The surface covers measure discovery, state metadata, weekly series, reliability caveats, revisions, and as-of queries, which is strong lifecycle coverage for this domain. A minor gap is the lack of an explicit list_states or region-enumeration tool, though agents can likely work around it.
US healthcare data for AI agents: CMS, FDA adverse events, CDC, NPPES NPI. Keyless, real samples.
SEC filings, Wikipedia, arXiv, US Census and more for AI agents, with every answer source-linked.
Official statistics for AI agents: Eurostat, World Bank, OECD, IMF and WHO data for 150+ countries.
Machine-readable utilities and datasets for AI agents.
