Skip to main content
Glama

medical-codes-mcp-server

by io.github.cyanheads
OverviewDiscussionsAdmin

Browse Code Hierarchy

medcode_browse_hierarchy
Read-onlyIdempotent

Walk a US medical code system's hierarchy for discovery without a search term. With no node, returns the top-level entries (ICD-10-CM categories, HCPCS range buckets, or ICD-10-PCS first-axis values). With a node, returns its immediate children. ICD-10-CM and HCPCS use a prefix hierarchy (a shorter code is the parent of a longer one); ICD-10-PCS is axis-based — each of its 7 characters is an independent axis (section, body system, root operation, body part, approach, device, qualifier), but only the top-level Section axis is browsable (omit node): positions 2–7 are context-dependent on the preceding axis path and are not enumerable from a flat partial code. Lets an agent orient in an unfamiliar system or enumerate a category's specific codes. A large child set paginates: when the response carries a nextCursor, pass it back as cursor to fetch the next page.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
nodeNoA node to expand — or omit / pass an empty string for the top level. For ICD-10-CM/HCPCS, a code whose children to list; ICD-10-PCS supports only top-level Section browsing. Must not be blank or whitespace-only when provided.
limitNoMax entries per page. Defaults to MEDCODE_MAX_RESULTS (50), ceiling 200.
cursorNoOpaque continuation token from a previous response's `nextCursor`, to fetch the next page of children/entries. Omit for the top of the list.
systemYesThe code system to browse.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
capNoThe page size that was applied.
axesNoThe top-level ICD-10-PCS Section axis values (only the Section axis is enumerable). Empty when kind is "codes".
kindNo"codes" for prefix-hierarchy children (ICD-10-CM/HCPCS); "axes" for ICD-10-PCS axis values.
codesNoChild codes under the requested node or top level. Empty when kind is "axes".
errorNoPresent when the call failed. Absent on success.
shownNoNumber of entries returned on this page (codes or axes).
noticeNoGuidance when a node has no children/axes — suggests the top level or a valid node.
truncatedNoTrue when more entries exist beyond this page.
nextCursorNoOpaque token to pass back as `cursor` for the next page. Present only when more entries exist beyond this page.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changed
    • changedOutput schema / properties / codes / items / properties / billable / description
      Previous value: -"True when the code is a billable leaf."New value: +"True when the code is a billable leaf. Null when the system has no billing concept."
    • changedOutput schema / properties / codes / items / properties / billable / type
      Previous value: -"boolean"New value: +[
+  "boolean",
+  "null"
+]
  2. Changed6 schema fields changed
    • removedOutput schema / properties / codes / items / properties / chapter / anyOf
      Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
    • addedOutput schema / properties / codes / items / properties / chapter / type
      Added value: +[
+  "string",
+  "null"
+]
    • removedOutput schema / properties / codes / items / properties / description / anyOf
      Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
    • addedOutput schema / properties / codes / items / properties / description / type
      Added value: +[
+  "string",
+  "null"
+]
    • removedOutput schema / properties / codes / items / properties / shortDescription / anyOf
      Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
    • addedOutput schema / properties / codes / items / properties / shortDescription / type
      Added value: +[
+  "string",
+  "null"
+]
  3. Changed6 schema fields changed
    • changedInput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
    • addedInput schema / additionalProperties
      Added value: +false
    • changedOutput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
    • addedOutput schema / anyOf
      Added value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "kind",
+      "codes",
+      "axes",
+      "truncated",
+      "shown",
+      "cap"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]
    • addedOutput schema / properties / error
      Added value: +{
+  "additionalProperties": {},
+  "description": "Present when the call failed. Absent on success.",
+  "properties": {
+    "code": {
+      "description": "JSON-RPC error code for this failure.",
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "data": {
+      "additionalProperties": {},
+      "properties": {
+        "reason": {
+          "description": "Machine-readable failure mode. Declared by this tool: `unknown_node`: The node does not exist in the system — for ICD-10-PCS, also when it uses a character outside the axis alphabet or begins no bundled code. Other values are possible when a failure originates below the handler.",
+          "examples": [
+            "unknown_node"
+          ],
+          "type": "string"
+        },
+        "recovery": {
+          "additionalProperties": {},
+          "description": "Actionable next step for the caller.",
+          "properties": {
+            "hint": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "hint"
+          ],
+          "type": "object"
+        },
+        "retryable": {
+          "description": "Whether retrying may succeed.",
+          "type": "boolean"
+        }
+      },
+      "type": "object"
+    },
+    "message": {
+      "description": "Human-readable description of what went wrong.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "code",
+    "message"
+  ],
+  "type": "object"
+}
    • removedOutput schema / required
      Removed value: -[
-  "kind",
-  "codes",
-  "axes",
-  "truncated",
-  "shown",
-  "cap"
-]
  4. Changed3 schema fields changed
    • addedInput schema / properties / node / anyOf
      Added value: +[
+  {
+    "const": "",
+    "type": "string"
+  },
+  {
+    "description": "A code whose children to list (ICD-10-CM/HCPCS). ICD-10-PCS supports only top-level Section browsing — a partial PCS code does not expand to next-position axis values.",
+    "minLength": 1,
+    "type": "string"
+  }
+]
    • changedInput schema / properties / node / description
      Previous value: -"A node to expand. For ICD-10-CM/HCPCS, a code whose children to list. ICD-10-PCS supports only top-level Section browsing (omit `node`) — a partial PCS code does not expand to next-position axis values. Omit for the top level."New value: +"A node to expand — or omit / pass an empty string for the top level. For ICD-10-CM/HCPCS, a code whose children to list; ICD-10-PCS supports only top-level Section browsing. Must not be blank or whitespace-only when provided."
    • removedInput schema / properties / node / type
      Removed value: -"string"
  5. Changed6 schema fields changed
    • addedInput schema / properties / cursor
      Added value: +{
+  "description": "Opaque continuation token from a previous response's `nextCursor`, to fetch the next page of children/entries. Omit for the top of the list.",
+  "type": "string"
+}
    • changedInput schema / properties / limit / description
      Previous value: -"Max entries to return. Defaults to MEDCODE_MAX_RESULTS (50), ceiling 200."New value: +"Max entries per page. Defaults to MEDCODE_MAX_RESULTS (50), ceiling 200."
    • changedOutput schema / properties / cap / description
      Previous value: -"The limit that was applied."New value: +"The page size that was applied."
    • addedOutput schema / properties / nextCursor
      Added value: +{
+  "description": "Opaque token to pass back as `cursor` for the next page. Present only when more entries exist beyond this page.",
+  "type": "string"
+}
    • changedOutput schema / properties / shown / description
      Previous value: -"Number of entries returned (codes or axes)."New value: +"Number of entries returned on this page (codes or axes)."
    • changedOutput schema / properties / truncated / description
      Previous value: -"True when the returned list was capped at the limit."New value: +"True when more entries exist beyond this page."
  6. Changed2 schema fields changed
    • changedInput schema / properties / node / description
      Previous value: -"A node to expand. For ICD-10-CM/HCPCS, a code whose children to list. For ICD-10-PCS, a partial code whose next-position axis values to list. Omit for the top level."New value: +"A node to expand. For ICD-10-CM/HCPCS, a code whose children to list. ICD-10-PCS supports only top-level Section browsing (omit `node`) — a partial PCS code does not expand to next-position axis values. Omit for the top level."
    • changedOutput schema / properties / axes / description
      Previous value: -"Valid next-position axis values for a partial PCS code. Empty when kind is \"codes\"."New value: +"The top-level ICD-10-PCS Section axis values (only the Section axis is enumerable). Empty when kind is \"codes\"."
  7. First observed

TDQS

A4.6/5.0
Behavior5/5

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

Annotations already mark this read-only and idempotent, so the description earn extra credit by disclosing hierarchy semantics: prefix vs axis-based structure, which positions are browsable, the fact that positions 2–7 are context-dependent, and pagination via `nextCursor`/`cursor`. This goes well beyond the annotations and prevents incorrect calls.

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?

The description is dense but every sentence earns its place. The core purpose and no-search-term qualifier are front-loaded, and the lengthy ICD-10-PCS explanation is necessary to prevent invalid browsing attempts. There is no fluff or repetition of the schema.

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

Completeness4/5

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

Given the tool's complexity, the description is nearly complete: it covers purpose, node semantics, hierarchy models, special ICD-10-PCS constraints, and pagination. The output schema exists, so return-value details are not required. The only substantive gap is the lack of any mention of what `system=RXNORM` returns, even though RXNORM is a valid enum value.

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?

The schema already documents all 4 parameters, so the baseline is 3. The description adds meaningful context for `node` (top-level vs immediate children), `cursor` (round-trip pagination), and system-specific top-level behaviors. However, the schema allows `RXNORM`, but the description's examples only cover ICD-10-CM, HCPCS, and ICD-10-PCS, leaving RXNORM behavior undocumented.

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 uses a specific verb ('Walk') and a specific resource ('a US medical code system's hierarchy'), and it clearly distinguishes itself from search tools by emphasizing 'without a search term.' It also explains the top-level forms for ICD-10-CM, HCPCS, and ICD-10-PCS, so an agent can immediately tell what this tool is for.

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?

It gives explicit invocation variants: with no `node` returns top-level entries, with a `node` returns immediate children System-specific usage is explained, including the ICD-10-PCS axis limitation. It does not explicitly name a sibling alternative like medcode_search_codes for term-based lookup, but the 'without a search term' phrase strongly implies the boundary.

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

All medical-codes-mcp-server toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources