Execute a FHIR $cql operation against a CQF-ruler server to evaluate a parameterized CQL expression against a specific patient and debug why a patient unexpectedly falls outside a measure population
POST a Parameters resource to the server's base $cql endpoint containing a parameter named expression with the CQL expression text as a string, a parameter named subject with the patient reference, and a parameter named parameters carrying a Tuple of any variable values needed by the expression
Start with the broadest population expression to confirm the server can evaluate the CQL at all; if the initial population returns false for a patient you expect to qualify, narrow to individual sub-expressions by wrapping them in isolated define statements
Add debug define statements that return intermediate values such as the dates of qualifying encounters or the codes on retrieved resources; each define result will appear as a separate parameter in the $cql response body allowing you to trace the evaluation path
Compare the codes returned by retrieve expressions against the expanded value sets used in the measure by calling $expand on the value set and checking whether the codes on the patient's resources are members; a retrieve returning an empty list is the most common root cause of population exclusion
Check date arithmetic by adding explicit interval define statements that compute the measurement period boundaries and compare them against the dates on clinical resources; off-by-one-day errors in period boundaries are a frequent source of population discrepancies
Once the root cause is identified, correct either the CQL expression, the value set content, or the underlying clinical data and re-evaluate until the patient appears in the expected population
Known gotchas
The $cql operation is not standardized across all FHIR server implementations; parameters, response format, and supported CQL features vary significantly between cqf-ruler, the CQL-evaluation-service, and commercial measure engines — test against the specific engine version deployed in your environment
CQL retrieve expressions return resources in the context of the subject patient; if the subject parameter is omitted, the engine may evaluate across all patients or return an error rather than clearly indicating that the patient context is missing
Date comparison in CQL is sensitive to whether dates are represented as Date, DateTime, or string types in the FHIR resources; a DateTime in UTC that converts to the previous calendar day in local time will cause the resource to fall outside a date-bounded measurement period
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