medical-codes-mcp-server

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

Annotations already mark readOnlyHint and idempotentHint, but the description goes beyond by detailing system-specific behaviors: prefix hierarchy vs axis-based, the fact that only the top-level Section axis is browsable for ICD-10-PCS, and pagination via nextCursor/cursor. This discloses important non-obvious behavior that annotations don't cover.

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

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

The description is appropriately detailed for the tool's complexity, with the main purpose front-loaded in the first sentence. Each subsequent sentence addresses a necessary aspect (hierarchy types, system-specific constraints, pagination). No redundant or filler content.

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

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

Given the tool's complexity (4 parameters, multiple code systems, pagination, system-specific limitations) and the presence of an output schema (which makes explicit return-value documentation unnecessary), the description covers all necessary context: use cases, how to navigate the hierarchy, system variations, and pagination. It is complete for an agent to select and invoke correctly.

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

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

The input schema already provides 100% parameter coverage with descriptions, but the description adds relational meaning: how omitting `node` vs providing it changes behavior, how `node` interacts with the chosen `system` (ICD-10-PCS restriction), and how `cursor` relates to a previous response's `nextCursor`. This supplements the schema's per-parameter descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Walk a US medical code system's hierarchy for discovery without a search term.' It specifies the resource (hierarchy) and the verb (walk), and distinguishes itself from siblings like search tools by emphasizing 'without a search term.' It also explains the two operational modes (with/without node).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

Provides clear usage context: 'for discovery without a search term' and 'Lets an agent orient in an unfamiliar system or enumerate a category's specific codes.' It implies when to use this tool versus search-oriented siblings, though it doesn't explicitly name alternative tools or state exclusions. The detailed hierarchy differences between ICD-10-CM/HCPCS vs ICD-10-PCS also guide correct usage.

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

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

Even with readOnlyHint and idempotentHint annotations, the description adds substantial behavioral context: the discriminated statuses, whyNon-billable and terminated are successful results rather than errors, unknown_code raised only when no bundled system exists, and alsoInSystems semantics. This goes well beyond what annotations declare.

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

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

Four sentences, front-loaded with the core purpose, then statuses, then system handling, then error semantics. Every sentence provides distinct value; no filler or redundancy.

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

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

The description covers all essential aspects: purpose, statuses, whyNot reasoning, error behavior, system disambiguation, and multi-system membership. An output schema exists but the description still clarifies return field semantics, making the tool fully self-explanatory.

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

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

Schema coverage is 100% with descriptions for both parameters. The tool description enhances this by explaining why `system` matters (disambiguate ambiguous code shapes) and elaborates on the auto-detection behavior. This meaningful addition justifies moving above the baseline of 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

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: 'Validate whether a US medical code exists, is current, and is billable.' It clearly distinguishes this from sibling tools (browse, get, list, map, search) by focusing on validation with a discriminated status result.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

Provides a clear use case: 'This is the detail a coder needs before submitting a claim.' It also explains when to pass the explicit `system` parameter ('to disambiguate') vs auto-detection. It does not explicitly mention when not to use the tool or name alternatives, so a 4 rather than 5.

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

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

Beyond the readOnly/idempotent annotations, the description discloses many non-obvious behaviors: NDC format flexibility (4-4-2, 5-3-2, etc.), malformed NDC handling, partial success with per-code reasons, hierarchy truncation with 'childrenTruncated' flag, echoed system for chaining, and 'alsoInSystems' for collisions. No contradictions 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.

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

The description is dense and lengthy, but each sentence delivers information not found elsewhere: NDC edge cases, partial success, hierarchy truncation, and chaining. It is front-loaded with the main purpose and logically flows from core function to edge cases to integration. Slightly verbose but appropriately so given the tool's complexity.

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

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

The description covers the key operational facets: supported systems, NDC behavior, auto-detection, batch processing, error handling, hierarchy flag, and interoperability with sibling tools. The output schema exists and would carry return details, but the description already mentions the critical return fields (found, notFound, system, alsoInSystems, childrenTruncated). For a multi-system medical code tool, this is comprehensive.

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

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

Schema coverage is 100%, but the description adds substantial value: it clarifies when to omit vs. pass 'system', explains the special NDC format and how it decodes to RxNorm, and details the meaning of 'includeHierarchy' (parent/children with truncation behavior). This goes far beyond the basic schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a clear verb+resource: 'Decode one or more US medical codes to their official descriptions.' It enumerates the specific code systems (ICD-10-CM, ICD-10-PCS, HCPCS, RxNorm) and explicitly distinguishes from siblings by noting alternative tools for hierarchy browsing and code mapping, making the tool's scope unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

The description gives concrete usage context: auto-detection, when to pass an explicit 'system' (only if ambiguous), batch limits, and partial success. It names alternatives for walking full hierarchy ('medcode_browse_hierarchy or medcode_map_codes') and chaining ('medcode_map_codes or a billability check'), though it does not explicitly state when NOT to use this tool in favor of search_codes or check_code.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint. The description adds valuable behavioral context: 'The corpus is offline and built at package-build time — this call reports exactly which release is baked into the running server.' This tells the agent that results are static and reflect the bundled release, which is important for interpreting other tool results.

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

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

The description is three sentences, front-loaded with the core action and resource, then supplements with usage context and system-specific clarifications. Every sentence provides useful information with no redundancy or fluff.

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

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

Even with an output schema present, the description fully explains what the tool does, when to use it, and the static nature of the data. It adequately covers the tool's role among siblings and leaves no critical gaps for a parameterless metadata listing tool.

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

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

The tool has zero parameters, so schema coverage is 100% by default and the baseline is 4. The description adds meaning about the tool's output (release identifiers, effective dates, code counts) without needing to explain inputs. It does not introduce any ambiguity about parameter usage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'List' and the resource 'bundled US medical code systems' with specific attributes (release identifiers, effective dates, code counts). It distinguishes itself from sibling tools that browse, check, get, map, or search codes by focusing on system-level metadata.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

The description gives explicit usage context: '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 tells the agent to call this tool first to verify system versions. It does not name alternative tools, but the purpose is clear enough for a status/list tool.

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

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

Beyond the annotations (readOnlyHint, idempotentHint), the description discloses critical behavioral traits: depth-1 traversal, successful empty result with notice for no edge, alsoInSystems for cross-system codes, source provenance on every result, and detailed pagination semantics. This goes far beyond what annotations provide and sets accurate expectations for agents.

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

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

The description is dense but every sentence carries useful information. It starts with the core purpose, then systematically covers hierarchy behavior, cross-system detection, drug directions, pagination, and provenance. No filler or repetition; 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.

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

Given the tool's complexity (7 directions, pagination, multiple systems, NDC formats), the description is comprehensive. It covers edge cases (empty results, alsoInSystems, iterative traversal), explains provenance for chained calls, and the presence of an output schema means return-value details are not the description's responsibility. The description leaves no obvious gaps.

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

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

Even though the schema documents all parameters (100% coverage), the description adds substantial semantic depth: it explains each direction's meaning, NDC format variations (hyphenated 4-4-2 etc.), the system auto-detect vs forced system option, cursor/limit behavior with defaults and ceiling, and the product-decoding nuance for ndc_to_rxcui. This materially helps an agent choose and format parameters correctly.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a clear, specific verb and resource: 'Crosswalk a US medical code or drug across systems and within a hierarchy.' This immediately distinguishes the tool from sibling tools like medcode_search_codes or medcode_get_code by focusing on transformation/mapping rather than lookup or validation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

The description provides strong usage context: it explains that parents/children are depth-1 and must be called iteratively for full paths, it clarifies pagination behavior with nextCursor/limit, and it notes that point directions ignore pagination. While it doesn't explicitly name alternative tools or when not to use this tool, it gives enough situational guidance to choose directions correctly.

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

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

The annotations already declare readOnlyHint and idempotentHint, but the description adds substantial behavioral context: token-prefix then substring matching, ranking with exact-prefix matches ahead, deterministic tie-breaking, pagination via nextCursor, and chapter normalization behavior with appliedFilters disclosure. 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.

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

The description is dense and front-loaded, with the core purpose stated first. Every sentence carries useful information, though it is a single long paragraph that could benefit from light structuring. It remains appropriately sized for the tool's complexity.

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

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

Given the tool has an output schema, return values need not be detailed. The description covers the matching algorithm, ranking behavior, filtering options, pagination, and case-insensitive chapter handling. It is complete for a search tool with complex behavior and leaves no significant gaps.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds minor context (e.g., limit default, chapter case-insensitivity) but does not materially augment parameter meaning beyond what the schema provides. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with 'Find US medical codes whose official descriptions match a described concept, via full-text search over the bundled index,' using a specific verb and clear resource. It also distinguishes itself from siblings by explicitly stating it is 'the reverse of medcode_get_code.'

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

The description provides a clear usage scenario: 'Use when you have a clinical description and need the code.' It names one alternative (the reverse of medcode_get_code) but does not explicitly address when not to use the tool or compare with other siblings like browse_hierarchy or map_codes. This is helpful but not exhaustive.

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