Tools Reference

SaveHealth provides 4 tools that follow a sequential workflow: search, options, prices, coupon.

---

Quick Reference

Tool	Step	Input	Output	Purpose
search_drug	1	drug_name, limit?	name, slug	Find a drug by name
get_drug_options	2	slug, dosage?	NDC, dosage, form, quantity, type	Choose dosage/form/quantity
get_drug_prices	3	NDC, quantity	Prices with key per pharmacy	Compare pharmacy prices
get_coupon	4	key	Coupon details (BIN, PCN, etc.)	Get coupon for a pharmacy

INFO

If the user already has an NDC (from their prescription bottle), skip directly to step 3 (get_drug_prices).

---

Tool Annotations

All 4 tools share the same annotation profile, reflecting the server's read-only architecture:

{
  "readOnlyHint": true,
  "destructiveHint": false,
  "openWorldHint": false,
  "idempotentHint": true
}

---

Step 1: search_drug

Purpose: Fuzzy search for a drug by name. Returns matching drug names with slugs for identification. Handles misspellings, brand names, and partial matches.

Important

Always call this tool first. When needs_disambiguation is true, present all suggestions to the user and ask them to pick before proceeding.

Input:

{
  "drug_name": "lisinopril",
  "limit": 5
}

Output (multiple matches — disambiguation needed):

{
  "found": true,
  "query": "lisinopril",
  "suggestions": [
    { "name": "Lisinopril", "slug": "lisinopril" },
    { "name": "Lisinopril-hydrochlorothiazide", "slug": "lisinopril-hydrochlorothiazide" },
    { "name": "Zestril", "slug": "zestril" },
    { "name": "Qbrelis", "slug": "qbrelis" },
    { "name": "Zestoretic", "slug": "zestoretic" }
  ],
  "total_matches": 5,
  "needs_disambiguation": true
}

Output (no results):

{
  "found": false,
  "query": "xyzfakemed123",
  "suggestions": [],
  "total_matches": 0,
  "needs_disambiguation": false
}

---

Step 2: get_drug_options

Purpose: Get all available dosage strengths, forms, quantities, and NDC codes for a drug. Options are sorted Generic first, Brand second, with the default option marked.

Input:

{
  "slug": "lisinopril",
  "dosage": "20mg"
}

The optional dosage parameter filters results to a specific strength.

Output:

{
  "slug": "lisinopril",
  "default_ndc": "68180098103",
  "options": [
    {
      "name": "Lisinopril",
      "type": "Generic",
      "dosage": "20MG",
      "form": "Tablet",
      "quantity": 30,
      "quantities": [30, 60, 90, 135, 180],
      "ndc": "68180098103",
      "is_default": true
    },
    {
      "name": "Zestril",
      "type": "Brand",
      "dosage": "20MG",
      "form": "Tablet",
      "quantity": 30,
      "quantities": [30, 60, 90, 135, 180],
      "ndc": "24979024107",
      "is_default": false
    }
  ]
}

TIP

The type field ("Generic" or "Brand") helps users identify cheaper generic alternatives.

---

Step 3: get_drug_prices

Purpose: Get real-time pharmacy prices for a specific NDC and quantity. Prices are sorted cheapest first.

Input:

{
  "ndc": "68180098103",
  "quantity": 30,
  "drug_name": "Lisinopril",
  "dosage": "20MG",
  "drug_form": "Tablet",
  "drug_type": "Generic"
}

The drug_name, dosage, drug_form, and drug_type fields are optional pass-through context included in the response for display purposes.

Output:

{
  "ndc": "68180098103",
  "quantity": 30,
  "drug_name": "Lisinopril",
  "drug_type": "Generic",
  "drug_dosage": "20MG",
  "drug_form": "Tablet",
  "prices": [
    { "pharmacy": "Albertsons", "chain": "albertsons", "price": 9.74, "key": "CgdvcHR1bXJ4..." },
    { "pharmacy": "Walgreens", "chain": "walgreens", "price": 9.79, "key": "CgVoaXBwbxIk..." },
    { "pharmacy": "Walmart", "chain": "walmart", "price": 15.52, "key": "CgdvcHR1bXJ4..." },
    { "pharmacy": "CVS", "chain": "cvs", "price": 18.93, "key": "CgVoaXBwbxIk..." }
  ]
}

INFO

Each pharmacy entry includes a key that is required for the next step (get_coupon).

---

Step 4: get_coupon

Purpose: Get complete coupon/discount card details for a specific pharmacy, using the key from get_drug_prices.

Input:

{
  "key": "CgdvcHR1bXJ4EiQ5Mzk1OTBlZC1hMzVlLTQxNmMtYTA1Yy04MjY0YTIyOTZiYjE..."
}

Output:

{
  "pharmacy": "Albertsons",
  "discounted_price": 9.74,
  "coupon_code": "MC2D0DCCD0",
  "instructions": "Present this information at the pharmacy: BIN: 011867, PCN: HT, Group: LABH001, Member ID: MC2D0DCCD0",
  "source": "SaveHealth",
  "bin": "011867",
  "pcn": "HT",
  "group_id": "LABH001",
  "member_id": "MC2D0DCCD0"
}

TIP

The coupon fields (BIN, PCN, Group ID, Member ID) are everything the pharmacist needs to process the discount. Just show them at the counter.

---

Tool Dependency Map

Tool	Requires	Provides
search_drug	drug_name (string)	slug
get_drug_options	slug (from search_drug)	NDC, dosage, form, quantity, type
get_drug_prices	NDC + quantity (from get_drug_options)	price list with keys
get_coupon	key (from get_drug_prices)	coupon details