MedPrice AI

Lookup hospital chargemaster cost

{
  "type": "object",
  "properties": {
    "hospital_id": {
      "type": "string",
      "description": "Opaque hospital identifier from list_hospitals."
    },
    "code_type": {
      "type": "string",
      "description": "Code system the chargemaster/billing code belongs to, e.g. APR-DRG, CDM, CPT, HCPCS, MS-DRG, RC. Hospitals may also support additional proprietary code types not listed here."
    },
    "code": {
      "type": "string"
    },
    "methodologies": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "case rate",
          "fee schedule",
          "other",
          "percent of total billed charges",
          "per diem"
        ]
      },
      "description": "Pricing methodologies to price, one result per entry in request order. Omit or pass an empty array to get a single aggregate result across all methodologies."
    },
    "revision_id": {
      "type": "string",
      "description": "Optional. A revision_id from list_hospitals' per-hospital revisions array, to price that specific past revision instead of the hospital's latest one. Omit to use the latest revision."
    }
  },
  "required": [
    "hospital_id",
    "code_type",
    "code"
  ]
}

{
  "type": "object",
  "properties": {
    "hospital": {
      "type": "string",
      "description": "Hospital name returned by the MedPrice AI backend."
    },
    "found": {
      "type": "boolean",
      "description": "True if at least one entry in results was found."
    },
    "hospital_id": {
      "type": "string",
      "description": "Opaque hospital identifier to use with get_hospital_chargemaster_cost or list_hospitals."
    },
    "results": {
      "type": "array",
      "description": "One entry per requested methodology, in request order - or, when the methodologies filter was left empty, exactly one aggregate entry.",
      "items": {
        "type": "object",
        "properties": {
          "methodology": {
            "type": "string",
            "description": "Methodology this entry is scoped to. Empty when aggregated across all methodologies (the request's methodology filter was left empty)."
          },
          "found": {
            "type": "boolean",
            "description": "Whether a matching chargemaster cost record was found for this methodology."
          },
          "cost": {
            "type": "object",
            "properties": {
              "code_type": {
                "type": "string"
              },
              "code": {
                "type": "string"
              },
              "min": {
                "type": "string"
              },
              "max": {
                "type": "string"
              },
              "avg": {
                "type": "string"
              },
              "median": {
                "type": "string"
              },
              "std_dev": {
                "type": "string"
              },
              "sample_count_sum_min": {
                "type": "integer",
                "description": "Lower bound on the summed CMS sample-remittance count across contributing payer rows. Equal to sample_count_sum_max unless a de-identified '1 through 10' row narrowed it to a range."
              },
              "sample_count_sum_max": {
                "type": "integer",
                "description": "Upper bound on the summed CMS sample-remittance count across contributing payer rows. Equal to sample_count_sum_min unless a de-identified '1 through 10' row narrowed it to a range."
              },
              "sample_count_exact": {
                "type": "boolean",
                "description": "True iff sample_count_sum_min == sample_count_sum_max, i.e. no contributing row was a de-identified '1 through 10' range."
              }
            }
          },
          "description": {
            "type": "object",
            "properties": {
              "hospital_name": {
                "type": "string"
              },
              "location": {
                "type": "string"
              },
              "code_description": {
                "type": "string"
              },
              "methodology_note": {
                "type": "string"
              }
            }
          }
        }
      }
    }
  }
}

Returns the hospitals supported by the medprice.ai API, with their hospital_id (opaque handle), EIN, name, structured_locations (addresses with geocoded coordinates where available), last_updated_on, and revision history (with per-revision has_payer_data, revision_id, and added_at - when medprice itself ingested that revision, as opposed to revision_date's source-file-reported update date). Defaults to returning the entire registry (currently a few hundred hospitals) in one call. If the response's next_page_token is non-empty, the result set was truncated: call this tool again passing that exact value as page_token to get the next page, and keep doing so until next_page_token is empty - do not stop after one page and conclude the list is complete. The response's total_count field (total across all pages) can be compared against how many hospitals you've accumulated so far as a completeness check, e.g. before answering questions like 'does medprice.ai cover any hospitals in Iowa'.

{
  "type": "object",
  "properties": {
    "page_size": {
      "type": "integer",
      "description": "Maximum number of hospitals to return. Defaults to 500 (covering the entire current registry in one call), capped at 500."
    },
    "page_token": {
      "type": "string",
      "description": "Opaque token from a previous list_hospitals response's next_page_token field. Omit for the first page. Do not pass any other value (e.g. an offset or cursor you construct yourself) here."
    }
  }
}

{
  "type": "object",
  "properties": {
    "hospitals": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "hospital_id": {
            "type": "string",
            "description": "Opaque hospital identifier to use with get_hospital_chargemaster_cost."
          },
          "ein": {
            "type": "string",
            "description": "Employer Identification Number for the hospital legal entity."
          },
          "hospital_name": {
            "type": "string"
          },
          "locations": {
            "type": "array",
            "description": "Deprecated - use structured_locations instead.",
            "items": {
              "type": "string"
            }
          },
          "structured_locations": {
            "type": "array",
            "description": "Same addresses as locations, plus geocoded coordinates where available.",
            "items": {
              "type": "object",
              "properties": {
                "address": {
                  "type": "string"
                },
                "lat": {
                  "type": "number"
                },
                "lng": {
                  "type": "number"
                },
                "precision": {
                  "type": "string",
                  "enum": [
                    "LOCATION_PRECISION_UNKNOWN",
                    "LOCATION_PRECISION_STREET",
                    "LOCATION_PRECISION_CITY"
                  ],
                  "description": "Geocoding precision: STREET is a full street-address match, CITY is a city/state fallback, UNKNOWN means not yet geocoded or precision wasn't recorded."
                }
              }
            }
          },
          "last_updated_on": {
            "type": "string",
            "description": "ISO-8601 date the source file was last updated. Duplicates the last (most recent) entry in revisions."
          },
          "revisions": {
            "type": "array",
            "description": "Every known revision of this hospital's filing, oldest first. Usually a single entry.",
            "items": {
              "type": "object",
              "properties": {
                "revision_date": {
                  "type": "string",
                  "description": "ISO-8601 date this revision's source file was last updated on."
                },
                "has_payer_data": {
                  "type": "boolean",
                  "description": "Whether this revision included payer-specific negotiated-rate data, as opposed to gross/cash price only."
                },
                "revision_id": {
                  "type": "string",
                  "description": "Opaque handle for this specific revision - pass back as revision_id to get_hospital_chargemaster_cost to price this revision instead of the hospital's latest one."
                },
                "added_at": {
                  "type": "string",
                  "description": "ISO-8601 UTC timestamp of when medprice itself ingested this revision (server-set at insert time) - not derived from revision_date/last_updated_on, which reflects the source file's own self-reported update date and can lag well behind actual ingestion. Useful for sorting/highlighting by 'recently added to medprice' rather than 'recently updated by the hospital'."
                }
              }
            }
          }
        }
      }
    },
    "next_page_token": {
      "type": "string",
      "description": "Opaque pagination token, empty when there are no more results."
    },
    "total_count": {
      "type": "integer",
      "description": "Total number of hospitals matching this query, across all pages, not just this page's hospitals.length. Compare against hospitals.length (plus any prior pages) before concluding the full hospital list has been seen - e.g. before answering 'does medprice.ai support any hospitals in state X' or similar completeness questions."
    }
  }
}

Returns cost stats for every hospital with a matching chargemaster entry for a code_type/code. Use this instead of calling get_hospital_chargemaster_cost once per hospital when comparing prices for the same procedure across hospitals (e.g. "which hospital has the cheapest MS-DRG 652?"). Defaults to returning every matching hospital (currently at most a few hundred) in one call. If the response's next_page_token is non-empty, the result set was truncated: call this tool again passing that exact value as page_token to get the next page, and keep doing so until next_page_token is empty - do not stop after one page and conclude a hospital has no data for this code. The response's total_count field (total across all pages) can be compared against how many results you've accumulated so far as a completeness check.

{
  "type": "object",
  "properties": {
    "code_type": {
      "type": "string",
      "description": "Code system the chargemaster/billing code belongs to, e.g. APR-DRG, CDM, CPT, HCPCS, MS-DRG, RC. Hospitals may also support additional proprietary code types not listed here."
    },
    "code": {
      "type": "string"
    },
    "methodology": {
      "type": "string",
      "enum": [
        "case rate",
        "fee schedule",
        "other",
        "percent of total billed charges",
        "per diem"
      ],
      "description": "Pricing methodology. Omit to aggregate across all methodologies."
    },
    "page_size": {
      "type": "integer",
      "description": "Maximum number of results to return. Defaults to 500 (covering every matching hospital in one call at the current registry size), capped at 500."
    },
    "page_token": {
      "type": "string",
      "description": "Opaque token from a previous list_hospital_code_costs response's next_page_token field. Omit for the first page. Do not pass any other value (e.g. an offset or cursor you construct yourself) here."
    }
  },
  "required": [
    "code_type",
    "code"
  ]
}

{
  "type": "object",
  "properties": {
    "results": {
      "type": "array",
      "description": "One entry per hospital with a matching chargemaster entry for this code (its latest revision only) - hospitals with no data for this code are omitted, not returned with found=false.",
      "items": {
        "type": "object",
        "properties": {
          "hospital": {
            "type": "string",
            "description": "Hospital name returned by the MedPrice AI backend."
          },
          "found": {
            "type": "boolean",
            "description": "True if at least one entry in results was found."
          },
          "hospital_id": {
            "type": "string",
            "description": "Opaque hospital identifier to use with get_hospital_chargemaster_cost or list_hospitals."
          },
          "results": {
            "type": "array",
            "description": "One entry per requested methodology, in request order - or, when the methodology filter was left empty, exactly one aggregate entry.",
            "items": {
              "type": "object",
              "properties": {
                "methodology": {
                  "type": "string",
                  "description": "Methodology this entry is scoped to. Empty when aggregated across all methodologies (the request's methodology filter was left empty)."
                },
                "found": {
                  "type": "boolean",
                  "description": "Whether a matching chargemaster cost record was found for this methodology."
                },
                "cost": {
                  "type": "object",
                  "properties": {
                    "code_type": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "min": {
                      "type": "string"
                    },
                    "max": {
                      "type": "string"
                    },
                    "avg": {
                      "type": "string"
                    },
                    "median": {
                      "type": "string"
                    },
                    "std_dev": {
                      "type": "string"
                    },
                    "sample_count_sum_min": {
                      "type": "integer",
                      "description": "Lower bound on the summed CMS sample-remittance count across contributing payer rows. Equal to sample_count_sum_max unless a de-identified '1 through 10' row narrowed it to a range."
                    },
                    "sample_count_sum_max": {
                      "type": "integer",
                      "description": "Upper bound on the summed CMS sample-remittance count across contributing payer rows. Equal to sample_count_sum_min unless a de-identified '1 through 10' row narrowed it to a range."
                    },
                    "sample_count_exact": {
                      "type": "boolean",
                      "description": "True iff sample_count_sum_min == sample_count_sum_max, i.e. no contributing row was a de-identified '1 through 10' range."
                    }
                  }
                },
                "description": {
                  "type": "object",
                  "properties": {
                    "hospital_name": {
                      "type": "string"
                    },
                    "location": {
                      "type": "string"
                    },
                    "code_description": {
                      "type": "string"
                    },
                    "methodology_note": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "next_page_token": {
      "type": "string",
      "description": "Opaque pagination token, empty when there are no more results."
    },
    "total_count": {
      "type": "integer",
      "description": "Total number of matching results across all pages, not just this page's results.length. Compare against results.length (plus any prior pages) to confirm you have the complete set before concluding a hospital or code has no data."
    }
  }
}

Returns every distinct code_type (e.g. CPT, MS-DRG) with catalogued cost data, along with each type's distinct code count and total hospital reports. Unpaginated. Use this to discover which code systems have data before drilling into list_codes.

{
  "type": "object",
  "properties": {}
}

{
  "type": "object",
  "properties": {
    "code_types": {
      "type": "array",
      "description": "One entry per distinct code_type present in the catalog, most code-rich first. Unpaginated.",
      "items": {
        "type": "object",
        "properties": {
          "code_type": {
            "type": "string",
            "description": "e.g. \"CPT\""
          },
          "code_count": {
            "type": "integer",
            "description": "Distinct codes catalogued under this type."
          },
          "total_hospital_reports": {
            "type": "integer",
            "description": "Sum of hospital_count across every code under this type - NOT a distinct-hospital count (a hospital reporting many codes under one type is counted once per code)."
          }
        }
      }
    }
  }
}

Returns every distinct code catalogued under a given code_type, paginated, with each code's raw chargemaster description and the number of hospitals reporting it. Use this to discover which codes exist under a code system (e.g. all CPT codes) before looking up prices with get_hospital_chargemaster_cost or list_hospital_code_costs.

{
  "type": "object",
  "properties": {
    "code_type": {
      "type": "string",
      "description": "Code system to list codes for, e.g. \"CPT\". From list_code_types."
    },
    "page_size": {
      "type": "integer",
      "description": "Maximum number of results to return. Defaults to 500, capped at 500."
    },
    "page_token": {
      "type": "string",
      "description": "Opaque token from a previous list_codes response. Omit for the first page."
    },
    "sort": {
      "type": "string",
      "enum": [
        "CODE_SORT_UNSPECIFIED",
        "CODE_SORT_HOSPITAL_COUNT_DESC",
        "CODE_SORT_SAMPLE_COUNT_DESC",
        "CODE_SORT_CODE_DESC"
      ],
      "description": "Ordering for the returned codes. CODE_SORT_UNSPECIFIED (default) sorts code-alphabetical. CODE_SORT_HOSPITAL_COUNT_DESC sorts most-hospitals-reporting first, for pre-sorted 'top codes' pages. CODE_SORT_SAMPLE_COUNT_DESC sorts by largest pricing sample size first (total_sample_count_max) - ranks by how many billing records actually back a code's pricing, rather than by how many hospitals merely report it. CODE_SORT_CODE_DESC is code-alphabetical, reverse order."
    }
  },
  "required": [
    "code_type"
  ]
}

{
  "type": "object",
  "properties": {
    "codes": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string"
          },
          "raw_description": {
            "type": "string",
            "description": "Raw chargemaster text, picked across reporting hospitals. Not necessarily a human-readable procedure name."
          },
          "hospital_count": {
            "type": "integer",
            "description": "Distinct hospitals reporting this code (latest revision only)."
          },
          "total_sample_count_min": {
            "type": "integer",
            "description": "Lower bound on the summed CMS sample-remittance count across every reporting hospital's contributing payer rows. Equal to total_sample_count_max unless a de-identified '1 through 10' row narrowed it to a range."
          },
          "total_sample_count_max": {
            "type": "integer",
            "description": "Upper bound on the summed CMS sample-remittance count across every reporting hospital's contributing payer rows. Equal to total_sample_count_min unless a de-identified '1 through 10' row narrowed it to a range."
          },
          "total_sample_count_exact": {
            "type": "boolean",
            "description": "True iff total_sample_count_min == total_sample_count_max, i.e. no contributing hospital's sample_count was a de-identified '1 through 10' range."
          }
        }
      }
    },
    "next_page_token": {
      "type": "string",
      "description": "Opaque pagination token, empty when there are no more results."
    },
    "total_count": {
      "type": "integer",
      "description": "Total number of matching codes across all pages."
    }
  }
}