Skip to main content
Glama
cliwant

mcp-sam-gov

by cliwant
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

cms_hospital_compare

Read-only

Find Medicare-certified hospitals by state or name to get location, type, ownership, emergency services, and CMS star rating.

Instructions

Look up Medicare-certified hospitals by state and/or facility-name fragment — location, type, ownership, emergency-services flag, and CMS star rating (CMS Hospital Compare 'Hospital General Information', keyless; data.cms.gov provider-data datastore-query API, ~5,432 hospitals). Input: state (2-letter, EXACT) OR facilityName (case-insensitive substring) — at least ONE is REQUIRED (all-empty query refused; hospitalType alone is NOT enough to scope); optional hospitalType (substring, e.g. 'Acute', 'Critical Access'), size (1–100, default 25), offset. Returns { hospitals:[{ facilityId, facilityName, address, city, state, zip, county, phone, hospitalType, ownership, emergencyServices, overallRating }] } + honest _meta. ★HONESTY: totalAvailable is the response's EXACT top-level count for the filter set, NEVER the returned-rows length. overallRating is CMS's 1–5 star rating; 'Not Available'/blank/non-numeric → null (NEVER 0). emergencyServices normalizes 'Yes'→true / 'No'→false / else null. IDs/names/addresses are null-never-empty-string. Genuine no-match → honest empty; 4xx → invalid_input/not_found; 5xx → THROWS; 200 non-array or missing count/results → schema_drift. Filters applied SERVER-SIDE (AND-combined). Summary star rating, NOT a clinical-quality or fitness determination.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
sizeNoMax hospital rows to return (1–100, default 25). Offset-paginated.
stateNoA 2-letter US state/territory code (→ state, EXACT match), e.g. 'VA', 'CA'. Provide at least this OR `facilityName`. Validated ^[A-Za-z]{2}$.
offsetNoRow offset for pagination (default 0). Page with _meta.pagination.nextOffset.
facilityNameNoA hospital-name fragment (→ facility_name, case-insensitive SUBSTRING/contains match), e.g. 'children'. Provide at least this OR `state`. Allowed: letters/digits/space/& . , ( ) / ' - (≤100 chars).
hospitalTypeNoAn optional hospital-type filter (→ hospital_type, case-insensitive SUBSTRING/contains match), e.g. 'Acute', 'Critical Access'. Allowed: letters/digits/space/& . , ( ) / ' - (≤100 chars).

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv1.12.0

TDQS

A4.6/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only declare readOnlyHint/openWorldHint, and the description adds far beyond that: keyless access, totalAvailable-vs-count honesty, overallRating/emergencyServices normalization rules, null-never-empty-string behavior, precise error taxonomy (4xx→invalid_input/not_found, 5xx→throws, schema_drift), and server-side AND-filtering. This is exceptional disclosure with no contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long, but every clause carries operational signal: source identity, filter rules, return shape, error mapping, normalization rules, and honest-data warnings. It is dense rather than padded, though a shorter version could front-load the core lookup intent even harder.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, 5 params, and a conditional requirement, an agent would normally be left guessing. This description specifies the exact return object shape, pagination via _meta, the error contract, and rating semantics, making the tool self-sufficient for correct invocation without any supplemental knowledge.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so baseline is 3, but the description adds meaning the schema hides: the conditional requirement (at least one of state/facilityName despite required:0), the hospitalType-not-sufficient constraint, and EXACT vs SUBSTRING match semantics that reinforce the schema examples.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb + resource ('Look up Medicare-certified hospitals') plus the exact dataset source (CMS Hospital Compare 'Hospital General Information', data.cms.gov provider-data API) and the returned field set. This distinguishes it from CMS siblings like cms_facility_directory and cms_medicare_provider_services without needing to open any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides clear operational context: the filter contract (state OR facilityName required, hospitalType alone insufficient) tells an agent exactly the scenario this tool serves. It does not explicitly name alternatives or when-not-to-use conditions, but the context is unambiguous enough that an agent can route to it correctly.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools