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., "@clear-pricer-mcp What does an established-patient office visit (99213) cost at each Chicago hospital?"
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.
© 2026 Trevor J. Romack — MIT-licensed (LICENSE) · tjromack@gmail.com
Ask what a procedure costs at three Chicago hospitals from any MCP client, and get back rows cited to the hospital's own price file.
A TypeScript MCP server over the public data release of clear-pricer: CMS-mandated hospital price files and the NPPES provider registry, cleaned, reconciled and published as versioned Parquet. Every tool is read-only, typed end to end, and returns provenance with every row: the hospital, its source file, that file's SHA-256 and effective date, and the release tag.
Public data only — no PHI, no keys, no accounts, no telemetry.
Demonstrates: exposing a versioned data release as typed, grain-safe MCP tools, verified by planted-bug mutations.
claude mcp add clear-pricer -- npx -y clear-pricer-mcpThen ask, for example: "What does an established-patient office visit (99213) cost at each hospital, and why is one missing?"
Claude Desktop, Cursor and other clients take the same command in their MCP config:
{ "mcpServers": { "clear-pricer": { "command": "npx", "args": ["-y", "clear-pricer-mcp"] } } }The first question about a table downloads it once from the pinned release (every table but the 117 MB charge table is under 3 MB) into your OS cache, verified against the release's manifest.
[TKTK — recorded session GIF: Claude Code answering a price question with cited rows]
MCP clients start the server with a minimal environment. If your network inspects TLS, pass your CA to Node in the server's config:
{ "mcpServers": { "clear-pricer": { "command": "npx", "args": ["-y", "clear-pricer-mcp"],
"env": { "NODE_EXTRA_CA_CERTS": "C:\\path\\to\\corporate-ca.pem" } } } }Related MCP server: RecoSearch
People who want an AI assistant to answer hospital price questions from the hospitals' own published files, with a citation they can check rather than a number they have to trust; and engineers who want a worked example of an MCP server that cannot quietly double-count, average across incomparable rows, or answer from data it has not verified.
Tool | Answers | Reads |
| "knee MRI" → billing codes, from the hospitals' own descriptions; flags codes that matched on one hospital's wording only |
|
| One code across the hospitals, for one rate basis; names hospitals that publish it another way, and how |
|
| One code at one hospital, by payer and plan, each charge cited by its position in the source file |
|
| Who an NPI was, as of a date; every version; which hospital discloses it |
|
| How far to trust each hospital's file: NPI reconciliation, template deviations, quarantined rows |
|
| Which release is served, what it was built from, and each file's verification status |
|
A question nothing in the release can answer is an error that says what was searched and what does exist, never an empty result.
99213 (CPT_CAT_I), rate basis dollar, release data-2026-10-07-67efd3d2:
- RUSH University Medical Center, outpatient: median $185.00 (range $88.00–$251.60, 15 payer plans)
— source 362174823_rush-university-medical-center_standardcharges.csv, updated 2026-09-25
- The University of Chicago Medical Center, outpatient: median $61.65 (range $61.65–$61.65, 1 payer plan)
— source 363488183_the-university-of-chicago-medical-center_standardcharges.json, updated 2026-04-01
Note: Northwestern Memorial Hospital publishes this code, but not under rate_basis 'dollar':
outpatient / algorithm_only: 6 charge rows (no dollar rate); outpatient / dollar_from_percent: 276 charge rows.All results below are from data-2026-10-07-67efd3d2; docs/results/contract-tests.md
is generated by the run itself.
Every file is verified before it is read. The SHA-256 of the release's manifest.json is pinned in
src/release.ts; the manifest pins every file; a mismatch refuses to serve (tested with tampered
files, a corrupted cache, and a wrong pin).
88 tests in four suites: unit (17), contract (46: each tool through a real MCP client over slices of the release),
end-to-end (3), and release (22: the real release recomputed against its own check_values.json).
Grain, at full scale. Joining charges to codes turns 7,371,416 charges into 22,647,893 rows (3.07×); the tools
never do. get_payer_rates' charge selection reproduces all 49,404 charge_rows in agg_code_prices with 0
mismatches, and covers exactly the 5,704,751 charges it summarises. Integer-cent checksums of the rate and gross
columns match the release.
24 planted bugs, 24 caught. npm run mutate applies each realistic bug (averaging across settings, a fanned-out
join, closed date intervals, skipped hash checks, empty answers returned as success, …), requires it to compile,
and runs every suite. The first run found a behaviour no test covered; it has one now.
Clean clone in CI on Ubuntu and Windows, Node 20 and 22, plus the release suite and the compiled server driven over stdio by an MCP client.
Not a complete or authoritative price index: three Chicago hospitals, one pinned release, the slice clear-pricer publishes, with its reconciliation failures stated there.
Not a price estimate for any patient. Published negotiated rates are contract terms, not what a given person pays.
Descriptions are the hospitals' own and can be wrong: UChicago describes CPT 44373 (small-bowel endoscopy) as a functional brain MRI. The tools surface such disagreements; they do not correct them.
The NPPES provider history (563 MB) is read remotely by HTTP range, so its row count is checked against the manifest but it is not hash-verified like every other file.
Not a hosted service: stdio only, running on the user's machine.
git clone https://github.com/tjromack/clear-pricer-mcp && cd clear-pricer-mcp
npm ci && npm test # offline, fixture-backed, a few seconds
npm run test:release # the real pinned release against its check_values.json (~120 MB download the first time)
npm run mutate # the 24-mutant suite; rewrites docs/results/
npm run build && npm run smoke # the compiled server over stdio, one question per toolDesign decisions and what was rejected are in DECISIONS.md; the build journal is docs/BUILD-LOG.md.
Negotiated-rate summary (min, quartiles, max over payer plans) for one billing code at each hospital in the release, for one rate basis, with the hospital's source file cited on every row. Hospitals that publish the code differently are listed in not_included with what they do publish.
| Name | Required | Description | Default |
|---|---|---|---|
| code | Yes | Billing code as published, e.g. CPT 99213, HCPCS J1885, MS-DRG 470. Use find_codes to get one. | |
| setting | No | Restrict to one care setting. Omit to get every setting, one row per hospital and setting. | |
| rate_basis | No | How the negotiated rate was published. 'dollar' = contracted dollar amount; 'dollar_from_percent' = a percentage of the hospital's own charge, converted to dollars; 'dollar_percent_unreconciled' = a dollar and a percentage that disagree (the dollar is used); 'algorithm_only', 'percent_only' and 'no_payer' carry no dollar rate. Compare hospitals on 'dollar' unless asked otherwise. | dollar |
| code_family | No | Only needed if the code string exists in more than one code family (the tool says so). |
| Name | Required | Description |
|---|---|---|
| code | Yes | |
| notes | Yes | |
| prices | Yes | One row per hospital × setting. Never averaged or summed across rows. |
| setting | Yes | The setting filter applied, or null for all settings |
| rate_basis | Yes | |
| code_family | Yes | |
| release_tag | Yes | |
| not_included | Yes | Hospitals with no row under this rate basis and setting, and what they publish instead |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, closed-world), and the description adds meaningful behavior beyond that: every row cites the hospital's source file, and hospitals that publish the code differently are captured in not_included rather than silently dropped. It does not discuss permissions or failure modes, but the edge-case handling disclosure is genuinely useful.
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 dense sentences with no wasted words, though it front-loads the return shape rather than the action, and both sentences are long. Still efficient and information-rich.
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 4-parameter, fully-described-schema tool with an output schema, the description is largely complete: it explains the summary statistics, the rate-basis constraint, and the not_included behavior. Missing only the routing guidance to sibling tools that would make it self-sufficient.
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 explains code, setting, rate_basis, and code_family in detail. The description only reinforces 'one rate basis' and the per-hospital scope; it adds no syntax or format detail beyond the schema, 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?
States a specific operation (negotiated-rate summary for one billing code) with explicit scope (each hospital in the release, one rate basis) and names the exact output dimensions (min, quartiles, max over payer plans). This is clearly distinguishable from detail-oriented siblings like get_payer_rates.
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: the cross-hospital summary framing suggests this is for comparing a code's rates rather than drilling into individual payer rates, and the schema (not the description) points to find_codes as a prerequisite. No explicit when-to-use/when-not statement or named alternative appears in the description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Per hospital: whether the NPIs its price file discloses resolve to it in NPPES, how many of its NPIs it leaves undisclosed, how its file departs from the CMS template (and how often), and rows quarantined. Use it to qualify any price answer.
| Name | Required | Description | Default |
|---|---|---|---|
| hospital_id | No | One hospital; omit for all three |
| Name | Required | Description |
|---|---|---|
| notes | Yes | |
| overall | Yes | clear-pricer's published ALL row across the three hospitals; not recomputed here |
| hospitals | Yes | |
| release_tag | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=false, so the safety profile is covered. The description adds interpretive context about what 'quality' comprises, but that content is largely a preview of the return payload (which an output schema already supplies) and says nothing operational such as data freshness, staleness, or cost of the call.
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, front-loaded with the 'Per hospital' scope, then the usage cue. The itemized list of quality dimensions is dense but earns its place; the parenthetical '(and how often)' is slightly clunky but informative.
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 an output schema present, the description needn't detail return values, and the single parameter is documented. Annotations cover side effects. The remaining gap is the absence of any routing guidance relative to the five sibling tools.
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 hospital_id parameter is fully documented in-schema, including the enum values and the 'omit for all three' default. The description never mentions the parameter, so it adds nothing beyond the schema — baseline 3 is appropriate.
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 enumerates exactly what the tool returns per hospital: NPI-to-NPPES resolution, undisclosed NPI counts, CMS-template departures with frequency, and quarantined rows. That is a specific, recognizable 'data quality/provenance report' distinct from price-lookup siblings like compare_code_prices and get_payer_rates. It stops short of an explicit verb framing (e.g. 'Assess the quality of...'), but the resource and scope are unambiguous.
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?
'Use it to qualify any price answer' gives a clear, actionable context for invoking the tool. There is no statement of when NOT to use it and no named alternative among the siblings, so it falls short of a full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search the hospitals' own item descriptions (as published in their price files) for billing codes, e.g. 'mri brain' or 'office visit established'. Returns each code with the hospitals that publish it and their descriptions. Use the code with compare_code_prices or get_payer_rates.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | Yes | Words to find in the hospitals' own item descriptions (e.g. 'mri brain', 'office visit established'), or a billing code. Every word must appear. Hospitals abbreviate: try 'MRI', 'CT', 'XR', 'W/O', 'Lwr Extre'. | |
| code_family | No | Restrict to one code family, e.g. CPT_CAT_I or MS-DRG | |
| hospital_id | No | Only codes this hospital publishes |
| Name | Required | Description |
|---|---|---|
| notes | Yes | |
| query | Yes | |
| results | Yes | Most widely published first, then most charge rows |
| truncated | Yes | More codes matched than `limit`; narrow the query |
| release_tag | Yes | |
| matched_words | Yes | The words every description had to contain |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover safety (readOnlyHint=true, idempotentHint=true, openWorldHint=false), so the description's job is lighter. It adds meaningful context: the source is the hospitals' own published free-text descriptions (implying messy/abbreviated data), and results combine each code with the hospitals publishing it and their descriptions. No auth or rate-limit detail, hence not a 5.
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?
Three sentences, each earning its place: what it searches, what it returns, and how to reuse the result. The verb and data source are front-loaded ahead of examples and routing.
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 an output schema present, return-value detail is not required, and annotations carry the safety profile. The description still supplies the data-source nature, result composition, and downstream routing, leaving nothing an agent needs to invoke it correctly missing.
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 75% and the schema itself already documents query matching ('every word must appear'), abbreviation hints, code_family, and hospital_id. The description's param-level value is confined to repeating example queries the schema already provides, so it adds little beyond the structured fields — baseline 3.
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 (Search) on a specific resource (hospitals' own item descriptions in their price files) for a specific outcome (billing codes), with two concrete query examples. It names the sibling tools it feeds (compare_code_prices, get_payer_rates), so an agent can place it without opening a schema.
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?
Explicitly routes the agent downstream: 'Use the code with compare_code_prices or get_payer_rates', clarifying this is the entry point in a pricing workflow. It stops short of stating when NOT to use it (e.g. when you already have a code), so it is clear context rather than full when/when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Every published charge for one billing code at one hospital: payer, plan, setting, negotiated rate (or the percentage/algorithm when no dollar figure is published), gross and cash price, with the charge's position in the hospital's source file. The first call downloads the 117 MB charge table once.
| Name | Required | Description | Default |
|---|---|---|---|
| code | Yes | Billing code as published, e.g. 99213. Use find_codes to get one. | |
| limit | No | ||
| payer | No | Case-insensitive match on payer name, e.g. 'aetna', 'blue cross' | |
| setting | No | ||
| rate_basis | No | How the negotiated rate was published. 'dollar' = contracted dollar amount; 'dollar_from_percent' = a percentage of the hospital's own charge, converted to dollars; 'dollar_percent_unreconciled' = a dollar and a percentage that disagree (the dollar is used); 'algorithm_only', 'percent_only' and 'no_payer' carry no dollar rate. Omit for every basis (each row is labelled). | |
| hospital_id | Yes | nm = Northwestern Memorial Hospital, rush = RUSH University Medical Center, uchicago = The University of Chicago Medical Center |
| Name | Required | Description |
|---|---|---|
| code | Yes | |
| notes | Yes | |
| rates | Yes | |
| returned | Yes | |
| truncated | Yes | |
| code_family | Yes | |
| hospital_id | Yes | |
| release_tag | Yes | |
| matched_charges | Yes | Distinct charge rows matching every filter |
| by_setting_and_basis | Yes | Distinct charges per setting × rate basis before the payer filter and limit; equals compare_code_prices' charge_rows |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish read-only, idempotent, closed-world behavior. The description adds genuinely new operational context: the first call downloads a 117 MB charge table once, and rows without a published dollar figure fall back to percentage/algorithm values. That first-call cost disclosure is exactly the kind of trait annotations cannot convey.
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 payload and scope, the second front-loads the one-time download cost. No filler and no repetition of the title.
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 an output schema present, the description need not spell out return values, and it complements the annotations with the download-cost note. Minor gaps remain around pagination/default limit behavior, but nothing essential to correct invocation is missing.
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 67%, so the schema already documents code, payer, rate_basis and hospital_id well. The description reinforces the rate-basis concept and the payer/plan/setting fields but says nothing about limit or result ordering, leaving part of the parameter space undocumented.
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 names a specific resource and scope: every published charge for one billing code at one hospital, enumerating the returned fields (payer, plan, setting, negotiated rate, gross/cash price). It clearly reads as a single-code lookup, though it never explicitly distinguishes itself from the sibling compare_code_prices.
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 by the scope statement (one code, one hospital), but there is no explicit when-to-use, when-not-to-use, or named alternative. The find_codes routing hint lives only in the schema for the code parameter, not in the description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Look up a National Provider Identifier in the NPPES registry history: name, entity type, status, practice address and taxonomy as of a date (or now), every version on record, and whether a hospital in the release discloses it. Validates the NPI check digit first.
| Name | Required | Description | Default |
|---|---|---|---|
| npi | Yes | National Provider Identifier, 10 digits | |
| as_of | No | Date to look the provider up as of (YYYY-MM-DD). Omit for the current registration. |
| Name | Required | Description |
|---|---|---|
| npi | Yes | |
| name | Yes | |
| as_of | Yes | The date asked about, or null for the current registration |
| notes | Yes | |
| entity | Yes | unknown = NPPES published only a deactivation notice |
| status | Yes | |
| version | Yes | |
| valid_to | Yes | |
| versions | Yes | Every version of this NPI in the release's history |
| credential | Yes | |
| provenance | Yes | |
| valid_from | Yes | |
| release_tag | Yes | |
| disclosed_by | Yes | Hospitals in the release whose price file discloses this NPI, with clear-pricer's reconciliation outcome |
| taxonomy_codes | Yes | |
| replacement_npi | Yes | |
| enumeration_date | Yes | |
| practice_address | Yes | |
| primary_taxonomy | Yes | |
| deactivation_date | Yes | |
| deactivation_reason | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, closed-world), and the description adds real behavior beyond them: it validates the NPI check digit first and returns the full version history rather than a single current record. It also gestures at a cross-reference with release data ('whether a hospital in the release discloses it'), which is disclosed behavior an agent could not infer.
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?
One front-loaded sentence that opens with the verb and resource before the return-field list, and the check-digit validation is tacked on at the end. Dense and mostly waste-free, though the trailing list of returned fields is slightly run-on.
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 an output schema present, the description needn't document return values, and annotations carry the safety profile; the temporal semantics and validation behavior round it out well. The phrase 'whether a hospital in the release discloses it' is the one mildly ambiguous element, implying a release cross-reference the agent has to guess at.
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 both parameters (npi pattern, as_of YYYY-MM-DD with 'omit for current registration') are already fully documented. The description reinforces the temporal default but adds no syntax or constraint beyond what the schema provides — the baseline 3.
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 and resource ('Look up a National Provider Identifier in the NPPES registry history') and enumerates the scope of what it returns (name, entity type, status, practice address, taxonomy, every version on record). No sibling tool touches NPIs, so the distinction from find_codes, get_payer_rates, etc. is unambiguous.
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?
The description makes clear when to use it — 'as of a date (or now)' — and what input framing it expects (a validated NPI). It never states a when-not condition or names an alternative, but no sibling overlaps this function, so the missing exclusion is low-cost.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The pinned clear-pricer release this server answers from: its tag, the manifest hash it was verified against, the hospital price files and NPPES files it was built from, and each table's row count and status.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| files | Yes | |
| origin | Yes | Where the release files are fetched from |
| fingerprint | Yes | clear-pricer's fingerprint of the release inputs |
| nppes_files | Yes | |
| price_files | Yes | |
| release_tag | Yes | |
| manifest_sha256 | Yes | Pinned in this server's source; the manifest is verified against it |
| check_values_verified | Yes | check_values.json matched the manifest's hash |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and openWorldHint=false, so the safety profile is covered. The description adds genuinely new context beyond that: the data is a 'pinned' release 'verified against' a manifest hash, telling the agent the served data is deterministic and provenance-checked. It stops short of explaining what the 'status' values mean.
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 that front-loads the core concept (the pinned release this server answers from) before the colon-delimited list of contents. No filler, though the list is dense enough that it reads as an enumeration rather than prose.
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 no parameters, a complete set of annotations, and an output schema that already documents the return shape, an agent has nearly everything it needs. The only meaningful gap is the absence of guidance on when this should be consulted versus data_quality.
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 takes zero parameters, so the baseline is 4; there is no parameter semantics for the description to compensate for. The empty input schema is consistent with the no-argument nature of the tool.
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 names the specific resource and enumerates exactly what it returns: release tag, manifest hash, source hospital price and NPPES files, and per-table row counts/statuses. An agent can identify this as the provenance/release-metadata tool. It does not explicitly distinguish itself from the nearest sibling, data_quality, which likely also reports table-level status.
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 when-to-use statement, no prerequisite, and no reference to alternatives such as data_quality or any of the lookup tools. Usage is only inferable from the enumerated return contents.
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.0compare_code_pricesdata_qualityfind_codesget_payer_rateslookup_providerrelease_infoScored across 6 tools
Each tool targets a distinct resource and action: code search (find_codes), cross-hospital price comparison (compare_code_prices), single-hospital payer detail (get_payer_rates), provider lookup (lookup_provider), data quality checks (data_quality), and release metadata (release_info). No overlapping responsibilities; the descriptions clarify the boundaries between price-related tools.
All names use snake_case and follow a verb_noun or noun_noun pattern, which is readable and consistent. Minor deviations: 'data_quality' and 'release_info' are noun phrases without a verb, unlike the others, but the overall convention is predictable.
Six tools is well-scoped for a domain focused on hospital price transparency data. Each tool serves a clear purpose: discovery, comparison, detail, provider validation, quality assurance, and provenance. No tool feels redundant or missing.
The surface covers the core lifecycle: finding codes, comparing prices across hospitals, drilling into payer rates, validating providers, assessing data quality, and retrieving release info. Minor gaps include a possible tool for bulk or geographic search, but the current set handles typical agent queries effectively.
Governed data discovery, exact queries, decisions, simulations, and runtime utilities over MCP.
Query your org's data in natural language — read-only MCP access to SQL, NoSQL, files & warehouses.
Hosted MCP server exposing US hospital procedure cost data to AI assistants
Query, join, profile, clean and convert CSV/JSON/Parquet with server-side DuckDB over MCP.
