MedPrice AI

Get price distribution for a billing code

get_code_price_distribution

Read-only

Returns the distribution of every hospital's price for a code_type/code, computed server-side: min/p10/q1/median/q3/p90/max, standard deviation, a histogram, and the real hospital nearest each percentile. Use this instead of paging through list_hospital_code_costs when you want to know how prices spread across hospitals (e.g. "is $12k high for MS-DRG 788?" - pass reference_price to get the number of hospitals priced below it). All figures are in terms of the chosen statistic (default: each hospital's average price). Served from the hospital-prices serving snapshot, which pools exactly (exact medians), so figures can differ slightly from earlier results of this tool. Like those, each figure still combines facility and professional charges (and all settings) into one number; use get_code_provider_price_distribution for a per-billing-class breakdown instead. With statistic MIN/MAX the figure is now the hospital's lowest/highest charge itself, not widened by the filing's per-item minimum/maximum.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "code_type": "<code_type>",
      "code": "<code>"
    },
    "name": "get_code_price_distribution"
  }
}

Input Schema

Name	Required	Description
`code`	Yes
`bin_count`	No	Number of histogram bars. Defaults to 16, capped at 200 (larger values are rejected).
`code_type`	Yes	Code system the billing code belongs to, e.g. APR-DRG, CDM, CPT, HCPCS, MS-DRG, RC.
`statistic`	No	Which per-hospital figure to distribute: each hospital's average (default), median, lowest filed price, or highest filed price.
`methodology`	No	Pricing methodology. Omit to aggregate across all methodologies.
`reference_price`	No	Optional price to place on the distribution. When positive, hospitals_below_reference counts hospitals priced strictly below it. Negative values are rejected.
`min_sample_count`	No	Minimum pricing sample size: only include hospitals whose price is backed by at least this many billing records (same semantics as list_hospital_code_costs). 0 (default) disables the filter. Negative values are rejected.

Output Schema

Name	Required	Description
`q1`	No	25th percentile.
`q3`	No	75th percentile.
`max`	No
`min`	No
`p10`	No
`p90`	No
`mean`	No	Mean across hospitals of the request's statistic (a national average). 0 when hospital_count is 0.
`median`	No
`std_dev`	No	Population standard deviation of the per-hospital values.
`q1_hospital`	No	A real hospital and its price for the code, used to name a hospital at a percentile. Unset (absent or empty hospital_id) when hospital_count is 0.
`q3_hospital`	No	A real hospital and its price for the code, used to name a hospital at a percentile. Unset (absent or empty hospital_id) when hospital_count is 0.
`histogram_hi`	No	Upper edge of the last bar: min(max, 1.35 * p90), or min + 1 when that is not above the minimum. Hospitals priced above this are counted in overflow_count.
`histogram_lo`	No	Lower edge of the first histogram bar (the minimum).
`max_hospital`	No	A real hospital and its price for the code, used to name a hospital at a percentile. Unset (absent or empty hospital_id) when hospital_count is 0.
`min_hospital`	No	A real hospital and its price for the code, used to name a hospital at a percentile. Unset (absent or empty hospital_id) when hospital_count is 0.
`p10_hospital`	No	A real hospital and its price for the code, used to name a hospital at a percentile. Unset (absent or empty hospital_id) when hospital_count is 0.
`p90_hospital`	No	A real hospital and its price for the code, used to name a hospital at a percentile. Unset (absent or empty hospital_id) when hospital_count is 0.
`mean_hospital`	No	A real hospital and its price for the code, used to name a hospital at a percentile. Unset (absent or empty hospital_id) when hospital_count is 0.
`histogram_bins`	No	Hospital count per equal-width bar from histogram_lo to histogram_hi; the last bar includes its upper edge.
`hospital_count`	No	Hospitals with a positive value for the code on their latest revision (and at least min_sample_count samples, if set). 0 means every other field is unset.
`overflow_count`	No	Hospitals priced above histogram_hi.
`median_hospital`	No	A real hospital and its price for the code, used to name a hospital at a percentile. Unset (absent or empty hospital_id) when hospital_count is 0.
`hospitals_below_reference`	No	Hospitals priced strictly below the request's reference_price; 0 when it was not set.

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedOct 22, 2026

addedOutput schema / properties / mean

Added value: +{
+  "description": "Mean across hospitals of the request's statistic (a national average). 0 when hospital_count is 0.",
+  "type": "number"
+}

addedOutput schema / properties / mean_hospital

Added value: +{
+  "description": "A real hospital and its price for the code, used to name a hospital at a percentile. Unset (absent or empty hospital_id) when hospital_count is 0.",
+  "properties": {
+    "hospital_id": {
+      "description": "Opaque handle - pass back as hospital_id to other tools.",
+      "type": "string"
+    },
+    "hospital_name": {
+      "type": "string"
+    },
+    "location": {
+      "type": "string"
+    },
+    "price": {
+      "description": "This hospital's value of the requested statistic.",
+      "type": "number"
+    }
+  },
+  "type": [
+    "object",
+    "null"
+  ]
+}

AddedOct 20, 2026

TDQS

A4.8/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the read-only annotations, it discloses data provenance (served from the hospital-prices serving snapshot, exact medians due to pooling), an important caveat (figures may differ slightly from earlier calls), and a data-model warning that figures combine facility and professional charges across all settings. It also clarifies a subtle semantic change for MIN/MAX, that the value is the hospital's own lowest/highest charge rather than widened by per-item filing extremes.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the capability and the primary alternative-first routing, then progressively adds caveats. It is dense but every sentence carries information; the final MIN/MAX sentence is syntactically heavy and could be split, which keeps it from a 5.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 7-parameter aggregation tool with an output schema, the description covers the computation model, the statistic semantics, provenance caveats, and the sibling routing needed to choose correctly. Combined with the schema's parameter documentation and the output schema, nothing material is missing for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is high (86%), so the baseline is 3, but the description adds real meaning: it explains that all figures are expressed in terms of the chosen statistic (default per-hospital average) and gives a usage pattern for reference_price (pass it to get hospitals priced below a number). It reinforces min_sample_count semantics by tying it to list_hospital_code_costs, though bin_count and methodology get no extra treatment beyond their schema text.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Returns the distribution of every hospital's price for a code_type/code') and enumerates the exact outputs (min/p10/q1/median/q3/p90/max, stddev, histogram, nearest-hospital anchors). It explicitly names the two siblings it replaces or defers to: list_hospital_code_costs and get_code_provider_price_distribution.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit routing rule ('Use this instead of paging through list_hospital_code_costs when you want to know how prices spread across hospitals') with a concrete triggering question ('is $12k high for MS-DRG 788?'). It also names the alternative for a different need ('use get_code_provider_price_distribution for a per-billing-class breakdown instead'), so when-to-use and when-not-to-use are both covered.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All MedPrice AI tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.