Module `ahon_knowledgebase_mcp.tools`

Lookup tools for AHON GP tables, ICPC-2, and NHG Table 45.

Functions

def describe_details_icpc_code(code: str) ‑> dict[str, str]

Return ICPC-2 code details including inclusion, exclusion criteria, and notes.

Args
-----=
code: ICPC-2 code (e.g. W81, K74, -34).

def describe_icpc_chapters() ‑> dict[str, str]

Retrieve the descriptions of the ICPC-2 chapters for narrowing down diagnostic codes.

Complaints, symptoms, and conditions are registered using the International Classification of Primary Care (ICPC)-2 classification system. Each code has a letter (the chapter) followed by two digits indicating: - symptoms (01–29), - diagnoses (70–99). Process/actions (30–69) appear as separate codes prefixed with - (e.g. -34), not under letter chapters. Subgroups use a period and two digits (e.g. R83.03).

Returns -----= For each ICPC-2 chapter (key), a description of the body-system chapters (value).

def describe_materials(primary_category: Union[Literal['A', 'B', 'D', 'F', 'H', 'K', 'L', 'N', 'P', 'R', 'S', 'T', 'U', 'W', 'X', 'Y', 'Z'], Literal['O', 'Q']]) ‑> dict[str, str]

List specimen/material codes for NHG diagnostic measurements in one primary category.

Use before describe_qualifiers() and fetch_measurement_nhg_ids() to narrow material codes (e.g., blood plasma).

Args
-----=
primary_category: Select only material codes matching this ICPC chapter (e.g., "B" for blood; see describe_icpc_chapters()). Includes two classes in addition to the ICPC chapters: "O" (other) and "Q" (unknown).

Returns: For each one or two-letter material code (key; e.g., "BP"), its description (value; e.g., "Blood plasma").

def describe_qualifiers(material: str) ‑> dict[str, str]

Describe qualifier codes that apply to measurements of a given material.

Qualifiers refine a measurement (e.g. "NU" = fasting). Call after describe_materials() and before fetch_measurement_nhg_ids() when the research question implies a condition of measurement.

Args
-----=
material: A one or twe letter code that refers to the organ (or organsystem) of the diagnostic measurement (e.g., "BP" for blood plasma; see describe_materials()). Only qualifiers that appear for this material in NHG Table 45 are returned.

Returns: For each two character alphanumeric code (key; e.g., "NU"), a concise description (value; e.g, "fasting").

def fetch_ahon_tables_overview(release: Literal['dws-2288-BrtErn1', 'AHON-2026']) ‑> str

General practice patient data available in the AHON database.

Args
-----=
release: Database schema's vary per data release. - "AHON-2026": Typical schema of a dataset released in 2026., - "dws-2288-BrtErn1": the extract on the Bert & Ernie MyDRE machines. This is the data extract also used in the paper of Homburg et al., 2025.

Returns -----= A catalog of tables with patient data available for analysis (CSV paths and schema keys). References: Homburg et al. "AI-driven early infectious disease detection in Dutch primary care using BERT and ERNIE." NPJ Digital Medicine 9.1 (2025): 92.

def fetch_icpc_chapter_codes(chapter: Literal['A', 'B', 'D', 'F', 'H', 'K', 'L', 'N', 'P', 'R', 'S', 'T', 'U', 'W', 'X', 'Y', 'Z'], component: Literal['symptoms', 'actions', 'diagnoses']) ‑> dict[str, str]

List ICPC-2 codes in one body-system chapter.

Args
-----=
chapter: Chapter letter from fetch_icpc_chapters.
component: Optionally restrict to symptoms (01–29), actions (30–69), or diagnoses (70–99). Letter chapters contain symptoms and diagnoses only; actions (30–69) are process codes prefixed with -.

def fetch_measurement_nhg_ids(material: str, qualifier: str | None = None, pattern: str | None = None) ‑> str

Get NHG Table 45 diagnostic measurement IDs for the given material.

Use the returned NHG identifiers as NHGNummer key when planning filters on the AHON measurement/determination table.

Args
-----=
material: One- or two-character specimen/material code (e.g. "BP" for blood plasma; see describe_materials()).
qualifier: Optional two-character qualifier (e.g. "NU" for fasting; see describe_qualifiers()). None means no qualifier filter (all measurements for the material). Pass a code to restrict to that qualifier only.
pattern: Optional case-insensitive regular expression matched against memo, abbreviation, and description. A row is kept if any of these fields matches. None means no text filter.

The data are based on NHG (Dutch College of General Practitioners) Table 45, revision 45 (obtained from the elan-dcc repository; scraped 29/05/2024). Warning: Potentially outputs a large number of rows (e.g., when material="B"), when no qualifier or pattern is specified.

Returns
-----=
A markdown table of matching measurements. Columns: NHG identifier (index;

NHGNummer in the AHON measurement/determination table), memo code (up to four characters), qualifier code, abbreviation, and full name. Empty table if nothing matches.

def fetch_table_codebook(table: Literal['action', 'allergy', 'contact', 'contraindication', 'episode', 'journal', 'medication', 'measurement-determination', 'patient', 'referral'], release: Literal['dws-2288-BrtErn1', 'AHON-2026']) ‑> str

Return the column definitions and cleaning rules for one AHON GP table.

Args
-----=
table: Name of a table exported from the GP information system (HIS), e.g. patient, medication, episode, etc.
release: Database schema's vary per data release. - "AHON-2026": Typical schema of a dataset released in 2026., - "dws-2288-BrtErn1": the extract on the Bert & Ernie MyDRE machines. This is the data extract also used in the paper of Homburg et al., 2025.

References: Homburg et al. "AI-driven early infectious disease detection in Dutch primary care using BERT and ERNIE." NPJ Digital Medicine 9.1 (2025): 92.