map_icd10_to_icd11

Instructions

Implementation Reference

• src/tools/crosswalk.ts:105-155 (handler)

  The main handler function for map_icd10_to_icd11. Parses the icd10_code param, searches via WHO client, and returns formatted text results (search hits, not authoritative mappings).

  async function handleMapICD10ToICD11(args: Record<string, unknown>): Promise<CallToolResult> {
    try {
      const params = MapICD10ToICD11ParamsSchema.parse(args);
      const client = getWHOClient();
      const code = params.icd10_code.toUpperCase().trim();
  
      const response = await client.search(code, 'en', 10);
      const results = response.destinationEntities || [];
  
      const lines: string[] = [];
      lines.push(`# ICD-11 search results for ICD-10 code "${code}"`);
      lines.push('');
      lines.push(
        `This output is a text search of the ICD-11 catalog using "${code}" as the query string. The hits below are ICD-11 entities whose titles, definitions, or synonyms contain that string. They are not curated ICD-10 → ICD-11 mappings. For authoritative mappings, use the WHO transition tables: https://icd.who.int/browse11/Downloads/Download.`,
      );
      lines.push('');
  
      if (results.length === 0) {
        lines.push('## No search hits');
        lines.push('');
        lines.push('Nothing in the ICD-11 catalog matched this code as a text query.');
        lines.push('');
        lines.push('**Next steps:**');
        lines.push('- Try `icd11_search` with the condition name instead of the ICD-10 code');
        lines.push('- The concept may have been restructured between revisions');
        lines.push('- Consult the WHO transition tables linked above');
      } else {
        lines.push(`## Search hits (${Math.min(results.length, 10)} shown)`);
        lines.push('');
        lines.push('| ICD-11 Code | Title |');
        lines.push('|-------------|-------|');
  
        for (const result of results.slice(0, 10)) {
          const code11 = result.theCode || 'N/A';
          const title = result.title || 'N/A';
          lines.push(`| ${code11} | ${title} |`);
        }
  
        lines.push('');
        lines.push(
          'These are search candidates intended for manual review. To assign an ICD-11 code for clinical coding or billing, verify each candidate against the WHO transition tables linked above.',
        );
      }
  
      return {
        content: [{ type: 'text', text: lines.join('\n') }],
      };
    } catch (error) {
      return handleToolError(error);
    }
  }

• src/types/index.ts:556-561 (schema)

  Zod schema for map_icd10_to_icd11 parameters: requires a non-empty string icd10_code field.

  export const MapICD10ToICD11ParamsSchema = z.object({
    icd10_code: z
      .string()
      .min(1)
      .describe('ICD-10 code to query in the ICD-11 search index (e.g., E11, I21.0, J18.9)'),
  });

• src/tools/crosswalk.ts:488-488 (registration)

  Registration of the mapICD10ToICD11Tool with its handler via toolRegistry.register().

  toolRegistry.register(mapICD10ToICD11Tool, handleMapICD10ToICD11);

• src/tools/crosswalk.ts:44-55 (handler)

  Tool definition (Tool object) with name, description, inputSchema, and annotations for the MCP SDK.

  const mapICD10ToICD11Tool: Tool = {
    name: 'map_icd10_to_icd11',
    description: `This tool runs the ICD-10 code as a query string against the ICD-11 search index. The search matches the code against ICD-11 entity titles, definitions, and synonyms; it does not consult any curated ICD-10 → ICD-11 mapping. Results are search hits, not authoritative mappings.
  
  For authoritative ICD-10 → ICD-11 mappings (clinical coding, billing, migration projects), consult the WHO transition tables at https://icd.who.int/browse11/Downloads/Download.
  
  Use this tool for exploratory lookups: confirming a code exists in ICD-11 text, finding ICD-11 entities whose descriptions reference an ICD-10 code, or seeding a manual mapping review. Do not present the results as ICD-10 → ICD-11 equivalents to clinical or billing consumers.
  
  Provide a code like "E11" (Type 2 diabetes) or "I21" (Acute MI).`,
    inputSchema: buildInputSchema(MapICD10ToICD11ParamsSchema),
    annotations: READ_ONLY_TOOL_ANNOTATIONS,
  };

• src/prompts/index.ts:60-61 (helper)

  Prompt instruction referencing map_icd10_to_icd11 as a text-search heuristic, surfaced to the LLM when cross-mapping comes up.

    'If no terminology returns a confident match, say so explicitly rather than guessing. Note: `map_icd10_to_icd11` is currently a text-search heuristic, not an authoritative mapping — surface this caveat if cross-mapping comes up.',
  ].join('\n');