how_to_join

What it answers

1. 1Return the fail-closed measured way to join two Vlada substrate tables, including an explicit DIRECT_OK, DIRECT_DECLARED_KEY, NEEDS_GRAIN, ROUTE_THROUGH_DIM, ROUTE_MULTIHOP, or DO_NOT_SERVE directive.
2. 2Direct joins come from (in order) the measured connection registry, the VALIDATED join graph (catalog.json join_edges: uniqueness >= 0.999 and match >= 0.80, measured live), or the semantic layer's declared shared surrogate key (DIRECT_DECLARED_KEY, labelled not-live-measured); a validated or declared direct join is always preferred over a route and never refused.
3. 3Route coverage (min_coverage) is the weaker side of the weakest hop; a route under 50% is labelled low_coverage_route.
4. 4Unproved composite, NEEDS_GRAIN, quarantined, impossible, or N:M direct evidence cannot be served.
5. 5With only table_a, it lists every executable connection from that table.

Inputs (4)

Call it

# MCP (https://mcp.vladahealth.com/mcp): the tool by name
how_to_join(table_a="fact_hospital_chargemaster", table_b="dim_provider_ccn")

curl -X POST https://api.vladahealth.com/v1/tools/how_to_join \
  -H "Authorization: Bearer $VLADA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"table_a":"fact_hospital_chargemaster","table_b":"dim_provider_ccn"}'

# the schema, no key
curl https://api.vladahealth.com/v1/tools/how_to_join/schema

A real answer

{
 "value": {
  "table_a": "fact_hospital_chargemaster",
  "directive": "DIRECT_OK",
  "join": {
   "source": "catalog.json join_edges (validated_sampled)",
   "entity_key": "cms:ccn",
   "verdict": "VALIDATED",
   "match_rate": 0.999409,
   "uniqueness_on_authority": 1.0,
   "left_cov": 0.999409,
   "right_cov": null,
   "cardinality": "N:1",
   "fan_out_ratio": 1.0,
   "sample_size": 5076,
   "notes": "PASSED on a SAMPLE of the fact side -- this shows the join works, not that it holds universally."
  },
  "path": null,
  "grain_qualifier": [],
  "registry": {
   "status": "loaded",
   "measured_edge_count": 3008,
   "join_graph_validated_edge_count": 164,
   "table_count": 305,
   "source_files": []
  }
 },
 "unit": null,
 "vintage": null,
 "methodology": null,
 "caveats": [],
 "response_hash": "dbfeb6f1323d95fe4df912741b146b40305b3b8b2b716d7602516e06b1fa4426",
 "semantic_version": 1,
 "tool_version": "how_to_join@1.3.0",
 "explanation": null,
 "status": "complete",
 "audience": "customer",
 "answer": {
  "value_ref": "value",
  "scope": {
   "tool": "how_to_join",
   "filters": {
    "table_a": "fact_hospital_chargemaster",
    "offset": 0
   }
  }
 },
 "method": "Computed over the filters shown in this answer's scope, from the sources listed in its evidence. Nothing outside those filters was included. You did not specify offset; 0 was used.",
 "evidence": {
  "response_hash": "dbfeb6f1323d95fe4df912741b146b40305b3b8b2b716d7602516e06b1fa4426"
 },
 "defaults_applied": [
  {
   "param": "offset",
   "used": 0,
   "reason": "tool default"
  }
 ],
 "as_of": "2026-11-09",
 "as_of_basis": "the catalog of data sources this answer was composed from"
}

What comes back

{
 "$defs": {
  "Quality": {
   "description": "Row-level quality signal. All flags precomputed at build time\n(stored on the gold mart) and passed through here.",
   "properties": {
    "is_outlier": {
     "default": false,
     "title": "Is Outlier",
     "type": "boolean"
    },
    "is_ghost_candidate": {
     "default": false,
     "title": "Is Ghost Candidate",
     "type": "boolean"
    },
    "n_similar_rates": {
     "default": 0,
     "title": "N Similar Rates",
     "type": "integer"
    },
    "confidence": {
     "default": 1,
     "title": "Confidence",
     "type": "number"
    }
   },
   "title": "Quality",
   "type": "object"
  },
  "Source": {
   "description": "Cell-level provenance. Every served value traces back here.\n\n`snapshot_id` is the Iceberg snapshot the tool read from. Two calls\nat the same snapshot MUST produce byte-identical responses —\nthat's the content-addressed caching guarantee.",
   "properties": {
    "table": {
     "title": "Table",
     "type": "string"
    },
    "rate_id": {
     "anyOf": [
      {
       "type": "string"
      },
      {
       "type": "null"
      }
     ],
     "default": null,
     "title": "Rate Id"
    },
    "source_files": {
     "items": {
      "type": "string"
     },
     "title": "Source Files",
     "type": "array"
    },
    "snapshot_id": {
     "anyOf": [
      {
       "type": "integer"
      },
      {
       "type": "null"
      }
     ],
     "default": null,
     "title": "Snapshot Id"
    }
   },
   "required": [
    "table"
   ],
   "title": "Source",
   "type": "object"
  }
 },
 "properties": {
  "value": {
   "default": null,
   "title": "Value"
  },
  "unit": {
   "anyOf": [
    {
     "type": "string"
    },
    {
     "type": "null"
    }
   ],
   "default": null,
   "title": "Unit"
  },
  "vintage": {
   "anyOf": [
    {
     "type": "string"
    },
    {
     "type": "null"
    }
   ],
   "default": null,
   "title": "Vintage"
  },
  "source": {
   "$ref": "#/$defs/Source"
  },
  "methodology": {
   "anyOf": [
    {
     "type": "string"
    },
    {
     "type": "null"
    }
   ],
   "default": null,
   "title": "Methodology"
  },
  "quality": {
   "$ref": "#/$defs/Quality"
  },
  "invariants_applied": {
   "items": {
    "type": "string"
   },
   "title": "Invariants Applied",
   "type": "array"
  },
  "caveats": {
   "items": {
    "type": "string"
   },
   "title": "Caveats",
   "type": "array"
  },
  "response_hash": {
   "default": "",
   "title": "Response Hash",
   "type": "string"
  },
  "semantic_version": {
   "default": 1,
   "title": "Semantic Version",
   "type": "integer"
  },
  "tool_version": {
   "default": "unknown",
   "title": "Tool Version",
   "type": "string"
  },
  "explanation": {
   "anyOf": [
    {
     "type": "string"
    },
    {
     "type": "null"
    }
   ],
   "default": null,
   "title": "Explanation"
  },
  "status": {
   "default": "complete",
   "title": "Status",
   "type": "string"
  },
  "refusal": {
   "anyOf": [
    {
     "additionalProperties": true,
     "type": "object"
    },
    {
     "type": "null"
    }
   ],
   "default": null,
   "title": "Refusal"
  },
  "failure": {
   "anyOf": [
    {
     "additionalProperties": true,
     "type": "object"
    },
    {
     "type": "null"
    }
   ],
   "default": null,
   "title": "Failure"
  },
  "as_of": {
   "anyOf": [
    {
     "type": "string"
    },
    {
     "type": "null"
    }
   ],
   "default": null,
   "title": "As Of"
  },
  "freshness_state": {
   "default": "unknown",
   "title": "Freshness State",
   "type": "string"
  }
 },
 "title": "CatalogResponse",
 "type": "object"
}

Sources

Known limits (1)

1. 1Only joins resolvable to physical columns + measurable live are in the registry; big-fact joins are dimension-routed. Absence of a verified join means 'not proven', not 'impossible'.