Skip to main content
Glama

List billing codes for a code type

list_codes
Read-only

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. Pass query to text-search codes/descriptions instead of listing a whole code_type. Pass hospital_id to restrict results to codes that one hospital actually reports.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
sortNoOrdering 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 network-wide pricing sample size first (sample_count_max, always network-wide regardless of hospital_id) - 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. CODE_SORT_RELEVANCE ranks best text match first (exact code, then code prefix, then description word-start, then description substring), ties broken by network-wide sample count descending, and is only meaningful - and the default - when query is set; without a query it behaves like CODE_SORT_SAMPLE_COUNT_DESC.
queryNoCase-insensitive text search: matches the code as a prefix, and substrings of the raw and AI-generated descriptions. Descriptions are only searched for queries of 4+ characters; shorter queries match the code prefix only. When set, code_type may be left empty to search across code types.
code_typeNoCode system to list codes for, e.g. "CPT". From list_code_types. May be left empty when query is set, to search across code types (excluding hospital-specific CDM and LOCAL codes) - CodeSummary.code_type tells the hits apart in that case.
page_sizeNoMaximum number of results to return. Defaults to 500, capped at 500.
page_tokenNoOpaque token from a previous list_codes response. Omit for the first page. Only valid with the same query/code_type/sort it was issued for.
hospital_idNoOptional hospital scoping (a hospital_id from list_hospitals): restricts results to codes that hospital actually reports on its latest revision, and makes sample_count_min/max/exact that hospital's own sample size for the code rather than the network-wide total. Unset (default) is network-wide. page_token is only valid with the same hospital_id it was issued for, same as query/code_type/sort.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
codesNo
total_countNoTotal number of matching codes across all pages.
next_page_tokenNoOpaque pagination token, empty when there are no more results.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changed
    • changedInput schema / properties / query / description
      Previous value: -"Case-insensitive text search: matches the code as a prefix, and substrings of the raw and friendly descriptions. Descriptions are only searched for queries of 4+ characters; shorter queries match the code prefix only. When set, code_type may be left empty to search across code types."New value: +"Case-insensitive text search: matches the code as a prefix, and substrings of the raw and AI-generated descriptions. Descriptions are only searched for queries of 4+ characters; shorter queries match the code prefix only. When set, code_type may be left empty to search across code types."
    • addedOutput schema / properties / codes / items / properties / ai_description
      Added value: +{
      +  "description": "LLM-normalized, human-readable description. Empty when not yet backfilled - fall back to raw_description.",
      +  "type": "string"
      +}
    • removedOutput schema / properties / codes / items / properties / friendly_description
      Removed value: -{
      -  "description": "LLM-normalized, human-readable description. Empty when not yet backfilled - fall back to raw_description.",
      -  "type": "string"
      -}
  2. Changed4 schema fields changed
    • changedOutput schema / properties / codes / items / properties / sample_count_max / description
      Previous value: -"Upper bound on the CMS sample-remittance count, same network-wide-vs-hospital-scoped convention as sample_count_min. Equal to sample_count_min unless a de-identified '1 through 10' row narrowed it to a range."New value: +"Upper bound on the CMS sample-remittance count, as a decimal string (int64 - see protoLoaderOptions.longs), same network-wide-vs-hospital-scoped convention as sample_count_min. Equal to sample_count_min unless a de-identified '1 through 10' row narrowed it to a range."
    • changedOutput schema / properties / codes / items / properties / sample_count_max / type
      Previous value: -"integer"New value: +"string"
    • changedOutput schema / properties / codes / items / properties / sample_count_min / description
      Previous value: -"Lower bound on the CMS sample-remittance count. By default (no hospital_id in the request) this sums every reporting hospital's contributing payer rows, network-wide; when the request scopes to a hospital_id, it's that one hospital's own sample count for this code instead. Equal to sample_count_max unless a de-identified '1 through 10' row narrowed it to a range."New value: +"Lower bound on the CMS sample-remittance count, as a decimal string (int64 - see protoLoaderOptions.longs). By default (no hospital_id in the request) this sums every reporting hospital's contributing payer rows, network-wide; when the request scopes to a hospital_id, it's that one hospital's own sample count for this code instead. Equal to sample_count_max unless a de-identified '1 through 10' row narrowed it to a range."
    • changedOutput schema / properties / codes / items / properties / sample_count_min / type
      Previous value: -"integer"New value: +"string"
  3. Changed15 schema fields changed
    • changedInput schema / properties / code_type / description
      Previous value: -"Code system to list codes for, e.g. \"CPT\". From list_code_types."New value: +"Code system to list codes for, e.g. \"CPT\". From list_code_types. May be left empty when query is set, to search across code types (excluding hospital-specific CDM and LOCAL codes) - CodeSummary.code_type tells the hits apart in that case."
    • addedInput schema / properties / hospital_id
      Added value: +{
      +  "description": "Optional hospital scoping (a hospital_id from list_hospitals): restricts results to codes that hospital actually reports on its latest revision, and makes sample_count_min/max/exact that hospital's own sample size for the code rather than the network-wide total. Unset (default) is network-wide. page_token is only valid with the same hospital_id it was issued for, same as query/code_type/sort.",
      +  "type": "string"
      +}
    • changedInput schema / properties / page_token / description
      Previous value: -"Opaque token from a previous list_codes response. Omit for the first page."New value: +"Opaque token from a previous list_codes response. Omit for the first page. Only valid with the same query/code_type/sort it was issued for."
    • addedInput schema / properties / query
      Added value: +{
      +  "description": "Case-insensitive text search: matches the code as a prefix, and substrings of the raw and friendly descriptions. Descriptions are only searched for queries of 4+ characters; shorter queries match the code prefix only. When set, code_type may be left empty to search across code types.",
      +  "type": "string"
      +}
    • changedInput schema / properties / sort / description
      Previous value: -"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."New value: +"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 network-wide pricing sample size first (sample_count_max, always network-wide regardless of hospital_id) - 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. CODE_SORT_RELEVANCE ranks best text match first (exact code, then code prefix, then description word-start, then description substring), ties broken by network-wide sample count descending, and is only meaningful - and the default - when query is set; without a query it behaves like CODE_SORT_SAMPLE_COUNT_DESC."
    • changedInput schema / properties / sort / enum
      Previous value: -[
      -  "CODE_SORT_UNSPECIFIED",
      -  "CODE_SORT_HOSPITAL_COUNT_DESC",
      -  "CODE_SORT_SAMPLE_COUNT_DESC",
      -  "CODE_SORT_CODE_DESC"
      -]New value: +[
      +  "CODE_SORT_UNSPECIFIED",
      +  "CODE_SORT_HOSPITAL_COUNT_DESC",
      +  "CODE_SORT_SAMPLE_COUNT_DESC",
      +  "CODE_SORT_CODE_DESC",
      +  "CODE_SORT_RELEVANCE"
      +]
    • changedInput schema / required
      Previous value: -[
      -  "code_type"
      -]New value: +[]
    • addedOutput schema / properties / codes / items / properties / code_type
      Added value: +{
      +  "description": "This code's type, e.g. \"CPT\". Always set - distinguishes hits when query was searched across code types (code_type left empty in the request).",
      +  "type": "string"
      +}
    • addedOutput schema / properties / codes / items / properties / friendly_description
      Added value: +{
      +  "description": "LLM-normalized, human-readable description. Empty when not yet backfilled - fall back to raw_description.",
      +  "type": "string"
      +}
    • addedOutput schema / properties / codes / items / properties / sample_count_exact
      Added value: +{
      +  "description": "True iff sample_count_min == sample_count_max, i.e. no contributing row was a de-identified '1 through 10' range.",
      +  "type": "boolean"
      +}
    • addedOutput schema / properties / codes / items / properties / sample_count_max
      Added value: +{
      +  "description": "Upper bound on the CMS sample-remittance count, same network-wide-vs-hospital-scoped convention as sample_count_min. Equal to sample_count_min unless a de-identified '1 through 10' row narrowed it to a range.",
      +  "type": "integer"
      +}
    • addedOutput schema / properties / codes / items / properties / sample_count_min
      Added value: +{
      +  "description": "Lower bound on the CMS sample-remittance count. By default (no hospital_id in the request) this sums every reporting hospital's contributing payer rows, network-wide; when the request scopes to a hospital_id, it's that one hospital's own sample count for this code instead. Equal to sample_count_max unless a de-identified '1 through 10' row narrowed it to a range.",
      +  "type": "integer"
      +}
    • removedOutput schema / properties / codes / items / properties / total_sample_count_exact
      Removed value: -{
      -  "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.",
      -  "type": "boolean"
      -}
    • removedOutput schema / properties / codes / items / properties / total_sample_count_max
      Removed value: -{
      -  "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.",
      -  "type": "integer"
      -}
    • removedOutput schema / properties / codes / items / properties / total_sample_count_min
      Removed value: -{
      -  "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.",
      -  "type": "integer"
      -}
  4. Changed5 schema fields changed
    • changedInput schema / properties / sort / description
      Previous value: -"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."New value: +"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."
    • changedInput schema / properties / sort / enum
      Previous value: -[
      -  "CODE_SORT_UNSPECIFIED",
      -  "CODE_SORT_HOSPITAL_COUNT_DESC"
      -]New value: +[
      +  "CODE_SORT_UNSPECIFIED",
      +  "CODE_SORT_HOSPITAL_COUNT_DESC",
      +  "CODE_SORT_SAMPLE_COUNT_DESC",
      +  "CODE_SORT_CODE_DESC"
      +]
    • addedOutput schema / properties / codes / items / properties / total_sample_count_exact
      Added value: +{
      +  "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.",
      +  "type": "boolean"
      +}
    • addedOutput schema / properties / codes / items / properties / total_sample_count_max
      Added value: +{
      +  "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.",
      +  "type": "integer"
      +}
    • addedOutput schema / properties / codes / items / properties / total_sample_count_min
      Added value: +{
      +  "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.",
      +  "type": "integer"
      +}
  5. Changed1 schema field changed
    • addedInput schema / properties / sort
      Added value: +{
      +  "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.",
      +  "enum": [
      +    "CODE_SORT_UNSPECIFIED",
      +    "CODE_SORT_HOSPITAL_COUNT_DESC"
      +  ],
      +  "type": "string"
      +}
  6. Added

TDQS

A4.5/5.0
Behavior4/5

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

Annotations already declare the safe read-only profile, and the description layers on real behavior: results are paginated, each row carries a hospital-report count, and the tool is meant as a discovery step. It does not itself explain the sort-mode semantics or the sample_count interplay (those live in the schema), so it stops short of maximal behavioral disclosure, but it adds meaningful context beyond the annotations.

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

Conciseness5/5

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

Purpose is front-loaded in the first sentence, followed by routing guidance and per-parameter hints, with no filler. Every sentence carries distinct, actionable information.

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 an output schema present, return values need not be re-explained, and the rich annotations cover safety. The description adds discovery context, pagination awareness, and QA-to-QA routing that complete the picture for calling this six-parameter listing tool correctly.

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 description coverage is 100%, so every parameter (including the enum sort modes and the query/hospital_id interactions) is already fully documented in the input schema. The description only restates the query and hospital_id intent, adding no syntax or format detail the schema lacks. 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?

Opens with a specific verb+resource: returns every distinct code under a given code_type, and enumerates what each result carries (chargemaster description, hospital count). It also names the sibling tools (get_hospital_chargemaster_cost, list_hospital_code_costs) it precedes, so an agent can place it without opening 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 Guidelines5/5

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

Gives explicit when-to-use framing ('discover which codes exist... before looking up prices'), names the alternatives, and states the conditions that switch modes: pass query to text-search instead of listing a whole code_type, pass hospital_id to scope to one hospital. Nothing is left to inference.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.