# Ground an agent

URL: https://docs.healthcare.dev/recipes/ground-an-agent

|       |                                                                                                                                                                                                                  |
| ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Plan  | **Every plan**. Each tool needs the plan its endpoint does: payer metrics on Builder, joined answers and coverage on Pro. Free and Builder get a monthly preview of each (the tool says how many calls are left) |
| Tools | [Every MCP tool](/mcp/tools), read-only, at most 10 results each, each citing `source` and `data_version`                                                                                                        |
| Cost  | An MCP tool call costs exactly what the REST call does                                                                                                                                                           |

An agent working from memory will state last year's code, miss a shortage that started last week
and can't know whether a provider was excluded last month. Give it the tools, tell it to use them
for every fact, and make it cite the release it used.

## 1. Connect the MCP server

Remote, nothing to install (Claude Code shown; [other clients](/mcp)):

```sh
claude mcp add --transport http healthcare-dev https://mcp.healthcare.dev/mcp \
  --header "Authorization: Bearer $HDEV_API_KEY"
```

Any client that takes a JSON config:

```json
{
  "mcpServers": {
    "healthcare-dev": {
      "url": "https://mcp.healthcare.dev/mcp",
      "headers": { "Authorization": "Bearer hdev_live_..." }
    }
  }
}
```

Or run it locally over stdio: `npx -y @healthcare.dev/mcp` with `HDEV_API_KEY` set. Don't commit
a config file that contains your key; for a shared or production agent, give it a
[child key](/child-keys) with its own scopes and spend cap.

## 2. Give it a system prompt

```md
You answer questions about US healthcare reference data: codes, drugs, providers, Medicare
coverage and payer prior authorization.

- Use the healthcare-dev tools for every code, drug, provider, coverage or payer fact. Never
  answer those from memory, even when you think you know.
- Cite every fact: the tool's `source` and `data_version`, and the `evidence` link when there is
  one.
- When an answer has `derivation`, say how it was reached: `source_stated` (the source says it),
  `derived` (concluded from what the source says) or `reviewed` (a person checked it). Give
  `confidence` and suggest reading the evidence when it is below 1.
- `not_listed`, an empty list or `false` from a check means the source lists nothing, not that
  the answer is no. Say so, with the tool's note.
- Show the disclaimer the tool returns. This is reference data, not medical, coding, billing,
  coverage or prior authorization advice.
- Never send or ask for patient information: no names, dates of birth, member ids or notes
  about a person.
- If a tool answers `plan-upgrade-required`, say which plan it needs; don't guess the answer, and
  don't present its sample answer (for a demo subject) as the answer to the question.
```

Coding agents can load the same rules as a skill: [Agent skill](/agents/skill).

## 3. Cite `meta` when you call the API yourself

When your own code calls the API and passes results to a model, pass the provenance with the
data. Every response's `meta` has `source`, `data_version`, `retrieved_at` and `license`;
`meta.license_terms` says what you may show end users.

**TypeScript**

```ts
import { HealthcareDev } from "@healthcare.dev/sdk";

const hdev = new HealthcareDev();
const { data, meta } = await hdev.providers.exclusions("1922348218");

const citation = `${meta.source} ${meta.data_version}, retrieved ${meta.retrieved_at} (${meta.license})`;
const context = JSON.stringify({ answer: data, note: data.note, citation });
// pass `context` to your model as a tool result, with the system prompt above
```

**Python**

```python
import json
from healthcare_dev import HealthcareDev

hdev = HealthcareDev()
r = hdev.providers.exclusions("1922348218")
meta = r["meta"]

citation = f"{meta['source']} {meta['data_version']}, retrieved {meta['retrieved_at']} ({meta['license']})"
context = json.dumps({"answer": r["data"], "note": r["data"]["note"], "citation": citation})
```

## Ask an agent

Each needs live data, so an agent without the tools can't answer it correctly:

- "Is NPI 1922348218 excluded by the OIG or opted out of Medicare? Cite the source." (Free)
- "Is NDC 0003-0894-21 in shortage or under an open recall?" (Free)
- "What changed in the latest HCPCS release?" (Builder)
- "Does Medicare support code 11720 for diagnosis B35.1 in Texas?" (Pro, or a preview on Free)

## What it is not

The tools give an agent reference data with its provenance. They don't make the agent's
conclusions clinical, coding, billing or coverage advice; keep a person in the loop for those.