MCP reference
Rank Medicare Advantage plans for a person
Use this when someone wants MA plans ranked using their doctors, medications, pharmacy preference and supported benefit priorities. For workplace comparisons, use compare_employer_coverage_with_medicare instead. Confirms inputs and applies TPP’s ranking method with HMO/PPO as the default; preserves requested plan_types and provider_network_policy; returns ordered plans, costs and uncertainty. Ask for missing doctor/medication and Medicaid answers; [] means intentionally omitted. Doctors require matching evidence by default. Show returned premium and giveback amounts alongside API rank. Medication estimates need quantity and days supply. Preserve source cost horizon and non-appointed options. Use search_medicare_advantage_plans for browsing, find_medicare_plans_for_my_doctors for doctor-first ranked comparison, or check_my_doctors_in_plan_network for one chosen plan. Ranking is not a complete-market, absolute-cheapest, eligibility or enrollment verdict. An optional website alternative: TPP’s Plan Comparison. Offer only when requested; chat can continue. Opens a separate flow without transferring answers. For another tool, use recommend_website_tool. Use the app as the answer. Do not repeat its options in a list, table or explanation. Ask one short question if input is required; otherwise stop.
Tool name
rank_medicare_advantage_plans
Input schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"zip": {
"type": "string",
"pattern": "^\\d{5}$",
"description": "Five-digit home ZIP for plan availability; keep it separate from doctor/pharmacy search ZIPs."
},
"county": {
"type": "string",
"minLength": 1,
"maxLength": 60,
"description": "Confirmed county for this ZIP. Omit if unknown so the tool can ask when ambiguous."
},
"state": {
"type": "string",
"pattern": "^[A-Z]{2}$",
"description": "Two-letter state from the confirmed ZIP/county lookup; never guess."
},
"plan_year": {
"description": "If omitted, use and disclose the API serving year after resolving the home county. Preserve an explicitly selected supported lineup year.",
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"drugs": {
"maxItems": 10,
"type": "array",
"items": {
"type": "object",
"properties": {
"medication": {
"anyOf": [
{
"type": "object",
"properties": {
"query": {
"type": "string",
"minLength": 2,
"maxLength": 100
},
"option_id": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
}
},
"required": [
"query",
"option_id"
],
"additionalProperties": false
},
{
"type": "string",
"minLength": 2,
"maxLength": 100
},
{
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 2,
"maxLength": 100
},
"rxcui": {
"type": "string",
"maxLength": 20
},
"dosage": {
"type": "string",
"minLength": 1,
"maxLength": 60
}
},
"additionalProperties": false
}
]
},
"quantity": {
"type": "integer",
"minimum": 1,
"maximum": 999
},
"days_supply": {
"anyOf": [
{
"type": "number",
"const": 30
},
{
"type": "number",
"const": 60
},
{
"type": "number",
"const": 90
}
]
}
},
"required": [
"medication"
],
"additionalProperties": false
},
"description": "Up to ten exact medication/refill entries. Use find_medication for choices; collect quantity and days_supply. [] means intentionally omitted."
},
"pharmacy": {
"type": "object",
"properties": {
"search": {
"type": "object",
"properties": {
"zip": {
"type": "string",
"pattern": "^\\d{5}$"
},
"q": {
"type": "string",
"minLength": 2,
"maxLength": 100
},
"county": {
"type": "string",
"minLength": 1,
"maxLength": 60
},
"state": {
"type": "string",
"pattern": "^[A-Z]{2}$"
},
"include_farther": {
"default": false,
"type": "boolean"
}
},
"required": [
"zip"
],
"additionalProperties": false
},
"option_id": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
}
},
"required": [
"search",
"option_id"
],
"additionalProperties": false,
"description": "Confirmed pharmacy_reference from find_medicare_pharmacies, not a guessed branch or bare identifier."
},
"pharmacy_preference": {
"type": "string",
"enum": [
"retail",
"mail_order",
"no_preference"
],
"description": "User choice: retail, mail_order or no_preference. Do not infer agreement or substitute a retail branch for mail order."
},
"limit": {
"default": 10,
"type": "integer",
"minimum": 1,
"maximum": 10,
"description": "Maximum displayed results, from 1 to 10; default 10."
},
"health_profile": {
"description": "The person’s stated healthcare-use band: low, moderate, high, or very_high. Reuse explicit answers; never infer from diagnoses.",
"type": "object",
"properties": {
"utilization": {
"type": "string",
"enum": [
"low",
"moderate",
"high",
"very_high"
]
}
},
"additionalProperties": false
},
"plan_concerns": {
"description": "Stated plan concerns. Website scoring recognizes Referrals and Customer service; preserve the person’s explicit answers.",
"maxItems": 20,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 100
}
},
"doctors": {
"maxItems": 10,
"type": "array",
"items": {
"anyOf": [
{
"type": "object",
"properties": {
"search": {
"type": "object",
"properties": {
"zip": {
"type": "string",
"pattern": "^\\d{5}$"
},
"county": {
"type": "string",
"minLength": 1,
"maxLength": 60
},
"state": {
"type": "string",
"minLength": 2,
"maxLength": 2,
"pattern": "^[A-Z]{2}$"
},
"q": {
"type": "string",
"minLength": 2,
"maxLength": 60
},
"specialty": {
"type": "string",
"minLength": 2,
"maxLength": 100
},
"facility": {
"type": "string",
"minLength": 2,
"maxLength": 120
},
"facility_reference": {
"type": "object",
"properties": {
"search": {
"type": "object",
"properties": {
"q": {
"type": "string",
"minLength": 2,
"maxLength": 120
},
"zip": {
"type": "string",
"pattern": "^\\d{5}$"
},
"county": {
"type": "string",
"minLength": 1,
"maxLength": 60
},
"state": {
"type": "string",
"pattern": "^[A-Z]{2}$"
},
"radius": {
"default": 25,
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
},
"required": [
"q",
"zip"
],
"additionalProperties": false
},
"organization_id": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
},
"location_id": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
}
},
"required": [
"search",
"organization_id",
"location_id"
],
"additionalProperties": false
},
"pcp_only": {
"type": "boolean"
},
"accepts_medicare_assignment": {
"type": "boolean"
},
"show_offices": {
"type": "boolean"
},
"office_option": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
}
},
"required": [
"zip"
],
"additionalProperties": false
},
"option_id": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
}
},
"required": [
"search",
"option_id"
],
"additionalProperties": false
},
{
"type": "string",
"minLength": 1,
"maxLength": 100
},
{
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 2,
"maxLength": 60
},
"npi": {
"type": "string",
"maxLength": 20
},
"office_zip": {
"type": "string",
"pattern": "^\\d{5}$"
},
"county": {
"type": "string",
"minLength": 1,
"maxLength": 60
},
"state": {
"type": "string",
"pattern": "^[A-Z]{2}$"
},
"specialty": {
"type": "string",
"minLength": 2,
"maxLength": 100
},
"facility": {
"type": "string",
"minLength": 2,
"maxLength": 120
}
},
"additionalProperties": false
}
]
},
"description": "Up to ten doctor names with office locations or confirmed find_medicare_doctors references. [] means intentionally omitted."
},
"priorities": {
"maxItems": 16,
"type": "array",
"items": {
"type": "string",
"enum": [
"keep-doctors",
"low-premium",
"low-oop",
"drug-coverage",
"dental",
"vision",
"hearing",
"fitness",
"otc",
"transportation",
"telehealth",
"meal-delivery",
"acupuncture",
"worldwide-coverage",
"pharmacy-network",
"benefits"
]
},
"description": "Only the person’s stated supported MA priorities; do not infer preferences from demographics."
},
"offer_rx": {
"description": "False requests MA-only plans without Part D; true or omitted requests plans with Part D. Never infer false from missing medications.",
"type": "boolean"
},
"provider_network_policy": {
"description": "Defaults to strict_all_in_network when doctors are supplied, otherwise score. An explicit score policy retains the broader API ranking pool. strict_all_in_network requires positive evidence for every selected doctor, including directory-likely matches; it does not certify exact-office participation.",
"type": "string",
"enum": [
"score",
"strict_all_in_network"
]
},
"plan_types": {
"description": "Defaults to the website HMO/PPO pool. Use an explicitly requested network-type subset; this is separate from drug coverage and SNP eligibility.",
"minItems": 1,
"maxItems": 3,
"type": "array",
"items": {
"type": "string",
"enum": [
"HMO",
"PPO",
"PFFS"
]
}
},
"medicaid": {
"type": "string",
"enum": [
"yes",
"no",
"unsure"
],
"description": "User-reported Medicaid enrollment: yes, no or unsure. Not an eligibility verification."
},
"medicaid_cost_sharing": {
"type": "string",
"enum": [
"yes",
"no",
"unsure"
],
"description": "User-reported Medicaid help with Medicare cost sharing: yes, no or unsure."
},
"full_medicaid_benefits": {
"type": "string",
"enum": [
"yes",
"no",
"unsure"
],
"description": "User-reported full Medicaid benefits: yes, no or unsure. Do not infer eligibility."
},
"current_plan": {
"type": "object",
"properties": {
"query": {
"type": "string",
"minLength": 2,
"maxLength": 150
},
"option_id": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
}
},
"required": [
"query",
"option_id"
],
"additionalProperties": false,
"description": "Confirmed current MA plan reference for a requested ranking comparison; retain its location/year context."
},
"current_plan_name": {
"type": "string",
"minLength": 2,
"maxLength": 150,
"description": "Familiar current MA plan name/insurer; ambiguous versions require confirmation."
},
"csnp_condition_keys": {
"maxItems": 7,
"type": "array",
"items": {
"type": "string",
"enum": [
"diabetes",
"heart",
"copd",
"esrd",
"dementia",
"hiv",
"mental_health"
]
},
"description": "Only supported condition categories explicitly reported for this ranking; not a diagnosis or eligibility decision."
},
"vision_profile": {
"type": "object",
"properties": {
"intent": {
"type": "string",
"enum": [
"coverage",
"priced_need"
]
},
"wears": {
"type": "string",
"enum": [
"glasses",
"contacts",
"both",
"none"
]
},
"replacement_cadence": {
"type": "string",
"enum": [
"yearly",
"every_2_3_years",
"rarely"
]
},
"lens_type": {
"type": "string",
"enum": [
"single_vision",
"progressive",
"unknown"
]
}
},
"additionalProperties": false,
"description": "User-reported supported vision needs for the MA ranking; omit unknown fields."
},
"benefit_choices": {
"type": "object",
"properties": {
"dental": {
"type": "object",
"properties": {
"intent": {
"type": "string",
"enum": [
"coverage",
"priced_need"
]
},
"annual_spend": {
"type": "string",
"enum": [
"low",
"medium",
"high",
"very_high",
"not_sure"
]
},
"usage": {
"type": "string",
"enum": [
"preventive",
"comprehensive",
"both",
"unknown"
]
},
"situation": {
"type": "string",
"enum": [
"own_teeth",
"missing_teeth",
"dentures",
"not_sure"
]
},
"procedure": {
"type": "string",
"enum": [
"crown",
"root_canal",
"denture",
"perio",
"extraction",
"not_sure"
]
}
},
"additionalProperties": false
},
"otc": {
"type": "object",
"properties": {
"intent": {
"type": "string",
"enum": [
"coverage",
"priced_need"
]
},
"monthly_spend": {
"type": "string",
"enum": [
"low",
"medium",
"high",
"not_sure"
]
}
},
"additionalProperties": false
},
"hearing": {
"type": "object",
"properties": {
"intent": {
"type": "string",
"enum": [
"coverage",
"priced_need"
]
},
"device_tier": {
"type": "string",
"enum": [
"basic",
"mid",
"premium",
"not_sure"
]
},
"replacement_timing": {
"type": "string",
"enum": [
"soon",
"later",
"eventually",
"none",
"no",
"not_sure"
]
},
"usage": {
"type": "string",
"enum": [
"current_wearer",
"prospective",
"exam_only",
"not_sure"
]
}
},
"additionalProperties": false
}
},
"additionalProperties": false,
"description": "User-reported supported dental, OTC and hearing needs for the MA ranking; never invent spending or usage."
}
},
"additionalProperties": false
}
Example request
Minimal synthetic request after initialization. A missing-input clarification is a valid result; do not invent personal facts to complete it. For content retrieval, replace the illustrative fixture ID with an ID returned by search.
{
"jsonrpc": "2.0",
"id": 3,
"method": "tools/call",
"params": {
"name": "rank_medicare_advantage_plans",
"arguments": {}
}
}
Connection
POST JSON-RPC to https://tools.thepocketprotector.com/mcp with method tools/call, name rank_medicare_advantage_plans, and arguments matching the schema above. Call tools/list to verify deployed availability.
Results and errors
Read both content and structuredContent. Follow returned clarification or continuation steps. Preserve source attribution, dates, uncertainty and scope. isError: true means the lookup did not complete. HTTP 429 requires waiting for Retry-After; never repeatedly retry an unavailable lookup.
Tool annotations
{
"title": "Rank Medicare Advantage plans for a person",
"readOnlyHint": true,
"openWorldHint": true,
"destructiveHint": false
}
Authentication: public, no account or API key required. Public tools perform no enrollment or account writes.
Read this page as Markdown