plan_hospital_price

What it answers

1. 1One hospital, one code, the rate by payer and plan name as the hospital filed it (where negotiated rates by insurer live today; the insurer-file / TiC tools are coming soon).
2. 2Dry-run a bounded hospital fact_hospital_chargemaster proof.
3. 3Requires hospital_ccn and billing_code, plans Iceberg files/bytes before materializing rows, and returns a receipt-shaped plan.

Inputs (11)

Call it

# MCP (https://mcp.vladahealth.com/mcp): the tool by name
plan_hospital_price(hospital_ccn="070005", billing_code="70450")

curl -X POST https://api.vladahealth.com/v1/tools/plan_hospital_price \
  -H "Authorization: Bearer $VLADA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"hospital_ccn":"070005","billing_code":"70450"}'

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

A real answer

{
 "value": {
  "proof_kind": "hospital_price_proof",
  "source_table": "fact_hospital_chargemaster",
  "hospital_ccn": "070005",
  "billing_code": "70450",
  "version_id": null,
  "planned_file_count": 1,
  "planned_bytes": 93233000,
  "planned_record_count": 1908186,
  "planned_delete_file_count": 0,
  "plan_manifest_hash": "432b007b75d09646abed67f2ed3107945c3e9902b0518a03d1cffbceaa5b8abb",
  "row_count": 0,
  "status": "planned",
  "all_rows_have_byte_provenance": true,
  "distinct_payer_names": [],
  "distinct_plan_names": [],
  "distinct_billing_classes": [],
  "distinct_methodologies": [],
  "distinct_content_sha256": [],
  "distinct_raw_s3_keys": [],
  "distinct_mrf_version_ids": [],
  "verdict": "planned"
 },
 "unit": null,
 "vintage": null,
 "methodology": null,
 "caveats": [],
 "response_hash": "58de83528854634706f3ef649906303176a93561774568603234fdef9b65286d",
 "semantic_version": 1,
 "tool_version": "plan_hospital_price@1.5.0",
 "explanation": null,
 "status": "complete",
 "proof_id": "hospitalprice_207327c53f67604d",
 "receipt": {
  "receipt_version": "hospital_price_proof_receipt.v0",
  "substrate": "hospital",
  "proof_kind": "hospital_price_proof",
  "proof_id": "hospitalprice_207327c53f67604d",
  "tool_name": "plan_hospital_price",
  "tool_version": "1.5.0",
  "source_table": "fact_hospital_chargemaster",
  "source_descriptor": {
   "table": "fact_hospital_chargemaster",
   "snapshot_id": "4789942790573672775",
   "raw_s3_keys": [],
   "content_sha256": [],
   "mrf_version_ids": [],
   "source_urls": [],
   "parser_artifact_hashes": [],
   "s3_version_ids": []
  },
  "read_snapshot_set": {
   "fact_hospital_chargemaster": "4789942790573672775"
  },
  "filters": {
   "hospital_ccn": "070005",
   "billing_code": "70450",
   "current_only": true
  },
  "guardrails": {
   "max_rows": 500,
   "max_planned_files": 500,
   "max_planned_bytes": 268435456,
   "current_only": true,
   "require_byte_provenance": true,
   "raw_parquet_glob_reads": "disabled",
   "shared_mrf_expansion": "not_performed_mvp"
  },
  "plan": {
   "planned_file_count": 1,
   "planned_bytes": 93233000,
   "planned_record_count": 1908186,
   "planned_delete_file_count": 0,
   "plan_manifest_hash": "432b007b75d09646abed67f2ed3107945c3e9902b0518a03d1cffbceaa5b8abb",
   "planned_files_sample": [
    "data/_VXeSg/hospital_state=CT/hospital_ccn=070005/20261002_010134_00448_k6qzf-35fcae15-3a2d-46e0-8d5d-644da8afbb0b.parquet"
   ]
  },
  "evidence": {
   "plan": {
    "planned_file_count": 1,
    "planned_bytes": 93233000,
    "planned_record_count": 1908186,
    "planned_delete_file_count": 0,
    "plan_manifest_hash": "432b007b75d09646abed67f2ed3107945c3e9902b0518a03d1cffbceaa5b8abb",
    "planned_files_sample": [
     "data/_VXeSg/hospital_state=CT/hospital_ccn=070005/20261002_010134_00448_k6qzf-35fcae15-3a2d-46e0-8d5d-644da8afbb0b.parquet"
    ]
   },
   "audit_chain": {
    "row_count": 0,
    "raw_s3_key_count": 0,
    "content_sha256_count": 0,
    "mrf_version_id_count": 0,
    "parser_artifact_hash_count": 0,
    "all_rows_have_byte_provenance": true
   }
  },
  "row_count": 0,
  "status": "planned",
  "caveats": [
   "billing_class_may_be_mixed",
   "current_rows_only_version_not_pinned_by_input",
   "hospital_price_proof_mvp_no_provider_group_expansion",
   "hospital_rates_are_chargemaster_mrf_rates_not_claims",
   "no_utilization_weighting_applied",
   "payer_name_may_be_mixed",
   "plan_name_may_be_mixed"
  ],
  "input_hash": "207327c53f67604d2fa515cbfde95955a8a3db0dbf20fdfddf8e97968f331723",
  "response_hash": "58de83528854634706f3ef649906303176a93561774568603234fdef9b65286d",
  "replay_pointer": {
   "tool": "plan_hospital_price",
   "inputs": {
    "hospital_ccn": "070005",
    "billing_code": "70450",
    "current_only": true,
    "require_byte_provenance": true,
    "max_rows": 500,
    "max_planned_files": 500,
    "max_planned_bytes": 268435456
   },
   "receipt_id": "hpr_58de83528854634706f3ef64"
  },
  "receipt_id": "hpr_58de83528854634706f3ef64"
 },
 "audience": "customer",
 "answer": {
  "value_ref": "value",
  "scope": {
   "tool": "plan_hospital_price",
   "filters": {
    "hospital_ccn": "070005",
    "billing_code": "70450",
    "current_only": true,
    "require_byte_provenance": true,
    "max_rows": 500,
    "max_planned_files": 500,
    "max_planned_bytes": 268435456
   }
  }
 },
 "method": "Negotiated facility prices for 70450 across hospitals, all plan types, compared on a single price basis. Percent-of-charge prices and list prices were set aside. You did not specify current_only; yes was used. You did not specify max_planned_bytes; 268435456 was used. You did not specify max_planned_files; 500 was used. You did not specify require_byte_provenance; yes was used.",
 "evidence": {
  "response_hash": "58de83528854634706f3ef649906303176a93561774568603234fdef9b65286d"
 },
 "defaults_applied": [
  {
   "param": "current_only",
   "used": true,
   "reason": "tool default"
  },
  {
   "param": "max_planned_bytes",
   "used": 268435456,
   "reason": "tool default"
  },
  {
   "param": "max_planned_files",
   "used": 500,
   "reason": "tool default"
  },
  {
   "param": "require_byte_provenance",
   "used": true,
   "reason": "tool default"
  }
 ],
 "freshness": {
  "state": "unknown",
  "why": "This tool does not report an edition for its answer, and the door could not derive one from what the answer reads. Treat the result as current to no stated date."
 }
}

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": "ok",
   "enum": [
    "planned",
    "ok",
    "no_match",
    "rejected_guardrail",
    "too_large_for_sync",
    "summary_from_cell_table"
   ],
   "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"
  },
  "proof_id": {
   "default": "",
   "title": "Proof Id",
   "type": "string"
  },
  "receipt": {
   "additionalProperties": true,
   "title": "Receipt",
   "type": "object"
  }
 },
 "title": "HospitalPriceProofResponse",
 "type": "object"
}

Sources

Known limits (0)