Ensure cqf-ruler is running with the clinical-reasoning module enabled; confirm the /cql/evaluate or /$cql endpoint is available via the server's CapabilityStatement or documentation
POST /$cql with a Parameters resource: include a subject parameter (Patient/{id}), a library parameter referencing the Library canonical URL, and an expression parameter naming the CQL expression to evaluate (e.g., 'Numerator')
Parse the returned Parameters resource; each result.name corresponds to an expression name and result.value holds the evaluated output (true/false for population criteria, resource lists for retrieve expressions)
If the expression returns unexpected results, add intermediate expression names (e.g., the retrieve expression listing qualifying diagnoses) as additional expression parameters to inspect intermediate values
Repeat with different patient IDs to validate that the CQL logic correctly includes and excludes patients based on their clinical data
Known gotchas
cqf-ruler's /$cql endpoint may differ in parameter naming from the HL7 specification's $cql operation; consult cqf-ruler-specific documentation rather than assuming the IG parameter names match exactly
If the Library referenced in the library parameter has not been loaded onto the cqf-ruler server, the operation returns a terminology or library resolution error, not a missing-resource 404 — pre-load all dependent Libraries before testing
CQL retrieve expressions that return empty lists are valid results (the patient has no qualifying resources), not errors; distinguish between an empty list result and a null result, as they have different implications for population inclusion
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp