Medicaid Intelligence

Medicaid Drug Trend

medicaid_drug_trend

Read-onlyIdempotent

How much Medicaid spent on a drug, year by year — annual prescriptions, units and gross reimbursement from 2020 onward, split between fee-for-service and managed care. Ask by NAME ("Ozempic", "Humira"): the name is matched against the Medicaid product list and aggregated across every package size, so this answers "how much did Medicaid spend on X" directly. An exact 11-digit NDC narrows to one package instead. Reimbursement is GROSS, before the rebates Medicaid negotiates, so it is not manufacturer revenue or net cost to the programme. Suppressed values are never converted to zero.

Input Schema

TableJSON Schema

Name	Required	Description
`ndc`	No	Exact 11-digit National Drug Code, hyphenated or not, e.g. "00002-1433-80". Optional — give this OR drug. An NDC narrows to one package size.
`drug`	No	Drug name as it appears on the package, e.g. "Ozempic" or "Humira" — matched against the Medicaid product list, aggregating every package size. A generic ingredient is expanded to its NDCs automatically when Medicaid lists it only under brands.
`state`	No	US state, as a two-letter code ("CA") or a full name ("California") — both are accepted.
`to_year`	No	Last calendar year, 2026 or earlier.
`from_year`	No	First calendar year, 2020 or later. Defaults to 2024 — pass an earlier year for a longer history.

Output Schema

TableJSON Schema

Name	Required	Description
`ndc`	No	Present only when the call was matched on an exact NDC.
`drug`	No
`state`	No
`years`	Yes
`source`	Yes
`matched_by`	Yes	ndc \| product_name \| ndc_expansion.
`interpretation`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed5 schema fields changedAug 21, 2026

addedOutput schema / properties / drug
```
Added value: +{
+  "type": "string"
+}
```

addedOutput schema / properties / matched_by

Added value: +{
+  "description": "ndc | product_name | ndc_expansion.",
+  "type": "string"
+}

addedOutput schema / properties / ndc / description

Added value: +"Present only when the call was matched on an exact NDC."

addedOutput schema / properties / state

Added value: +{
+  "type": [
+    "string",
+    "null"
+  ]
+}

changedOutput schema / required

Previous value: -[
-  "ndc",
-  "years",
-  "source",
-  "interpretation"
-]New value: +[
+  "matched_by",
+  "years",
+  "source",
+  "interpretation"
+]

Changed5 schema fields changedAug 12, 2026

changedInput schema / examples

Previous value: -[
-  {
-    "from_year": 2022,
-    "ndc": "00002143380",
-    "state": "CA",
-    "to_year": 2025
-  }
-]New value: +[
+  {
+    "drug": "Ozempic"
+  },
+  {
+    "drug": "Humira",
+    "from_year": 2024,
+    "to_year": 2026
+  },
+  {
+    "from_year": 2022,
+    "ndc": "00002143380",
+    "state": "CA",
+    "to_year": 2025
+  }
+]

addedInput schema / properties / drug

Added value: +{
+  "description": "Drug name as it appears on the package, e.g. \"Ozempic\" or \"Humira\" — matched against the Medicaid product list, aggregating every package size. A generic ingredient is expanded to its NDCs automatically when Medicaid lists it only under brands.",
+  "type": "string"
+}

changedInput schema / properties / from_year / description

Previous value: -"First calendar year, 2020 or later."New value: +"First calendar year, 2020 or later. Defaults to 2024 — pass an earlier year for a longer history."

changedInput schema / properties / ndc / description

Previous value: -"Exact 11-digit National Drug Code, hyphenated or not, e.g. \"00002-1433-80\" or \"00002143380\". Resolve a brand or ingredient name to an NDC first with openfda_drug_label or rxnorm."New value: +"Exact 11-digit National Drug Code, hyphenated or not, e.g. \"00002-1433-80\". Optional — give this OR drug. An NDC narrows to one package size."

changedInput schema / required

Previous value: -[
-  "ndc"
-]New value: +[]

First observedAug 3, 2026

TDQS

A4.3/5.0

Behavior4/5

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

Annotations already declare the tool safe (readOnly, idempotent, non-destructive). The description adds valuable behavioral context beyond that: reimbursement is GROSS (not manufacturer revenue), suppressed values are never converted to zero, and it covers the 2020-onward scope. It also notes the split between fee-for-service and managed care, enriching the agent's understanding of the data returned.

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

Conciseness5/5

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

The description is a single, well-organized paragraph that front-loads the core purpose, then the query options, then key caveats (gross reimbursement, suppressed values). Every sentence earns its place, with no redundancy. It is appropriately sized for the tool's complexity.

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?

The tool has 5 optional parameters, an output schema, and rich annotations. The description covers the main behavioral nuances (gross vs net, suppressed values, name vs NDC) and the scope (2020 onward, split by care type). It does not need to repeat return-value details since an output schema exists, and parameter descriptions in the schema handle input specifics. The description is complete for agent selection and invocation.

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

Parameters3/5

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

Schema description coverage is 100%, and the schema itself thoroughly explains each parameter (ndc, drug, state, to_year, from_year). The description adds slight interpretation (e.g., name matching aggregates across package sizes, NDC narrows to one package), but these points are largely echoed in the schema. The baseline of 3 is appropriate; the description does not significantly add beyond the schema.

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?

The description clearly states the tool's function: 'How much Medicaid spent on a drug, year by year' — a specific verb (spend) and resource (drug trend). It distinguishes itself from sibling tools like medicaid_drug_state_market or medicaid_drug_utilization by focusing on temporal spending trends and gross reimbursement. The name/NDC distinction further clarifies the primary query modes.

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

Usage Guidelines4/5

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

The description provides clear guidance on how to query: 'Ask by NAME... An exact 11-digit NDC narrows to one package instead.' It also implies when to use this tool for longitudinal spending data, though it does not explicitly name alternative tools for exclusions. The gross vs net clarification helps agents interpret outputs correctly, meeting the 'clear context' bar.

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

All Medicaid Intelligence 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.