Skip to main content
Glama

medical-codes-mcp-server

by io.github.cyanheads

Server Details

Offline US medical code lookup and crosswalk — ICD-10-CM/PCS, HCPCS Level II, RxNorm. Keyless.

If you are the author of this connector, you can claim ownership with GitHub, an HTTP challenge, or a DNS record. Claimed connector authors can inspect health checks, view analytics, and manage their listing.
Status
Healthy
Last Tested
Transport
Streamable HTTP
URL
Repository
cyanheads/medical-codes-mcp-server
GitHub Stars
2
Server Listing
medical-codes-mcp-server

Available Tools

6 tools
medcode_browse_hierarchymedical-codes-mcp-serverA
Read-onlyIdempotent
Inspect

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.

ParametersJSON 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

ParametersJSON Schema
NameRequiredDescription
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.

medcode_check_codemedical-codes-mcp-serverA
Read-onlyIdempotent
Inspect

Validate whether a US medical code exists, is current, and is billable in the active bundled release. Returns a discriminated status — valid_billable, valid_not_billable, valid_header, or terminated — with a whyNot explaining non-billable and terminated cases (e.g. "valid ICD-10-CM category but not billable — submit a more specific child code"). This is the detail a coder needs before submitting a claim. Auto-detects the system from the code's shape; pass an explicit system to disambiguate. A non-billable or terminated code is a successful result with a whyNot, not an error — only a code that exists in no bundled system raises unknown_code. A code string that also exists in another bundled system carries alsoInSystems naming it, since the verdict applies only to the system that answered.

ParametersJSON Schema
NameRequiredDescriptionDefault
codeYesThe code to validate, with or without dots. Must not be blank or whitespace-only.
systemNoForce the lookup into this system. Omit to auto-detect from the code's shape.

Output Schema

ParametersJSON Schema
NameRequiredDescription
codeNoThe code in display form (ICD-10-CM carries the dot).
errorNoPresent when the call failed. Absent on success.
statusNoValidity status. valid_billable = submit as-is; valid_header/valid_not_billable = needs a more specific code; terminated = retired.
systemNoThe system the code was resolved in, echoed for chaining.
whyNotNoExplanation for non-billable/terminated statuses, or null when valid_billable.
billableNoTrue only when status is valid_billable.
alsoInSystemsNoOther bundled systems holding this same code string, present only when there is at least one. The verdict above is for the system this code resolved in; the code is a DIFFERENT code in each system listed here, with its own billability — "B00" is the ICD-10-CM category "Herpesviral [herpes simplex] infections" and also the ICD-10-PCS table row "Imaging, Central Nervous System, Plain Radiography". Re-call with `system` set to one of these values to validate it there.

TDQS

A4.7/5.0
Behavior5/5

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

With readOnlyHint and idempotentHint already present, the description still adds crucial behavioral detail: non-billable/terminated codes are successful results carrying a whyNot, only codes absent from all bundled systems raise unknown_code, and alsoInSystems clarifies multi-system matches. This goes well beyond the annotations and fully discloses the tool's result semantics.

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 lengthy but every sentence carries unique, non-redundant information. It is front-loaded with the core contract and proceeds to edge cases in a logical order. No sentence is wasted, and 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 presence of an output schema and the complexity of the tool's discriminated statuses, the description covers all essential facets: existence, currency, billability, whyNot explanations, multi-system aliases, and error semantics. An agent has everything needed to invoke it correctly and interpret the result.

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 adds meaningful context beyond the schema: it clarifies that 'code' can include or exclude dots, explains that 'system' is optional and used to disambiguate auto-detection, and notes the system enum values. This enriches parameter understanding without redundancy.

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 opens with a precise verb+resource contract: 'Validate whether a US medical code exists, is current, and is billable in the active bundled release.' It further distinguishes itself via the discriminated statuses (valid_billable, valid_not_billable, etc.) and explicitly frames it as 'the detail a coder needs before submitting a claim.' This makes the tool's role clear against siblings like search, browse, or map.

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?

The description gives strong context for when to use it ('before submitting a claim') and explains the auto-detection vs. forcing a system ('pass an explicit system to disambiguate'). However, it does not explicitly state when *not* to use it or name alternative tools. The distinction from siblings is implied but not spelled out, so it falls short of a 5.

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

medcode_get_codemedical-codes-mcp-serverA
Read-onlyIdempotent
Inspect

Decode one or more US medical codes to their official descriptions across ICD-10-CM (diagnoses), ICD-10-PCS (inpatient procedures), HCPCS Level II (supplies/drugs/services), and RxNorm (drugs, by RXCUI). Also decodes a National Drug Code (NDC) directly to its RxNorm product offline, tagged source: "NDC" — hyphenated in an FDA segment configuration (4-4-2, 5-3-2, 5-4-1, or the 11-digit 5-4-2) or as bare 10/11 digits; any other segment widths are malformed and stay unresolved. Auto-detects the system from each code's shape; pass an explicit system only when a value is genuinely ambiguous. Accepts 1–50 codes and returns partial success: resolved codes in found, unresolved in notFound with a per-code reason, so one bad code never fails the batch. Set includeHierarchy to attach each code's parent and immediate children (with a childrenTruncated flag when a code has more children than the cap returns — walk the full set via medcode_browse_hierarchy or medcode_map_codes). The resolved system is echoed on every result for chaining into medcode_map_codes or a billability check; a code string that also exists in another bundled system carries alsoInSystems naming it, so a single answer to a colliding code is never mistaken for the only one.

ParametersJSON Schema
NameRequiredDescriptionDefault
codesYesCodes to decode (1–50). Mixed systems are fine — each is detected independently. An NDC decodes to its RxNorm product: hyphenated as 4-4-2, 5-3-2, 5-4-1, or 5-4-2, or as bare 10/11 digits.
systemNoForce every code to be looked up in this system. Omit to auto-detect per code.
includeHierarchyNoWhen true, attach each found code's parent and immediate children.

Output Schema

ParametersJSON Schema
NameRequiredDescription
errorNoPresent when the call failed. Absent on success.
foundNoSuccessfully decoded codes, in request order.
notFoundNoCodes that did not resolve, with per-code reasons.

TDQS

A5/5.0
Behavior5/5

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

Beyond the annotations (readOnlyHint=true, idempotentHint=true, openWorldHint=false), the description discloses critical runtime behavior: partial success with `found` and `notFound` fields and per-code reasons, malformed NDC handling, auto-detection, the `childrenTruncated` flag, and the `alsoInSystems` collision signal. It also explains the impact of `includeHierarchy` and how to walk the full set. This goes well beyond the annotations, giving an agent a precise mental model of the tool's behavior.

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 long but every sentence earns its place, covering the core action, NDC specifics, batch semantics, hierarchy option, collision handling, and chaining. It is front-loaded with the primary purpose, then branches into details. No redundant or filler language—each clause contributes to actionable understanding.

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 tool's complexity (multiple coding systems, NDC decoding, partial success, hierarchy, collisions) and the presence of an output schema, the description covers all necessary aspects: input constraints, optional parameters, edge cases, and secondary behavior. It even mentions the `alsoInSystems` field and the `childrenTruncated` flag, which are likely part of the output schema but are reinforced here. An agent can fully anticipate how to call the tool and interpret results without further inspection.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Even though the schema has 100% coverage with descriptions for each parameter, the description adds meaningful detail: it specifies exact NDC segment formats (4-4-2, 5-3-2, 5-4-1, 5-4-2, and bare 10/11 digits), clarifies that the `codes` array accepts mixed systems, and explains that `system` is only for forced lookups. This adds semantic value beyond the schema, particularly around edge cases and expected input formats.

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 opens with a specific verb and resource: 'Decode one or more US medical codes to their official descriptions' across multiple named systems (ICD-10-CM, ICD-10-PCS, HCPCS, RxNorm). It distinguishes itself from siblings by covering decoding specifically, and further differentiates NDC decoding as a unique behavior. The description is clearly about a batch decoding tool, not a search, map, browse, or check tool.

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?

The description explicitly states when to pass the `system` parameter ('only when a value is genuinely ambiguous'), and directs users to alternatives for fuller hierarchy traversal ('walk the full set via medcode_browse_hierarchy or medcode_map_codes'). It also mentions chaining into medcode_map_codes or a billability check, providing actionable routing. This is clear, specific guidance that selects this tool over siblings.

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

medcode_list_systemsmedical-codes-mcp-serverA
Read-onlyIdempotent
Inspect

List the bundled US medical code systems with their release identifiers, effective dates, and code counts. Confirms which ICD-10-CM fiscal year, ICD-10-PCS fiscal year, HCPCS Level II release, and RxNorm normalized set are active before acting on any decode, search, or crosswalk result. The corpus is offline and built at package-build time — this call reports exactly which release is baked into the running server. ICD-10-CM/PCS are the US clinical modifications, not the ICD-10/ICD-11 base.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
errorNoPresent when the call failed. Absent on success.
systemsNoOne entry per bundled code system, in canonical order.

TDQS

A4.3/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, so the safety profile is covered structurally. The description adds genuinely useful behavioral context beyond those annotations: the corpus is offline and baked at package-build time, so the call reports exactly what release is in the running server — a key caveat for an agent relying on currency. The ICD-10-CM/PCS vs. base ICD disambiguation also prevents a conceptual misapplication. No contradiction with annotations.

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?

The description is efficient at roughly 65 words and front-loads the primary function in the first sentence. The middle sentence's enumeration of each code system and release type adds specificity but is slightly verbose relative to the first sentence's summary. The closing ICD disambiguation earns its place. Every sentence contributes, though the second sentence could be tightened.

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?

For a zero-parameter, read-only inventory tool with an output schema present, the description is complete: it tells the agent what will be returned (release identifiers, effective dates, code counts), why it matters operationally (validate releases before acting on results), and the key build-time constraint. Since the output schema already documents the return shape, the description does not need to restate it. Nothing an agent needs to call this correctly 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?

This tool has zero parameters (schema shows an empty object with additionalProperties=false), so there is no parameter ambiguity to resolve. Per the rubric's baseline for zero-parameter tools, a 4 is appropriate — the description correctly handles the parameter-free case and needs no compensating detail.

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 states a specific verb ('List') and a well-defined resource ('bundled US medical code systems') with explicit content detail (release identifiers, effective dates, code counts). It clearly distinguishes itself from its siblings (browse/check/get/map/search) by identifying its job as cataloging the available systems rather than operating on codes. The clarification that ICD-10-CM/PCS are US clinical modifications rather than the ICD-10/11 base adds important disambiguation.

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?

The description gives explicit when-to-use guidance: 'Confirms which ICD-10-CM fiscal year, ICD-10-PCS fiscal year, HCPCS Level II release, and RxNorm normalized set are active before acting on any decode, search, or crosswalk result.' This clearly tells an agent to call this before trusting results from sibling operations. It does not explicitly name alternatives or state when not to use it, but for a zero-parameter inventory tool the usage context is clear enough.

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

medcode_map_codesmedical-codes-mcp-serverA
Read-onlyIdempotent
Inspect

Crosswalk a US medical code or drug across systems and within a hierarchy. Hierarchy directions: parents and children walk a code's prefix hierarchy one level per call — immediate parent/children only (depth-1); call iteratively for the full ancestor or descendant path (ICD-10-CM/HCPCS; ICD-10-PCS codes have no prefix parent). A resolvable source with no edge in the requested direction is a successful empty result with a notice, not an error. A source code string that also exists in another bundled system carries alsoInSystems naming it, since only the resolved system's hierarchy was walked. Drug directions (RxNorm): name_to_rxcui (drug name → RXCUI), ndc_to_rxcui and rxcui_to_ndc (NDC ↔ RXCUI; NDCs accepted hyphenated in an FDA segment configuration — 4-4-2, 5-3-2, 5-4-1, or the 11-digit 5-4-2 — or as bare 10/11 digits; ndc_to_rxcui names the product it decoded to), rxcui_to_ingredients and rxcui_to_brands (RXCUI → ingredient/brand RXCUIs, each with the target's RxNorm name and its conceptType — read that before counting a combination product's ingredients). Every result carries source provenance (which system or edge answered) so a chained call (e.g. into openfda with a resolved NDC) uses the right identifier. The children, name_to_rxcui, and rxcui_to_ndc directions can return large sets and paginate: a nextCursor in the response is passed back as cursor (with an optional limit page size) to walk the full set; the point directions ignore both.

ParametersJSON Schema
NameRequiredDescriptionDefault
fromYesThe source value: a code (for parents/children), a drug name, an NDC, or an RXCUI. Must not be blank or whitespace-only.
limitNoMax results per page for the paginated directions (children, name_to_rxcui, rxcui_to_ndc). Defaults to MEDCODE_MAX_RESULTS (50), ceiling 200. Ignored by the point directions.
cursorNoOpaque continuation token from a previous response's `nextCursor`, for the paginated directions (children, name_to_rxcui, rxcui_to_ndc). Omit for the first page.
systemNoFor parents/children, force the source code into this system. Omit to auto-detect.
directionYesWhat to map to. parents/children return the immediate parent or children only (depth-1) — call iteratively to walk a full path; the rxcui/ndc/name directions are RxNorm drug crosswalks.

Output Schema

ParametersJSON Schema
NameRequiredDescription
capNoPaginated directions only: the page size that was applied.
fromNoThe source value, echoed back.
hitsNoCrosswalk results, each tagged with the edge that produced it.
errorNoPresent when the call failed. Absent on success.
shownNoPaginated directions only: number of hits returned on this page.
noticeNoGuidance whenever a resolvable source returns no hits, naming which of the two causes applies: it has no edge in the requested direction (a top-level code has no parent; a leaf has no children; ICD-10-PCS codes have no prefix parent), or the `cursor` starts past the last page of a direction that does have results.
directionNoThe mapping direction that was applied.
truncatedNoPaginated directions (children, name_to_rxcui, rxcui_to_ndc) only: true when more results exist beyond this page.
nextCursorNoPaginated directions only: opaque token to pass back as `cursor` for the next page. Present only when more results exist beyond this page.
alsoInSystemsNoOther bundled systems holding the same `from` code string, present only when there is at least one (hierarchy directions only — a drug name, NDC, or RXCUI is not system-scoped). The hits above were walked in `resolvedSystem` alone; the code is a DIFFERENT code with a different hierarchy in each system listed here — "B00" is the ICD-10-CM category "Herpesviral [herpes simplex] infections" and also the ICD-10-PCS table row "Imaging, Central Nervous System, Plain Radiography". Re-call with `system` set to one of these values to walk it there.
resolvedSystemNoThe system the source resolved in, or null when not system-scoped.

TDQS

A4.6/5.0
Behavior5/5

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

Annotations already declare readOnlyHint=true and idempotentHint=true, and the description is consistent with them (a crosswalk is read-only and idempotent). Beyond annotations, the description discloses substantial behavior: a resolvable source with no edge is a successful empty result with a notice (not an error), alsoInSystems for codes existing in multiple systems, source provenance on every result, the depth-1 hierarchy semantics, and the caveat to read conceptType before counting a combination product's ingredients. These add real value the annotations could not convey.

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

Conciseness3/5

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

The purpose is front-loaded and nearly every sentence carries necessary behavioral content for a tool of this complexity (7 directions, pagination, multiple systems). However, it is delivered as one dense ~300-word paragraph with no structural breaks — no bullets, no per-direction sections — which makes it hard for an agent to scan. The information density justifies the length, but the wall-of-text format is a readability weakness.

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?

For a 5-parameter tool with 7 direction enums, pagination, and an output schema, the description is exceptionally complete: it covers direction semantics, error behavior, pagination mechanics, provenance, the combination-product caveat, and system override. Since an output schema exists, return-value explanation is unnecessary. There is no meaningful operational detail an agent would need that is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/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, but the description adds considerable meaning beyond the schema: it elaborates each direction's semantics (depth-1 vs iterative, the RxNorm crosswalk behaviors, ndc_to_rxcui naming the decoded product), explains the cursor/nextCursor mechanism and which directions paginate, clarifies that point directions ignore limit/cursor, and explains system auto-detection vs forced resolution. This is far more than the schema strings alone provide.

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: 'Crosswalk a US medical code or drug across systems and within a hierarchy.' It names the exact operation (mapping between coding systems and hierarchy directions) and the resource scope, and the direction enums make the behavior concrete. It is clearly distinct from siblings like medcode_browse_hierarchy (browse), medcode_check_code (check), and medcode_search_codes (search) — this is the crosswalk tool, not a lookup, check, or search tool.

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?

Provides rich context on how to use each direction: iterative calls for full ancestor/descendant paths, empty-result semantics, pagination via nextCursor/cursor, and system override. It explains usage well, but it never names sibling tools or gives explicit exclusions ('use X instead when...'), so the when-not-to-use guidance is absent even though the how-to-use guidance is thorough.

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

medcode_search_codesmedical-codes-mcp-serverA
Read-onlyIdempotent
Inspect

Find US medical codes whose official descriptions match a described concept, via full-text search over the bundled index. Every search term must appear — matched first as a token prefix, then as a substring so inflected and compound forms are also found (a "neuropathy" search surfaces "mononeuropathy"/"polyneuropathy" siblings too, not only a standalone "neuropathy" token). Filter by system (ICD10CM/ICD10PCS/HCPCS/RXNORM), billableOnly to exclude headers/categories, and chapter. Use when you have a clinical description and need the code — the reverse of medcode_get_code. Results echo the resolved system per row for chaining, rank exact prefix matches ahead of substring-only matches with a deterministic tie-break, and disclose truncation with a nextCursor: pass it back as cursor to page through the full ranked set.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoMax codes per page. Defaults to the server's MEDCODE_MAX_RESULTS (50), ceiling 200.
queryYesClinical description to match, e.g. "type 2 diabetes with neuropathy". Must not be blank or whitespace-only.
cursorNoOpaque continuation token from a previous response's `nextCursor`, to fetch the next page of the same ranked result set. Omit for the first page.
systemNoRestrict results to one system. Omit to search all bundled systems.
chapterNoRestrict to a chapter/range bucket (the value from a code's `chapter` field). Case-insensitive: surrounding whitespace is trimmed and the value is upper-cased to match how chapters are stored, and `appliedFilters.chapter` echoes the upper-cased value that actually ran. A blank or whitespace-only value carries no filtering intent and is treated as omitted, which the response discloses as `appliedFilters.chapter: null`.
billableOnlyNoWhen true, return only billable leaf codes (exclude headers/categories).

Output Schema

ParametersJSON Schema
NameRequiredDescription
capNoThe page size that was applied.
codesNoMatching codes, ranked by full-text relevance.
errorNoPresent when the call failed. Absent on success.
shownNoNumber of codes returned on this page.
noticeNoGuidance when nothing matched — echoes the query and suggests how to broaden.
truncatedNoTrue when more matches exist beyond this page.
nextCursorNoOpaque token to pass back as `cursor` for the next page. Present only when more matches exist beyond this page.
appliedFiltersNoFilters the server applied to the search.
effectiveQueryNoThe query as the server parsed it for matching.

TDQS

A5/5.0
Behavior5/5

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

The description discloses the full behavioral profile: token-prefix then substring matching, ranking with deterministic tie-break, pagination via nextCursor, and the echo of the resolved system per row. This goes well beyond the readOnly/idempotent annotations, adding genuinely useful context.

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 long but packed with information, with each sentence earning its place. It front-loads the core purpose and then systematically explains behavior, filtering, and pagination without any filler.

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?

Because an output schema exists, return values don't need explanation. The description covers the full invocation context: when to use, how to filter, how ranking works, and how to page through all results. Nothing an agent needs is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Despite the schema covering 100% of parameter descriptions, the description adds crucial semantic nuance: how the matching algorithm behaves, how `cursor` chains pages, how `chapter` is normalized and echoed, and how `billableOnly` filters. This exceeds what the schema alone conveys.

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 states a specific verb and resource: 'Find US medical codes' via 'full-text search over the bundled index.' It also explicitly contrasts with a sibling tool, medcode_get_code, making its distinct purpose unmistakable.

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?

It gives an explicit usage condition: 'Use when you have a clinical description and need the code — the reverse of medcode_get_code.' It also lists filtering options, leaving no ambiguity about when to select this tool over alternatives.

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 6 tool updates
    • Changedmedcode_browse_hierarchy6 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"
-]
    • Changedmedcode_check_code6 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": [
+      "system",
+      "code",
+      "status",
+      "billable",
+      "whyNot"
+    ]
+  },
+  {
+    "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_code`: The code does not exist in the named or detected system. `ambiguous_system`: The code is present in more than one bundled system and no `system` was given. Other values are possible when a failure originates below the handler.",
+          "examples": [
+            "unknown_code",
+            "ambiguous_system"
+          ],
+          "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: -[
-  "system",
-  "code",
-  "status",
-  "billable",
-  "whyNot"
-]
    • Changedmedcode_get_code6 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": [
+      "found",
+      "notFound"
+    ]
+  },
+  {
+    "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: `no_codes_found`: None of the requested codes exist in any bundled system. Other values are possible when a failure originates below the handler.",
+          "examples": [
+            "no_codes_found"
+          ],
+          "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: -[
-  "found",
-  "notFound"
-]
    • Changedmedcode_list_systems6 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": [
+      "systems"
+    ]
+  },
+  {
+    "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.",
+          "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: -[
-  "systems"
-]
    • Changedmedcode_map_codes6 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": [
+      "from",
+      "direction",
+      "resolvedSystem",
+      "hits"
+    ]
+  },
+  {
+    "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: `no_mapping`: The source value did not resolve to any bundled code. `direction_unavailable`: A drug-crosswalk direction was requested but this build carries no RxNorm tables. `ambiguous_system`: The source code is present in more than one system and no `system` was given. Other values are possible when a failure originates below the handler.",
+          "examples": [
+            "no_mapping",
+            "direction_unavailable",
+            "ambiguous_system"
+          ],
+          "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: -[
-  "from",
-  "direction",
-  "resolvedSystem",
-  "hits"
-]
    • Changedmedcode_search_codes6 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": [
+      "codes",
+      "effectiveQuery",
+      "appliedFilters",
+      "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.",
+          "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: -[
-  "codes",
-  "effectiveQuery",
-  "appliedFilters",
-  "truncated",
-  "shown",
-  "cap"
-]
  2. 4 tool updates
    • Changedmedcode_check_code1 field changed
      • addedOutput schema / properties / alsoInSystems
        Added value: +{
+  "description": "Other bundled systems holding this same code string, present only when there is at least one. The verdict above is for the system this code resolved in; the code is a DIFFERENT code in each system listed here, with its own billability — \"B00\" is the ICD-10-CM category \"Herpesviral [herpes simplex] infections\" and also the ICD-10-PCS table row \"Imaging, Central Nervous System, Plain Radiography\". Re-call with `system` set to one of these values to validate it there.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}
    • Changedmedcode_get_code3 fields changed
      • changedInput schema / properties / codes / description
        Previous value: -"Codes to decode (1–50). Mixed systems are fine — each is detected independently. An NDC (hyphenated or 10/11-digit) decodes to its RxNorm product."New value: +"Codes to decode (1–50). Mixed systems are fine — each is detected independently. An NDC decodes to its RxNorm product: hyphenated as 4-4-2, 5-3-2, 5-4-1, or 5-4-2, or as bare 10/11 digits."
      • addedOutput schema / properties / found / items / properties / alsoInSystems
        Added value: +{
+  "description": "Other bundled systems holding this same code string, present only when there is at least one. The result above is the system this code resolved in; the code is a DIFFERENT code in each system listed here — \"B00\" is the ICD-10-CM category \"Herpesviral [herpes simplex] infections\" and also the ICD-10-PCS table row \"Imaging, Central Nervous System, Plain Radiography\". Re-call with `system` set to one of these values to decode it there.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}
      • changedOutput schema / properties / notFound / items / properties / reason / description
        Previous value: -"Why it could not be resolved (unknown shape, not in the bundled release, or ambiguous)."New value: +"Why it could not be resolved (absent from every bundled system, a well-formed NDC nothing maps to, or ambiguous across systems)."
    • Changedmedcode_map_codes7 fields changed
      • changedInput schema / properties / cursor / description
        Previous value: -"Opaque continuation token from a previous response's `nextCursor`, for the paginated directions (children, name_to_rxcui). Omit for the first page."New value: +"Opaque continuation token from a previous response's `nextCursor`, for the paginated directions (children, name_to_rxcui, rxcui_to_ndc). Omit for the first page."
      • changedInput schema / properties / limit / description
        Previous value: -"Max results per page for the paginated directions (children, name_to_rxcui). Defaults to MEDCODE_MAX_RESULTS (50), ceiling 200. Ignored by the point directions."New value: +"Max results per page for the paginated directions (children, name_to_rxcui, rxcui_to_ndc). Defaults to MEDCODE_MAX_RESULTS (50), ceiling 200. Ignored by the point directions."
      • addedOutput schema / properties / alsoInSystems
        Added value: +{
+  "description": "Other bundled systems holding the same `from` code string, present only when there is at least one (hierarchy directions only — a drug name, NDC, or RXCUI is not system-scoped). The hits above were walked in `resolvedSystem` alone; the code is a DIFFERENT code with a different hierarchy in each system listed here — \"B00\" is the ICD-10-CM category \"Herpesviral [herpes simplex] infections\" and also the ICD-10-PCS table row \"Imaging, Central Nervous System, Plain Radiography\". Re-call with `system` set to one of these values to walk it there.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}
      • addedOutput schema / properties / hits / items / properties / conceptType
        Added value: +{
+  "description": "The target concept's RxNorm type, present on `rxcui_to_ingredients` and `rxcui_to_brands` hits only: \"IN\" (ingredient), \"PIN\" (precise ingredient — a specific salt, ester, or isomer of an ingredient), \"MIN\" (multiple ingredients — a concept naming a combination, never a substance within it), or \"BN\" (brand name). Ingredient hits mix the first three, so the hit count is not the substance count: a \"MIN\" hit is the grouping concept and never counts, and a \"PIN\" names a form of a substance rather than an extra one — usually alongside the \"IN\" it refines, though two \"PIN\" esters can share a single \"IN\". Counting the \"IN\" hits is the closest reading, and under-counts those shared cases.",
+  "type": "string"
+}
      • changedOutput schema / properties / hits / items / properties / description / description
        Previous value: -"Description of the target when available."New value: +"Description of the target when available: the code description for hierarchy hits, the official RxNorm name for the `name_to_rxcui`, `ndc_to_rxcui`, `rxcui_to_ingredients`, and `rxcui_to_brands` drug concepts. Absent for `rxcui_to_ndc`, whose targets are package identifiers with no description of their own."
      • changedOutput schema / properties / notice / description
        Previous value: -"Guidance when a resolvable code has no edge in the requested direction (e.g. a top-level code has no parent; a leaf has no children; ICD-10-PCS codes have no prefix parent)."New value: +"Guidance whenever a resolvable source returns no hits, naming which of the two causes applies: it has no edge in the requested direction (a top-level code has no parent; a leaf has no children; ICD-10-PCS codes have no prefix parent), or the `cursor` starts past the last page of a direction that does have results."
      • changedOutput schema / properties / truncated / description
        Previous value: -"Paginated directions (children, name_to_rxcui) only: true when more results exist beyond this page."New value: +"Paginated directions (children, name_to_rxcui, rxcui_to_ndc) only: true when more results exist beyond this page."
    • Changedmedcode_search_codes1 field changed
      • changedInput schema / properties / chapter / description
        Previous value: -"Restrict to a chapter/range bucket (the value from a code's `chapter` field)."New value: +"Restrict to a chapter/range bucket (the value from a code's `chapter` field). Case-insensitive: surrounding whitespace is trimmed and the value is upper-cased to match how chapters are stored, and `appliedFilters.chapter` echoes the upper-cased value that actually ran. A blank or whitespace-only value carries no filtering intent and is treated as omitted, which the response discloses as `appliedFilters.chapter: null`."
  3. 5 tool updates
    • Changedmedcode_browse_hierarchy3 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"
    • Changedmedcode_check_code1 field changed
      • changedInput schema / properties / code / description
        Previous value: -"The code to validate, with or without dots."New value: +"The code to validate, with or without dots. Must not be blank or whitespace-only."
    • Changedmedcode_get_code1 field changed
      • changedInput schema / properties / codes / items / description
        Previous value: -"A single code to decode (with or without dots), an RXCUI, or an NDC."New value: +"A single code to decode (with or without dots), an RXCUI, or an NDC. Must not be blank or whitespace-only."
    • Changedmedcode_map_codes1 field changed
      • changedInput schema / properties / from / description
        Previous value: -"The source value: a code (for parents/children), a drug name, an NDC, or an RXCUI."New value: +"The source value: a code (for parents/children), a drug name, an NDC, or an RXCUI. Must not be blank or whitespace-only."
    • Changedmedcode_search_codes1 field changed
      • changedInput schema / properties / query / description
        Previous value: -"Clinical description to match, e.g. \"type 2 diabetes with neuropathy\"."New value: +"Clinical description to match, e.g. \"type 2 diabetes with neuropathy\". Must not be blank or whitespace-only."
  4. 4 tool updates
    • Changedmedcode_browse_hierarchy6 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."
    • Changedmedcode_get_code1 field changed
      • addedOutput schema / properties / found / items / properties / childrenTruncated
        Added value: +{
+  "description": "True when the code has more immediate children than `children` carries — the list was capped at the server cap (present only when includeHierarchy is true). Retrieve the full child list with medcode_browse_hierarchy or medcode_map_codes (children) for this code.",
+  "type": "boolean"
+}
    • Changedmedcode_map_codes6 fields changed
      • addedInput schema / properties / cursor
        Added value: +{
+  "description": "Opaque continuation token from a previous response's `nextCursor`, for the paginated directions (children, name_to_rxcui). Omit for the first page.",
+  "type": "string"
+}
      • addedInput schema / properties / limit
        Added value: +{
+  "description": "Max results per page for the paginated directions (children, name_to_rxcui). Defaults to MEDCODE_MAX_RESULTS (50), ceiling 200. Ignored by the point directions.",
+  "maximum": 200,
+  "minimum": 1,
+  "type": "integer"
+}
      • addedOutput schema / properties / cap
        Added value: +{
+  "description": "Paginated directions only: the page size that was applied.",
+  "type": "number"
+}
      • addedOutput schema / properties / nextCursor
        Added value: +{
+  "description": "Paginated directions only: opaque token to pass back as `cursor` for the next page. Present only when more results exist beyond this page.",
+  "type": "string"
+}
      • addedOutput schema / properties / shown
        Added value: +{
+  "description": "Paginated directions only: number of hits returned on this page.",
+  "type": "number"
+}
      • addedOutput schema / properties / truncated
        Added value: +{
+  "description": "Paginated directions (children, name_to_rxcui) only: true when more results exist beyond this page.",
+  "type": "boolean"
+}
    • Changedmedcode_search_codes6 fields changed
      • addedInput schema / properties / cursor
        Added value: +{
+  "description": "Opaque continuation token from a previous response's `nextCursor`, to fetch the next page of the same ranked result set. Omit for the first page.",
+  "type": "string"
+}
      • changedInput schema / properties / limit / description
        Previous value: -"Max codes to return. Defaults to the server's MEDCODE_MAX_RESULTS (50), ceiling 200."New value: +"Max codes per page. Defaults to the server's 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 matches exist beyond this page.",
+  "type": "string"
+}
      • changedOutput schema / properties / shown / description
        Previous value: -"Number of codes returned."New value: +"Number of codes returned on this page."
      • changedOutput schema / properties / truncated / description
        Previous value: -"True when results were capped at the limit."New value: +"True when more matches exist beyond this page."
  5. 2 tool updates
    • Changedmedcode_get_code4 fields changed
      • changedInput schema / properties / codes / description
        Previous value: -"Codes to decode (1–50). Mixed systems are fine — each is detected independently."New value: +"Codes to decode (1–50). Mixed systems are fine — each is detected independently. An NDC (hyphenated or 10/11-digit) decodes to its RxNorm product."
      • changedInput schema / properties / codes / items / description
        Previous value: -"A single code to decode, with or without dots."New value: +"A single code to decode (with or without dots), an RXCUI, or an NDC."
      • changedOutput schema / properties / found / items / description
        Previous value: -"A decoded code, optionally with its parent and immediate children."New value: +"A decoded code, optionally with its parent/children and resolution source."
      • addedOutput schema / properties / found / items / properties / source
        Added value: +{
+  "description": "Resolution provenance when the input was not a direct code: \"NDC\" when an NDC was decoded to its RxNorm product via the NDC↔RxNorm map. Omitted for direct code lookups.",
+  "type": "string"
+}
    • Changedmedcode_map_codes1 field changed
      • changedInput schema / properties / direction / description
        Previous value: -"What to map to. parents/children return the immediate parent or children only (depth-1) — call iteratively to walk a full path; the rxcui/ndc/name directions are RxNorm drug crosswalks (phase 2)."New value: +"What to map to. parents/children return the immediate parent or children only (depth-1) — call iteratively to walk a full path; the rxcui/ndc/name directions are RxNorm drug crosswalks."
  6. 2 tool updates
    • Changedmedcode_browse_hierarchy2 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\"."
    • Changedmedcode_map_codes2 fields changed
      • changedInput schema / properties / direction / description
        Previous value: -"What to map to. parents/children walk the code hierarchy; the rxcui/ndc/name directions are RxNorm drug crosswalks (phase 2)."New value: +"What to map to. parents/children return the immediate parent or children only (depth-1) — call iteratively to walk a full path; the rxcui/ndc/name directions are RxNorm drug crosswalks (phase 2)."
      • addedOutput schema / properties / notice
        Added value: +{
+  "description": "Guidance when a resolvable code has no edge in the requested direction (e.g. a top-level code has no parent; a leaf has no children; ICD-10-PCS codes have no prefix parent).",
+  "type": "string"
+}
  7. 6 tool updates
    • First observedmedcode_browse_hierarchy
    • First observedmedcode_check_code
    • First observedmedcode_get_code
    • First observedmedcode_list_systems
    • First observedmedcode_map_codes
    • First observedmedcode_search_codes

Frequently Asked Questions

Discussions

No comments yet. Be the first to start the discussion!

Login with GitHub to comment

Related MCP Connectors

Related MCP Servers

  • mcp-icd10

    stabgan
    A
    license
    A
    quality
    D
    maintenance
    Offline MCP server for ICD medical code lookup, search, and crosswalk translation with 124K codes and 102K mappings, all local with zero network calls.
    5
    3
    MIT

  • medical-codes

    pipeworx-io
    A
    license
    Not graded
    quality
    C
    maintenance
    Search medical codes including ICD-10, LOINC, and clinical terms for conditions, procedures, and drugs via natural language queries.
    5
    MIT
  • OMOPHub MCP Server by OMOPHub

    OMOPHub MCP Serverofficial

    OMOPHub
    A
    license
    A
    quality
    A
    maintenance
    Provides AI agents with instant access to 10M+ OMOP medical vocabulary concepts for searching, mapping, and navigating clinical codes across SNOMED, ICD-10, RxNorm, LOINC, and more.
    11
    116
    6
    MIT
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