atc_lookup

Instructions

Implementation Reference

• src/tools/atc.ts:132-169 (handler)

  The main handler function for the atc_lookup tool. Parses input (ATC code), calls the RxNorm client's getATCByCode, builds structured output, and returns formatted text.

  async function handleATCLookup(args: Record<string, unknown>): Promise<CallToolResult> {
    try {
      const params = ATCByCodeParamsSchema.parse(args);
      const client = getRxNormClient();
      const details = await client.getATCByCode(params.atc_code);
  
      const structured: ATCLookupOutput = {
        atc_code: params.atc_code,
        found: details !== null,
        details,
      };
  
      if (!details) {
        return {
          content: [
            {
              type: 'text',
              text: `# ATC code "${params.atc_code}" not found at level 1-4.\n\nIf this is a 7-character substance code (e.g., "A10BA02"), use atc_classify with the drug name instead — RxClass byId only exposes ATC1-4 codes.`,
            },
          ],
          structuredContent: structured,
        };
      }
  
      const lines: string[] = [
        `# ATC ${details.atc_code} — ${details.atc_name}`,
        '',
        `**Level:** ${details.atc_level_type}`,
      ];
  
      return {
        content: [{ type: 'text', text: lines.join('\n') }],
        structuredContent: structured,
      };
    } catch (error) {
      return handleToolError(error);
    }
  }

• src/clients/rxnorm-client.ts:430-458 (handler)

  The client-side implementation that calls the NLM RxClass byId API endpoint to resolve an ATC code (level 1-4) to its name and level type. Uses caching.

  async getATCByCode(atcCode: string): Promise<RxNormATCClass | null> {
    const cacheKey = `atc:bycode:${atcCode.toUpperCase()}`;
  
    return cache.getOrSet(
      CACHE_PREFIX.RXNORM,
      cacheKey,
      async () => {
        try {
          const response = await this.request<RxClassByIdResponse>(
            '/rxclass/class/byId.json',
            { classId: atcCode },
          );
          const item = response.rxclassMinConceptList?.rxclassMinConcept?.[0];
          if (!item) return null;
          return {
            atc_code: item.classId,
            atc_name: item.className,
            atc_level_type: item.classType,
          };
        } catch (error) {
          if (error instanceof ApiError && error.code === 'NOT_FOUND') {
            return null;
          }
          throw error;
        }
      },
      DEFAULT_TTL.LOOKUP,
    );
  }

• src/types/index.ts:646-650 (schema)

  Input schema (ATCByCodeParamsSchema) for atc_lookup — validates the atc_code parameter as a 1-5 character ATC code via regex.

  export const ATCByCodeParamsSchema = z.object({
    atc_code: ATCCodeSchema.describe(
      'ATC code at level 1-4 (1-5 chars). Substance-level codes (7 chars, e.g., A10BA02) are not exposed by this endpoint — use atc_classify with the drug name instead.',
    ),
  });

• src/types/index.ts:682-688 (schema)

  Output schema (ATCLookupOutputSchema) defining the structured response shape: atc_code, found boolean, and nullable details.

  export const ATCLookupOutputSchema = z.object({
    atc_code: z.string(),
    found: z.boolean(),
    // Populated when found=true. Null when the code is unknown or
    // substance-level (RxClass byId doesn't expose the 7-char codes).
    details: ATCClassEntrySchema.nullable(),
  });

• src/tools/atc.ts:221-221 (registration)

  Registration of atc_lookup tool: toolRegistry.register(atcLookupTool, handleATCLookup) binds the tool definition to its handler.

  toolRegistry.register(atcLookupTool, handleATCLookup);