Skip to main content
Glama

medical-codes-mcp-server

by io.github.cyanheads

medical-codes-mcp-server

medcode_search_codes
Read-onlyIdempotent

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.

Input Schema

TableJSON 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

TableJSON Schema
NameRequiredDescriptionDefault
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.

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