Skip to main content
Glama
cliwant

mcp-sam-gov

by cliwant
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

cms_dmepos_suppliers

Read-only

Find Medicare DMEPOS suppliers by NPI or state, with aggregate billing and payment figures: HCPCS codes, beneficiaries, claims, services, and Medicare-allowed amounts.

Instructions

Look up Medicare DMEPOS (Durable Medical Equipment) SUPPLIERS — supplier identity plus aggregate Medicare figures: HCPCS codes billed, beneficiaries served, claims, services, submitted / Medicare-allowed / Medicare-paid amounts (CMS 'Medicare DMEPOS — by Supplier', keyless; data.cms.gov data-API). The supply-side complement to cms_medicare_provider_services. Input: npi (10-digit) OR state (2-letter) — at least ONE is REQUIRED (all-empty query refused); optional size (1–100, default 25), offset. Returns { suppliers:[{ npi, supplierName, credentials, entityType, city, state, zip, totalHcpcsCodes, totalBeneficiaries, totalClaims, totalServices, submittedCharges, medicareAllowed, medicarePayment }] } + honest _meta. ★HONESTY: totalAvailable is the EXACT count from a SEPARATE stats sub-query (…/data-viewer/stats → found_rows), NEVER the returned-rows length; if that count fails, totalAvailable is null + a disclosing note (never length-faked). Aggregate/payment values are numeric-string → number|null (genuine 0 stays 0, absent → null); NPI/entityType/names are null-never-empty-string; supplierName coalesces Last_Name_Org + First_Name. Genuine no-match → honest empty; 4xx → invalid_input/not_found; 5xx → THROWS; 200 non-array/non-JSON → schema_drift. PUBLIC SUPPLIER-LEVEL AGGREGATE figures (no patient identifiers) for ONE annual vintage — NOT a fraud/quality/fitness determination.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
npiNoA 10-digit supplier National Provider Identifier (→ Suplr_NPI), e.g. '1003000126'. Provide at least this OR `state`. Validated ^\d{10}$.
sizeNoMax supplier rows to return (1–100, default 25). Offset-paginated.
stateNoA 2-letter US state/territory code (→ Suplr_Prvdr_State_Abrvtn), e.g. 'VA', 'CA'. Provide at least this OR `npi`. Validated ^[A-Za-z]{2}$.
offsetNoRow offset for pagination (default 0). Page with _meta.pagination.nextOffset.

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 already declare readOnlyHint=true, but the description goes far beyond by disclosing honest error handling (totalAvailable from a separate stats query, never length-faked), null semantics (numeric-string → number|null, null-never-empty-string), error mapping (4xx vs 5xx vs schema_drift), and the public aggregate nature of the data. This is substantial transparency beyond the annotations, with no contradictions.

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 dense and well-structured, with a clear opening sentence, input specification, output format, and honesty/error handling sections. Each sentence adds value; it is not bloated, though it could be slightly tightened. The front-loading of purpose and key constraints earns a high score.

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?

Given the tool's complexity (aggregate data, pagination, honesty guarantees, error handling) and the absence of an output schema, the description is remarkably complete. It covers output fields, _meta, pagination, null handling, error codes, and data vintage. Nothing an agent needs to call it correctly is missing.

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

Parameters3/5

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

Schema coverage is 100% and each parameter already has a detailed description including validation regexes and the requirement that at least one of npi/state be provided. The description adds minimal extra parameter semantics—it reiterates the input logic and mentions pagination via _meta, but does not materially enhance understanding 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.

Purpose5/5

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

The description states a specific verb ('Look up') and resource ('Medicare DMEPOS SUPPLIERS') and enumerates exactly what is returned (identity plus aggregate figures). It distinguishes itself from the sibling cms_medicare_provider_services by explicitly calling itself the 'supply-side complement', leaving no ambiguity about which tool to choose.

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

Usage Guidelines5/5

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

It clearly states the input requirement (npi OR state, at least one) and references the complementary sibling, giving the agent a direct alternative. It also includes usage cautions ('NOT a fraud/quality/fitness determination') that help the agent decide appropriateness. The guidance is explicit and actionable.

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