medicare_info
Access and analyze Medicare data including provider services, hospital quality metrics, drug spending, formulary coverage, and ASP pricing for healthcare research and decision-making.
Instructions
Unified tool for Medicare data operations: provider services, Part D prescribers, hospital data, spending information, hospital quality metrics, and ASP pricing. Use the method parameter to specify the operation type.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| method | Yes | The operation to perform: - 'search_providers': Medicare Physician & Other Practitioners data - 'search_prescribers': Part D prescriber data - 'search_hospitals': Hospital utilization data - 'search_spending': Drug/service spending data - 'search_formulary': Part D formulary coverage - 'get_hospital_star_rating': Hospital overall quality star ratings (1-5) - 'get_readmission_rates': Hospital 30-day readmission rates by condition - 'get_hospital_infections': Hospital-acquired infections (HAI) data - 'get_mortality_rates': Hospital 30-day mortality rates - 'search_hospitals_by_quality': Find hospitals by quality metrics - 'compare_hospitals': Compare quality metrics across hospitals - 'get_vbp_scores': Hospital Value-Based Purchasing performance scores - 'get_hcahps_scores': Patient experience (HCAHPS) survey scores - 'get_asp_pricing': Medicare Part B ASP pricing data - 'get_asp_trend': ASP pricing trends over time - 'compare_asp_pricing': Compare ASP across drugs - 'get_formulary_trend': Track formulary changes over time (prior auth, tiers, coverage) | |
| dataset_type | No | For search_providers: Type of dataset to search. Options: - 'geography_and_service': Use when you need to compare regions, analyze geographic patterns, study regional variations in healthcare delivery, understand geographic distribution of healthcare services, or calculate per-capita/per-beneficiary rates by region. - 'provider_and_service': Use when you need to analyze individual provider performance, track specific procedures by provider, calculate total procedures across providers, or study provider-level service patterns and outcomes. - 'provider': Use when you need to analyze provider demographics, study provider participation in Medicare, understand provider practice patterns, or examine provider-level beneficiary characteristics and risk scores. | |
| year | No | For search_providers: Year of the dataset to query (2013 to latest available year, defaults to latest year). | |
| hcpcs_code | No | For search_providers: HCPCS code to search for (e.g., '99213' for established patient office visit). | |
| provider_type | No | For search_providers: Type of provider to search for (e.g., 'Cardiology', 'Podiatry', 'Family Practice'). | |
| geo_level | No | For search_providers: Geographic level for filtering (e.g., 'National', 'State', 'County', 'ZIP'). | |
| geo_code | No | For search_providers: Geographic code to filter by (e.g., 'CA' for California, '06037' for Los Angeles County). | |
| place_of_service | No | For search_providers: Place of service code to filter by (e.g., 'F' for facility, 'O' for office, 'H' for hospital). | |
| size | No | Number of results to return (default: 10 for search_providers, 25 for search_formulary, max: 5000). | |
| offset | No | Starting result number for pagination (default: 0). | |
| sort_by | No | For search_providers: Field to sort results by (e.g., 'Tot_Srvcs', 'Tot_Benes', 'Tot_Mdcr_Pymt_Amt'). | |
| sort_order | No | For search_providers: Sort order ('asc' or 'desc', default: 'desc'). | |
| drug_name | No | For search_prescribers: Drug name to search for - brand or generic (e.g., 'semaglutide', 'Ozempic', 'metformin'). Searches both brand and generic names. | |
| prescriber_type | No | For search_prescribers: Prescriber specialty (e.g., 'Endocrinology', 'Family Practice', 'Internal Medicine'). | |
| prescriber_npi | No | For search_prescribers: National Provider Identifier (NPI) of the prescriber. | |
| state | No | For search_prescribers, search_hospitals: State abbreviation (e.g., 'CA', 'TX', 'NY'). | |
| hospital_name | No | For search_hospitals: Hospital name (partial match supported). | |
| hospital_id | No | For search_hospitals: CMS Certification Number (CCN) or provider ID. | |
| drg_code | No | For search_hospitals (inpatient): Diagnosis Related Group (DRG) code. | |
| spending_drug_name | No | For search_spending: Drug name for spending analysis (brand or generic). | |
| spending_type | No | For search_spending: Type of spending data - 'part_d' (prescription drugs), 'part_b' (administered drugs). Default: 'part_d'. | |
| formulary_drug_name | No | For search_formulary: Drug name to search for (partial match supported, e.g., 'metformin', 'insulin'). At least one of formulary_drug_name or ndc_code is required. | |
| ndc_code | No | For search_formulary: NDC (National Drug Code) for exact drug identification (e.g., '00002143380'). At least one of drug_name or ndc_code is required. | |
| tier | No | For search_formulary: Tier number to filter by (1=Preferred Generic, 2=Generic, 3=Preferred Brand, 4=Non-Preferred Brand, 5=Specialty, 6=Select Care). | |
| requires_prior_auth | No | For search_formulary: Filter by prior authorization requirement (true=requires PA, false=no PA required). | |
| has_quantity_limit | No | For search_formulary: Filter by quantity limit (true=has limit, false=no limit). | |
| has_step_therapy | No | For search_formulary: Filter by step therapy requirement (true=requires ST, false=no ST required). | |
| plan_state | No | For search_formulary: State abbreviation to filter plans (e.g., 'CA', 'TX', 'NY'). | |
| plan_id | No | For search_formulary: Medicare Part D plan ID to filter by specific plan. | |
| quality_hospital_id | No | For hospital quality methods: CMS Certification Number (CCN) to lookup specific hospital (e.g., '050146'). | |
| quality_state | No | For hospital quality methods: State abbreviation to filter hospitals (e.g., 'CA', 'TX', 'NY'). | |
| min_star_rating | No | For search_hospitals_by_quality: Minimum star rating (1-5) to filter hospitals. | |
| condition | No | For get_readmission_rates/get_mortality_rates: Medical condition to filter by (e.g., 'heart_failure', 'pneumonia', 'heart_attack', 'copd', 'stroke'). | |
| infection_type | No | For get_hospital_infections: Type of infection (e.g., 'CLABSI', 'CAUTI', 'SSI', 'CDIFF', 'MRSA'). | |
| metrics | No | For compare_hospitals: Array of metrics to compare (e.g., ['star_rating', 'readmission_rate', 'mortality_rate', 'infection_rate']). | |
| hospital_ids | No | For compare_hospitals: Array of hospital CCN IDs to compare. | |
| hcpcs_code_asp | No | For ASP pricing methods: HCPCS code for Part B drug (e.g., 'J9035' for Bevacizumab). | |
| quarter | No | For get_asp_pricing: Quarter for ASP data (e.g., '2025Q1', '2024Q4'). | |
| start_quarter | No | For get_asp_trend: Starting quarter for trend analysis (e.g., '2023Q1'). | |
| end_quarter | No | For get_asp_trend: Ending quarter for trend analysis (e.g., '2025Q1'). | |
| hcpcs_codes | No | For compare_asp_pricing: Array of HCPCS codes to compare pricing. | |
| hcahps_measure | No | For get_hcahps_scores: HCAHPS measure ID to filter by (e.g., 'H_COMP_1_A_P' for nurse communication, 'H_HSP_RATING_9_10' for hospital rating 9-10). | |
| vbp_domain | No | For get_vbp_scores: VBP domain to filter by ('clinical_outcomes', 'person_community_engagement', 'safety', 'efficiency_cost_reduction', or 'all' for total performance score). | |
| start_month | No | For get_formulary_trend: Starting month in YYYYMM format (e.g., '202401' for January 2024). | |
| end_month | No | For get_formulary_trend: Ending month in YYYYMM format (e.g., '202512' for December 2025). | |
| trend_metric | No | For get_formulary_trend: Metric to track ('prior_auth', 'tier', 'quantity_limit', 'coverage', or 'all'). Default: 'all'. |
Implementation Reference
- src/index.ts:118-407 (schema)Complete definition of the 'medicare_info' tool including name, detailed description, comprehensive input schema with all parameters for various methods, response schema, and usage examples.export const MEDICARE_INFO_TOOL: Tool = { name: "medicare_info", description: "Unified tool for Medicare data operations: provider services, Part D prescribers, hospital data, spending information, hospital quality metrics, and ASP pricing. Use the method parameter to specify the operation type.", input_schema: { type: "object", properties: { method: { type: "string", description: "The operation to perform:\n" + "- 'search_providers': Medicare Physician & Other Practitioners data\n" + "- 'search_prescribers': Part D prescriber data\n" + "- 'search_hospitals': Hospital utilization data\n" + "- 'search_spending': Drug/service spending data\n" + "- 'search_formulary': Part D formulary coverage\n" + "- 'get_hospital_star_rating': Hospital overall quality star ratings (1-5)\n" + "- 'get_readmission_rates': Hospital 30-day readmission rates by condition\n" + "- 'get_hospital_infections': Hospital-acquired infections (HAI) data\n" + "- 'get_mortality_rates': Hospital 30-day mortality rates\n" + "- 'search_hospitals_by_quality': Find hospitals by quality metrics\n" + "- 'compare_hospitals': Compare quality metrics across hospitals\n" + "- 'get_vbp_scores': Hospital Value-Based Purchasing performance scores\n" + "- 'get_hcahps_scores': Patient experience (HCAHPS) survey scores\n" + "- 'get_asp_pricing': Medicare Part B ASP pricing data\n" + "- 'get_asp_trend': ASP pricing trends over time\n" + "- 'compare_asp_pricing': Compare ASP across drugs\n" + "- 'get_formulary_trend': Track formulary changes over time (prior auth, tiers, coverage)" }, dataset_type: { type: "string", description: "For search_providers: Type of dataset to search. Options:\n" + "- 'geography_and_service': Use when you need to compare regions, analyze geographic patterns, study regional variations in healthcare delivery, understand geographic distribution of healthcare services, or calculate per-capita/per-beneficiary rates by region.\n" + "- 'provider_and_service': Use when you need to analyze individual provider performance, track specific procedures by provider, calculate total procedures across providers, or study provider-level service patterns and outcomes.\n" + "- 'provider': Use when you need to analyze provider demographics, study provider participation in Medicare, understand provider practice patterns, or examine provider-level beneficiary characteristics and risk scores." }, year: { type: "string", description: "For search_providers: Year of the dataset to query (2013 to latest available year, defaults to latest year)." }, hcpcs_code: { type: "string", description: "For search_providers: HCPCS code to search for (e.g., '99213' for established patient office visit)." }, provider_type: { type: "string", description: "For search_providers: Type of provider to search for (e.g., 'Cardiology', 'Podiatry', 'Family Practice')." }, geo_level: { type: "string", description: "For search_providers: Geographic level for filtering (e.g., 'National', 'State', 'County', 'ZIP')." }, geo_code: { type: "string", description: "For search_providers: Geographic code to filter by (e.g., 'CA' for California, '06037' for Los Angeles County)." }, place_of_service: { type: "string", description: "For search_providers: Place of service code to filter by (e.g., 'F' for facility, 'O' for office, 'H' for hospital)." }, size: { type: "number", description: "Number of results to return (default: 10 for search_providers, 25 for search_formulary, max: 5000)." }, offset: { type: "number", description: "Starting result number for pagination (default: 0)." }, sort_by: { type: "string", description: "For search_providers: Field to sort results by (e.g., 'Tot_Srvcs', 'Tot_Benes', 'Tot_Mdcr_Pymt_Amt')." }, sort_order: { type: "string", description: "For search_providers: Sort order ('asc' or 'desc', default: 'desc')." }, drug_name: { type: "string", description: "For search_prescribers: Drug name to search for - brand or generic (e.g., 'semaglutide', 'Ozempic', 'metformin'). Searches both brand and generic names." }, prescriber_type: { type: "string", description: "For search_prescribers: Prescriber specialty (e.g., 'Endocrinology', 'Family Practice', 'Internal Medicine')." }, prescriber_npi: { type: "string", description: "For search_prescribers: National Provider Identifier (NPI) of the prescriber." }, state: { type: "string", description: "For search_prescribers, search_hospitals: State abbreviation (e.g., 'CA', 'TX', 'NY')." }, hospital_name: { type: "string", description: "For search_hospitals: Hospital name (partial match supported)." }, hospital_id: { type: "string", description: "For search_hospitals: CMS Certification Number (CCN) or provider ID." }, drg_code: { type: "string", description: "For search_hospitals (inpatient): Diagnosis Related Group (DRG) code." }, spending_drug_name: { type: "string", description: "For search_spending: Drug name for spending analysis (brand or generic)." }, spending_type: { type: "string", description: "For search_spending: Type of spending data - 'part_d' (prescription drugs), 'part_b' (administered drugs). Default: 'part_d'." }, formulary_drug_name: { type: "string", description: "For search_formulary: Drug name to search for (partial match supported, e.g., 'metformin', 'insulin'). At least one of formulary_drug_name or ndc_code is required." }, ndc_code: { type: "string", description: "For search_formulary: NDC (National Drug Code) for exact drug identification (e.g., '00002143380'). At least one of drug_name or ndc_code is required." }, tier: { type: "number", description: "For search_formulary: Tier number to filter by (1=Preferred Generic, 2=Generic, 3=Preferred Brand, 4=Non-Preferred Brand, 5=Specialty, 6=Select Care)." }, requires_prior_auth: { type: "boolean", description: "For search_formulary: Filter by prior authorization requirement (true=requires PA, false=no PA required)." }, has_quantity_limit: { type: "boolean", description: "For search_formulary: Filter by quantity limit (true=has limit, false=no limit)." }, has_step_therapy: { type: "boolean", description: "For search_formulary: Filter by step therapy requirement (true=requires ST, false=no ST required)." }, plan_state: { type: "string", description: "For search_formulary: State abbreviation to filter plans (e.g., 'CA', 'TX', 'NY')." }, plan_id: { type: "string", description: "For search_formulary: Medicare Part D plan ID to filter by specific plan." }, quality_hospital_id: { type: "string", description: "For hospital quality methods: CMS Certification Number (CCN) to lookup specific hospital (e.g., '050146')." }, quality_state: { type: "string", description: "For hospital quality methods: State abbreviation to filter hospitals (e.g., 'CA', 'TX', 'NY')." }, min_star_rating: { type: "number", description: "For search_hospitals_by_quality: Minimum star rating (1-5) to filter hospitals." }, condition: { type: "string", description: "For get_readmission_rates/get_mortality_rates: Medical condition to filter by (e.g., 'heart_failure', 'pneumonia', 'heart_attack', 'copd', 'stroke')." }, infection_type: { type: "string", description: "For get_hospital_infections: Type of infection (e.g., 'CLABSI', 'CAUTI', 'SSI', 'CDIFF', 'MRSA')." }, metrics: { type: "array", description: "For compare_hospitals: Array of metrics to compare (e.g., ['star_rating', 'readmission_rate', 'mortality_rate', 'infection_rate'])." }, hospital_ids: { type: "array", description: "For compare_hospitals: Array of hospital CCN IDs to compare." }, hcpcs_code_asp: { type: "string", description: "For ASP pricing methods: HCPCS code for Part B drug (e.g., 'J9035' for Bevacizumab)." }, quarter: { type: "string", description: "For get_asp_pricing: Quarter for ASP data (e.g., '2025Q1', '2024Q4')." }, start_quarter: { type: "string", description: "For get_asp_trend: Starting quarter for trend analysis (e.g., '2023Q1')." }, end_quarter: { type: "string", description: "For get_asp_trend: Ending quarter for trend analysis (e.g., '2025Q1')." }, hcpcs_codes: { type: "array", description: "For compare_asp_pricing: Array of HCPCS codes to compare pricing." }, hcahps_measure: { type: "string", description: "For get_hcahps_scores: HCAHPS measure ID to filter by (e.g., 'H_COMP_1_A_P' for nurse communication, 'H_HSP_RATING_9_10' for hospital rating 9-10)." }, vbp_domain: { type: "string", description: "For get_vbp_scores: VBP domain to filter by ('clinical_outcomes', 'person_community_engagement', 'safety', 'efficiency_cost_reduction', or 'all' for total performance score)." }, start_month: { type: "string", description: "For get_formulary_trend: Starting month in YYYYMM format (e.g., '202401' for January 2024)." }, end_month: { type: "string", description: "For get_formulary_trend: Ending month in YYYYMM format (e.g., '202512' for December 2025)." }, trend_metric: { type: "string", description: "For get_formulary_trend: Metric to track ('prior_auth', 'tier', 'quantity_limit', 'coverage', or 'all'). Default: 'all'." } }, required: ["method"] }, responseSchema: { type: "object", properties: { total: { type: "number", description: "Total number of results found" }, providers: { type: "array", description: "List of Medicare providers matching the search criteria", items: { type: "object", properties: { npi: { type: "string", description: "Provider's National Provider Identifier (NPI)" }, provider_name: { type: "string", description: "Provider's full name" }, provider_type: { type: "string", description: "Provider's specialty or type of practice" }, provider_address: { type: "string", description: "Provider's street address" }, provider_city: { type: "string", description: "Provider's city" }, provider_state: { type: "string", description: "Provider's state (2-letter abbreviation)" }, provider_zip: { type: "string", description: "Provider's ZIP code" }, provider_country: { type: "string", description: "Provider's country code (typically 'US')" }, medicare_participating: { type: "string", description: "Whether the provider participates in Medicare ('Y' for yes, 'N' for no)" }, total_hcpcs_codes: { type: "number", description: "Total number of unique HCPCS codes used by the provider" }, total_beneficiaries: { type: "number", description: "Total number of unique Medicare beneficiaries served" }, total_services: { type: "number", description: "Total number of services provided" }, total_submitted_charges: { type: "number", description: "Total amount of submitted charges in dollars" }, total_medicare_allowed: { type: "number", description: "Total amount allowed by Medicare in dollars" }, total_medicare_payment: { type: "number", description: "Total amount paid by Medicare in dollars" }, total_medicare_standardized: { type: "number", description: "Total standardized Medicare payment amount in dollars (adjusted for geographic differences)" }, beneficiary_average_age: { type: "number", description: "Average age of beneficiaries served" }, beneficiary_age_lt_65: { type: "number", description: "Number of beneficiaries under 65 years old" }, beneficiary_age_65_74: { type: "number", description: "Number of beneficiaries aged 65-74" }, beneficiary_age_75_84: { type: "number", description: "Number of beneficiaries aged 75-84" }, beneficiary_age_gt_84: { type: "number", description: "Number of beneficiaries over 84 years old" }, beneficiary_female_count: { type: "number", description: "Number of female beneficiaries" }, beneficiary_male_count: { type: "number", description: "Number of male beneficiaries" }, beneficiary_race_white: { type: "number", description: "Number of white beneficiaries" }, beneficiary_race_black: { type: "number", description: "Number of black beneficiaries" }, beneficiary_race_api: { type: "number", description: "Number of Asian/Pacific Islander beneficiaries" }, beneficiary_race_hispanic: { type: "number", description: "Number of Hispanic beneficiaries" }, beneficiary_race_native: { type: "number", description: "Number of Native American beneficiaries" }, beneficiary_race_other: { type: "number", description: "Number of beneficiaries of other races" }, beneficiary_dual_count: { type: "number", description: "Number of dual-eligible beneficiaries (eligible for both Medicare and Medicaid)" }, beneficiary_non_dual_count: { type: "number", description: "Number of non-dual-eligible beneficiaries" }, beneficiary_average_risk_score: { type: "number", description: "Average risk score of beneficiaries (higher scores indicate more complex medical conditions)" } } } } } }, examples: [ { name: 'Search for office visit codes by state (2023 data)', description: 'Search for office visit codes by state (2023 data)', input: { "dataset_type": "geography_and_service", "year": "2023", "hcpcs_code": "99213", "geo_level": "State", "geo_code": "CA", "size": 5, "sort_by": "Tot_Srvcs", "sort_order": "desc" }, output: { "total": 5, "providers": [{ "npi": "1234567890", "provider_name": "Dr. Jane Smith", "provider_type": "Family Practice", "provider_address": "789 Health St", "provider_city": "Los Angeles", "provider_state": "CA", "provider_zip": "90001", "provider_country": "US", "medicare_participating": "Y", "total_hcpcs_codes": 10, "total_beneficiaries": 100, "total_services": 500, "total_submitted_charges": 50000, "total_medicare_allowed": 40000, "total_medicare_payment": 35000, "total_medicare_standardized": 34000, "beneficiary_average_age": 70, "beneficiary_age_lt_65": 20, "beneficiary_age_65_74": 30, "beneficiary_age_75_84": 25, "beneficiary_age_gt_84": 25, "beneficiary_female_count": 55, "beneficiary_male_count": 45, "beneficiary_race_white": 60, "beneficiary_race_black": 10, "beneficiary_race_api": 15, "beneficiary_race_hispanic": 10, "beneficiary_race_native": 2, "beneficiary_race_other": 3, "beneficiary_dual_count": 15, "beneficiary_non_dual_count": 85, "beneficiary_average_risk_score": 1.2 }] } }, { name: 'Search for providers by specialty with pagination', description: 'Search for providers by specialty with pagination', input: { "dataset_type": "provider", "provider_type": "Podiatry", "geo_level": "State", "geo_code": "NY", "size": 10, "offset": 20, "sort_by": "Tot_Mdcr_Pymt_Amt", "sort_order": "desc" }, output: { "total": 10, "providers": [{ "npi": "0987654321", "provider_name": "Dr. John Doe", "provider_type": "Podiatry", "provider_address": "123 Foot Ave", "provider_city": "New York", "provider_state": "NY", "provider_zip": "10001", "provider_country": "US", "medicare_participating": "Y", "total_hcpcs_codes": 8, "total_beneficiaries": 80, "total_services": 400, "total_submitted_charges": 40000, "total_medicare_allowed": 32000, "total_medicare_payment": 28000, "total_medicare_standardized": 27000, "beneficiary_average_age": 65, "beneficiary_age_lt_65": 15, "beneficiary_age_65_74": 25, "beneficiary_age_75_84": 20, "beneficiary_age_gt_84": 20, "beneficiary_female_count": 45, "beneficiary_male_count": 35, "beneficiary_race_white": 50, "beneficiary_race_black": 8, "beneficiary_race_api": 12, "beneficiary_race_hispanic": 8, "beneficiary_race_native": 1, "beneficiary_race_other": 1, "beneficiary_dual_count": 10, "beneficiary_non_dual_count": 70, "beneficiary_average_risk_score": 1.1 }] } }, { name: 'Search for specific procedure by place of service', description: 'Search for specific procedure by place of service', input: { "dataset_type": "provider_and_service", "hcpcs_code": "45378", "place_of_service": "O", "size": 5, "sort_by": "Tot_Srvcs", "sort_order": "desc" }, output: { "total": 5, "providers": [{ "npi": "1122334455", "provider_name": "Dr. Alice Johnson", "provider_type": "Gastroenterology", "provider_address": "456 Digestive Blvd", "provider_city": "Chicago", "provider_state": "IL", "provider_zip": "60601", "provider_country": "US", "medicare_participating": "Y", "total_hcpcs_codes": 12, "total_beneficiaries": 120, "total_services": 600, "total_submitted_charges": 60000, "total_medicare_allowed": 48000, "total_medicare_payment": 42000, "total_medicare_standardized": 41000, "beneficiary_average_age": 68, "beneficiary_age_lt_65": 25, "beneficiary_age_65_74": 35, "beneficiary_age_75_84": 30, "beneficiary_age_gt_84": 30, "beneficiary_female_count": 60, "beneficiary_male_count": 60, "beneficiary_race_white": 70, "beneficiary_race_black": 15, "beneficiary_race_api": 20, "beneficiary_race_hispanic": 15, "beneficiary_race_native": 3, "beneficiary_race_other": 3, "beneficiary_dual_count": 20, "beneficiary_non_dual_count": 100, "beneficiary_average_risk_score": 1.3 }] } }, { name: 'Get total knee replacement procedures in California (2023)', description: 'Search for all providers performing knee replacements (HCPCS 27447) in California, sorted by total services to get the top 100 providers', input: { "dataset_type": "provider_and_service", "year": "2023", "hcpcs_code": "27447", "geo_level": "State", "geo_code": "CA", "size": 100, "sort_by": "Tot_Srvcs", "sort_order": "desc" }, output: { "total": 100, "providers": [{ "npi": "1234567890", "provider_name": "Dr. John Smith", "provider_type": "Orthopedic Surgery", "provider_address": "123 Medical Center Dr", "provider_city": "Los Angeles", "provider_state": "CA", "provider_zip": "90024", "provider_country": "US", "medicare_participating": "Y", "total_hcpcs_codes": 15, "total_beneficiaries": 95, "total_services": 120, "total_submitted_charges": 1200000, "total_medicare_allowed": 960000, "total_medicare_payment": 840000, "total_medicare_standardized": 820000, "beneficiary_average_age": 72, "beneficiary_age_lt_65": 15, "beneficiary_age_65_74": 35, "beneficiary_age_75_84": 30, "beneficiary_age_gt_84": 20, "beneficiary_female_count": 65, "beneficiary_male_count": 30, "beneficiary_race_white": 70, "beneficiary_race_black": 5, "beneficiary_race_api": 10, "beneficiary_race_hispanic": 10, "beneficiary_race_native": 1, "beneficiary_race_other": 4, "beneficiary_dual_count": 10, "beneficiary_non_dual_count": 85, "beneficiary_average_risk_score": 1.2 }], "total_services": 4958 } } ] };
- src/index.ts:2136-2144 (registration)MCP server registration of the medicare_info tool, making it discoverable via listTools request.server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: [ { name: MEDICARE_INFO_TOOL.name, description: MEDICARE_INFO_TOOL.description, inputSchema: MEDICARE_INFO_TOOL.input_schema } ] }));
- src/index.ts:2145-2357 (handler)Primary MCP tool call handler for 'medicare_info'. Parses arguments, dispatches to specific method handlers (search_providers, etc.) via switch statement, and returns JSON-formatted results.server.setRequestHandler(CallToolRequestSchema, async (request) => { const toolName = request.params?.name; const args = request.params?.arguments; try { switch (toolName) { case 'medicare_info': { const method = (args as any)?.method; switch (method) { case 'search_providers': { const result = await searchMedicare( (args as any)?.dataset_type, (args as any)?.year, (args as any)?.hcpcs_code, (args as any)?.geo_level, (args as any)?.geo_code, (args as any)?.place_of_service, (args as any)?.size, (args as any)?.offset, (args as any)?.text_search, (args as any)?.sort, (args as any)?.provider_type ); return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }], isError: false }; } case 'search_prescribers': { const result = await searchPrescribers( (args as any)?.drug_name, (args as any)?.prescriber_npi, (args as any)?.prescriber_type, (args as any)?.state, (args as any)?.size, (args as any)?.offset, (args as any)?.sort ); return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }], isError: false }; } case 'search_hospitals': { const result = await searchHospitals( (args as any)?.hospital_name, (args as any)?.hospital_id, (args as any)?.state, (args as any)?.city, (args as any)?.drg_code, (args as any)?.size, (args as any)?.offset, (args as any)?.sort ); return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }], isError: false }; } case 'search_spending': { const result = await searchSpending( (args as any)?.spending_drug_name, (args as any)?.spending_type, (args as any)?.year, (args as any)?.size, (args as any)?.offset, (args as any)?.sort ); return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }], isError: false }; } case 'search_formulary': { const result = await searchFormulary( (args as any)?.formulary_drug_name, (args as any)?.ndc_code, (args as any)?.tier, (args as any)?.requires_prior_auth, (args as any)?.has_quantity_limit, (args as any)?.has_step_therapy, (args as any)?.plan_state, (args as any)?.plan_id, (args as any)?.size, (args as any)?.offset ); return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }], isError: false }; } case 'get_hospital_star_rating': { const result = await getHospitalStarRating( (args as any)?.quality_hospital_id, (args as any)?.quality_state, (args as any)?.size, (args as any)?.offset ); return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }], isError: false }; } case 'get_readmission_rates': { const result = await getReadmissionRates( (args as any)?.quality_hospital_id, (args as any)?.quality_state, (args as any)?.condition, (args as any)?.size, (args as any)?.offset ); return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }], isError: false }; } case 'get_hospital_infections': { const result = await getHospitalInfections( (args as any)?.quality_hospital_id, (args as any)?.quality_state, (args as any)?.infection_type, (args as any)?.size, (args as any)?.offset ); return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }], isError: false }; } case 'get_mortality_rates': { const result = await getMortalityRates( (args as any)?.quality_hospital_id, (args as any)?.quality_state, (args as any)?.condition, (args as any)?.size, (args as any)?.offset ); return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }], isError: false }; } case 'search_hospitals_by_quality': { const result = await searchHospitalsByQuality( (args as any)?.quality_state, (args as any)?.min_star_rating, (args as any)?.size, (args as any)?.offset ); return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }], isError: false }; } case 'compare_hospitals': { const result = await compareHospitals( (args as any)?.hospital_ids, (args as any)?.metrics, (args as any)?.size ); return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }], isError: false }; } case 'get_vbp_scores': { const result = await getVbpScores( (args as any)?.quality_hospital_id, (args as any)?.quality_state, (args as any)?.vbp_domain, (args as any)?.size, (args as any)?.offset ); return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }], isError: false }; } case 'get_hcahps_scores': { const result = await getHcahpsScores( (args as any)?.quality_hospital_id, (args as any)?.quality_state, (args as any)?.hcahps_measure, (args as any)?.size, (args as any)?.offset ); return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }], isError: false }; } case 'get_asp_pricing': { const result = await getAspPricing( (args as any)?.hcpcs_code_asp, (args as any)?.quarter ); return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }], isError: false }; } case 'get_asp_trend': { const result = await getAspTrend( (args as any)?.hcpcs_code_asp, (args as any)?.start_quarter, (args as any)?.end_quarter ); return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }], isError: false }; } case 'compare_asp_pricing': { const result = await compareAspPricing( (args as any)?.hcpcs_codes, (args as any)?.quarter ); return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }], isError: false }; } case 'get_formulary_trend': { const result = await getFormularyTrend( (args as any)?.start_month, (args as any)?.end_month, (args as any)?.drug_name, (args as any)?.rxcui, (args as any)?.trend_metric ); return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }], isError: false }; } default: throw new McpError(-32602, `Unknown method: ${method}. Valid methods: search_providers, search_prescribers, search_hospitals, search_spending, search_formulary, get_hospital_star_rating, get_readmission_rates, get_hospital_infections, get_mortality_rates, search_hospitals_by_quality, compare_hospitals, get_vbp_scores, get_hcahps_scores, get_asp_pricing, get_asp_trend, compare_asp_pricing, get_formulary_trend`); } } default: throw new McpError(-32603, 'Unknown tool'); } } catch (error) { throw new McpError(-32603, error instanceof Error ? error.message : String(error)); } });
- src/index.ts:502-678 (helper)Key helper function implementing 'search_providers' method. Queries CMS Medicare Physician datasets (3 types: geography/service, provider/service, provider-only), applies filters/sorting/pagination, standardizes response.async function searchMedicare( dataset_type: string = "geography_and_service", year?: string, hcpcs_code?: string, geo_level?: string, geo_code?: string, place_of_service?: string, size: number = 10, offset: number = 0, text_search?: string, sort?: { field: string; direction: 'asc' | 'desc' }, provider_type?: string ) { let datasetVersionId: string; let selectedYear: string; if (dataset_type === "geography_and_service") { selectedYear = year || getLatestYear(versionMapGeography); datasetVersionId = versionMapGeography[selectedYear]; } else if (dataset_type === "provider_and_service") { selectedYear = year || getLatestYear(versionMapProviderAndService); datasetVersionId = versionMapProviderAndService[selectedYear]; } else if (dataset_type === "provider") { selectedYear = year || getLatestYear(versionMapProvider); datasetVersionId = versionMapProvider[selectedYear]; } else { throw new Error(`Invalid dataset_type: ${dataset_type}`); } if (!datasetVersionId) { throw new Error(`Invalid year specified: ${selectedYear} for dataset_type: ${dataset_type}`); } const query = new URLSearchParams({ size: Math.min(size, 5000).toString(), offset: offset.toString() }); // Add filters using the CMS API filter syntax if (geo_level && geo_code) { if (dataset_type === "geography_and_service") { query.append("filter[Rndrng_Prvdr_Geo_Lvl]", geo_level); query.append("filter[Rndrng_Prvdr_Geo_Cd]", geo_code); } else { // For provider_and_service and provider datasets if (geo_level === "State") { query.append("filter[Rndrng_Prvdr_State_Abrvtn]", geo_code); } else if (geo_level === "County") { query.append("filter[Rndrng_Prvdr_State_FIPS]", geo_code); } else if (geo_level === "ZIP") { query.append("filter[Rndrng_Prvdr_Zip5]", geo_code); } } } if (hcpcs_code && (dataset_type === "geography_and_service" || dataset_type === "provider_and_service")) { query.append("filter[HCPCS_Cd]", hcpcs_code); } if (place_of_service && (dataset_type === "geography_and_service" || dataset_type === "provider_and_service")) { query.append("filter[Place_Of_Srvc]", place_of_service); } if (provider_type && (dataset_type === "provider_and_service" || dataset_type === "provider")) { query.append("filter[Rndrng_Prvdr_Type]", provider_type); } if (text_search) { // Add text search filter for relevant fields based on dataset type if (dataset_type === "provider" || dataset_type === "provider_and_service") { query.append("Rndrng_Prvdr_Last_Org_Name", text_search); query.append("Rndrng_Prvdr_First_Name", text_search); } if (dataset_type === "geography_and_service" || dataset_type === "provider_and_service") { query.append("HCPCS_Desc", text_search); } } if (sort) { query.append("sort", `${sort.direction === 'desc' ? '-' : ''}${sort.field}`); } const url = `https://data.cms.gov/data-api/v1/dataset/${datasetVersionId}/data?${query.toString()}`; const response = await fetch(url); if (!response.ok) { throw new Error(`HTTP error! status: ${response.status}`); } const data = await response.json() as (MedicareProviderGeographyResponse[] | MedicareProviderIndividualResponse[] | MedicareProviderResponse[]); return { total: data.length, providers: data.map((item) => { if (dataset_type === "provider") { const providerItem = item as MedicareProviderResponse; return { npi: providerItem.Rndrng_NPI, provider_name: `${providerItem.Rndrng_Prvdr_Last_Org_Name}, ${providerItem.Rndrng_Prvdr_First_Name}${providerItem.Rndrng_Prvdr_MI ? ` ${providerItem.Rndrng_Prvdr_MI}` : ''}`, provider_type: providerItem.Rndrng_Prvdr_Type, provider_address: providerItem.Rndrng_Prvdr_St1, provider_city: providerItem.Rndrng_Prvdr_City, provider_state: providerItem.Rndrng_Prvdr_State_Abrvtn, provider_zip: providerItem.Rndrng_Prvdr_Zip5, provider_country: providerItem.Rndrng_Prvdr_Cntry, medicare_participating: providerItem.Rndrng_Prvdr_Mdcr_Prtcptg_Ind, total_hcpcs_codes: parseInt(providerItem.Tot_HCPCS_Cds), total_beneficiaries: providerItem.Tot_Benes, total_services: providerItem.Tot_Srvcs, total_submitted_charges: providerItem.Tot_Sbmtd_Chrg, total_medicare_allowed: providerItem.Tot_Mdcr_Alowd_Amt, total_medicare_payment: providerItem.Tot_Mdcr_Pymt_Amt, total_medicare_standardized: providerItem.Tot_Mdcr_Stdzd_Amt, beneficiary_average_age: providerItem.Bene_Avg_Age, beneficiary_age_lt_65: providerItem.Bene_Age_LT_65_Cnt, beneficiary_age_65_74: providerItem.Bene_Age_65_74_Cnt, beneficiary_age_75_84: providerItem.Bene_Age_75_84_Cnt, beneficiary_age_gt_84: providerItem.Bene_Age_GT_84_Cnt, beneficiary_female_count: providerItem.Bene_Feml_Cnt, beneficiary_male_count: providerItem.Bene_Male_Cnt, beneficiary_race_white: providerItem.Bene_Race_Wht_Cnt, beneficiary_race_black: providerItem.Bene_Race_Black_Cnt, beneficiary_race_api: providerItem.Bene_Race_API_Cnt, beneficiary_race_hispanic: providerItem.Bene_Race_Hspnc_Cnt, beneficiary_race_native: providerItem.Bene_Race_NatInd_Cnt, beneficiary_race_other: providerItem.Bene_Race_Othr_Cnt, beneficiary_dual_count: providerItem.Bene_Dual_Cnt, beneficiary_non_dual_count: providerItem.Bene_Ndual_Cnt, beneficiary_average_risk_score: providerItem.Bene_Avg_Risk_Scre }; } if (dataset_type === "geography_and_service") { const geoItem = item as MedicareProviderGeographyResponse; return { hcpcs_code: geoItem.HCPCS_Cd, hcpcs_desc: geoItem.HCPCS_Desc, hcpcs_drug_ind: geoItem.HCPCS_Drug_Ind, place_of_service: geoItem.Place_Of_Srvc, total_beneficiaries: geoItem.Tot_Benes, total_services: geoItem.Tot_Srvcs, total_beneficiary_days: geoItem.Tot_Bene_Day_Srvcs, avg_submitted_charge: geoItem.Avg_Sbmtd_Chrg, avg_medicare_allowed: geoItem.Avg_Mdcr_Alowd_Amt, avg_medicare_payment: geoItem.Avg_Mdcr_Pymt_Amt, avg_medicare_standardized: geoItem.Avg_Mdcr_Stdzd_Amt, geo_level: geoItem.Rndrng_Prvdr_Geo_Lvl, geo_code: geoItem.Rndrng_Prvdr_Geo_Cd, geo_desc: geoItem.Rndrng_Prvdr_Geo_Desc, total_providers: geoItem.Tot_Rndrng_Prvdrs }; } else { const providerItem = item as MedicareProviderIndividualResponse; return { hcpcs_code: providerItem.HCPCS_Cd, hcpcs_desc: providerItem.HCPCS_Desc, hcpcs_drug_ind: providerItem.HCPCS_Drug_Ind, place_of_service: providerItem.Place_Of_Srvc, total_beneficiaries: providerItem.Tot_Benes, total_services: providerItem.Tot_Srvcs, total_beneficiary_days: providerItem.Tot_Bene_Day_Srvcs, avg_submitted_charge: providerItem.Avg_Sbmtd_Chrg, avg_medicare_allowed: providerItem.Avg_Mdcr_Alowd_Amt, avg_medicare_payment: providerItem.Avg_Mdcr_Pymt_Amt, avg_medicare_standardized: providerItem.Avg_Mdcr_Stdzd_Amt, npi: providerItem.Rndrng_NPI, provider_name: `${providerItem.Rndrng_Prvdr_Last_Org_Name}, ${providerItem.Rndrng_Prvdr_First_Name}${providerItem.Rndrng_Prvdr_MI ? ` ${providerItem.Rndrng_Prvdr_MI}` : ''}`, provider_type: providerItem.Rndrng_Prvdr_Type, provider_address: providerItem.Rndrng_Prvdr_St1, provider_city: providerItem.Rndrng_Prvdr_City, provider_state: providerItem.Rndrng_Prvdr_State_Abrvtn, provider_zip: providerItem.Rndrng_Prvdr_Zip5, provider_country: providerItem.Rndrng_Prvdr_Cntry, medicare_participating: providerItem.Rndrng_Prvdr_Mdcr_Prtcptg_Ind }; } }) }; }
- src/types.ts:1-39 (schema)TypeScript interface defining the structure of MCP Tool objects, used for medicare_info tool definition.export interface Tool { name: string; description: string; input_schema: { type: string; properties: { [key: string]: { type: string; description: string; default?: any; }; }; required: string[]; }; responseSchema: { type: string; properties: { [key: string]: { type: string; description: string; items?: { type: string; properties: { [key: string]: { type: string; description: string; }; }; }; }; }; }; examples: Array<{ name: string; description: string; input: Record<string, any>; output: Record<string, any>; }>; }