Skip to main content
Glama

medical-codes-mcp-server

by io.github.cyanheads

medical-codes-mcp-server

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.

TDQS

A4.4/5.0
Behavior4/5

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

Annotations already declare readOnlyHint=true and idempotentHint=true, covering safety. The description adds substantial behavioral context: how the hierarchy works per system, the PCS limitation, and pagination with nextCursor/cursor. This goes beyond the annotations and helps the agent anticipate behavior, though the output schema covers return format.

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

Conciseness4/5

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

Though somewhat long, every sentence carries essential information for a multi-system, paginated tool. The structure is logical: purpose first, then behavior, then system nuances, then pagination. It's detailed but not padded; the length is justified by the tool's complexity.

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

Completeness5/5

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

Given the complexity (4 parameters, 4 enum systems, pagination, output schema), the description covers everything an agent needs to call it correctly: how to initiate (top-level), how to drill down, system-specific rules, pagination mechanics, and a usage scenario. The output schema exists, so return values are documented elsewhere. Nothing essential is missing.

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?

Schema coverage is 100%, so the baseline is 3. The description enhances parameter meaning: it clarifies that `node` works only for ICD-10-CM/HCPCS as a code to expand, and for ICD-10-PCS only top-level browsing is allowed. It also explains the `cursor` parameter's role in pagination, adding value beyond the schema.

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 clearly states the verb 'Walk' and the resource 'a US medical code system's hierarchy'. It explicitly contrasts with search ('without a search term') and differentiates itself from siblings like medcode_search_codes. The purpose is unambiguous and immediately distinguishes this browsing tool from searching.

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 explains when to use the tool ('to orient in an unfamiliar system or enumerate a category's specific codes') and provides clear system-specific guidance (prefix vs axis-based, PCS limitations). The phrase 'without a search term' implies the alternative is the search tool. It doesn't explicitly name a sibling, but the context is strong enough.

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
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

A4.7/5.0
Disambiguation5/5

Each tool serves a unique, non-overlapping function: browsing hierarchy, validating codes, decoding descriptions, listing systems, mapping between codes, and searching by clinical description. There is no ambiguity in selecting the right tool for a task.

Naming Consistency5/5

All tool names follow the 'medcode_' prefix with a clear verb_noun pattern: browse_hierarchy, check_code, get_code, list_systems, map_codes, search_codes. This is a perfectly consistent naming convention.

Tool Count5/5

With six tools, the server is well-scoped for its purpose of decoding, validating, searching, and crosswalking medical codes. Each tool covers a distinct essential capability, and the count feels appropriate for a focused domain.

Completeness5/5

The tool set covers the full read-only lifecycle: discovering codes (browse), searching (search), decoding (get), validating (check), crosswalking (map), and identifying release versions (list_systems). There are no obvious dead ends or missing operations for this domain.

Resources