Compare ACA health plans by real yearly cost, with tax credits, doctors and drugs, from CMS data.
Scored across 5 tools
Each tool targets a distinct resource and action: search_* tools retrieve IDs, get_plan returns full plan details, and check_coverage performs the cross-resource lookup. The descriptions explicitly clarify the dependency chain (use search_drugs/search_doctors first), leaving no overlap.
All five tools follow a clean verb_noun snake_case pattern: check_coverage, get_plan, search_doctors, search_drugs, search_plans. Verb choice is also semantically meaningful (search for lookup, get for retrieval by ID, check for validation).
Five tools is well-scoped for a health-plan lookup domain—two lookup tools, two retrieval/validation tools, and one detail tool—each earning its place with no redundancy.
The surface covers the core workflow: find plans with cost estimates, drill into plan details, look up drugs/doctors, and verify coverage. Minor gaps exist (e.g., no direct plan comparison or provider-network breadth listing), but agents can work around these via the existing tools.
Check whether plans cover specific medications (by RxCUI) and have specific doctors in network (by NPI). Use search_drugs and search_doctors first to get the ids.
| Name | Required | Description | Default |
|---|---|---|---|
| npis | No | ||
| rxcuis | No | ||
| plan_ids | Yes | plan_id values from search_plans |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds the id-prerequisite workflow, but with no output schema it never says what a coverage result looks like (boolean per plan? per drug?) or how partial/no-coverage cases are reported.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero filler, with the core purpose and the prerequisite ordering both front-loaded. Nothing restates the name or title.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Safety and prerequisite context are covered, but for a batch lookup tool with no output schema the response shape and per-plan result semantics are unexplained. An agent knows how to call it but not how to interpret the return.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 33% (only plan_ids is documented), but the description compensates by mapping medications→rxcuis (RxCUI identifiers) and doctors→npis (NPI identifiers) and stating where those ids come from. Array caps and defaults are already in the schema, so the remaining gap is minor.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (check) and two concrete resources (drug coverage by RxCUI, doctor network status by NPI) scoped to plans. This is clearly distinct from the sibling search_* and get_plan tools, which retrieve entities rather than evaluate coverage against a plan.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells the agent to call search_drugs and search_doctors first to obtain the ids, which is the key prerequisite. It does not cover when to prefer get_plan or what to do when npis/rxcuis are omitted, so it stops short of full when/when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Full details for one plan: deductible, out-of-pocket max, copays, drug tiers, key benefits, and what the person would pay in the plan's official coverage examples (having a baby, managing diabetes, a simple fracture).
| Name | Required | Description | Default |
|---|---|---|---|
| plan_id | Yes | plan_id from search_plans, e.g. 16842FL0120001-04 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered without the description. The description adds real value by disclosing what content comes back, including official coverage scenarios, but says nothing about invalid/unknown plan_id behavior or the size/shape of the response.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence that leads with the scope ('Full details for one plan') and then enumerates contents. No filler, no restatement of the title.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description carries the burden of describing return content, and it does so concretely. Minor gaps remain around error/empty handling and when to prefer check_coverage, but for a single-parameter read tool it is close to complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only one parameter exists and the schema documents it fully at 100% coverage (including an example id and its provenance from search_plans). The description adds no further meaning about the identifier, so the documented baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names the resource (one plan) and enumerates the concrete data returned: deductible, out-of-pocket max, copays, drug tiers, benefits, and coverage examples. This clearly separates it from a list/lookup sibling like search_plans, though no sibling is named explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied: fetch full detail for a single plan identified by plan_id (the schema itself points at search_plans as the source of that id). There is no explicit when-to-use vs. check_coverage guidance, which matters since check_coverage is a sibling that could plausibly overlap on cost information.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Look up a doctor near a ZIP code to get their NPI, needed by check_coverage.
| Name | Required | Description | Default |
|---|---|---|---|
| zip | Yes | 5-digit ZIP near the doctor | |
| query | Yes | Doctor's name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already establish that this is a read-only, idempotent, non-destructive, closed-world lookup. The description adds meaningful context beyond the annotations by stating that the result includes an NPI and that this NPI is needed by check_coverage, which helps the agent understand the tool's role in a multi-step workflow.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single efficient sentence. It front-loads the lookup action and then adds the downstream dependency on check_coverage without any filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter read-only lookup with full schema coverage and informative annotations, the description supplies enough context to invoke the tool correctly. It identifies the key output, NPI, though it does not describe how multiple doctor matches are returned, which is a minor gap for a search tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the schema already documents both required parameters: zip as a 5-digit ZIP near the doctor and query as the doctor's name. The description reinforces the ZIP-based location lookup but does not add syntax or matching semantics beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: "Look up a doctor near a ZIP code," and states the useful output, the doctor's NPI. It also distinguishes this lookup from the downstream sibling tool check_coverage by saying the NPI is "needed by check_coverage."
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a clear usage context by tying the tool to check_coverage: use it to obtain an NPI needed by that tool. It does not provide explicit when-not guidance or name other alternatives, but the intended workflow is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Look up a medication by name (generic or brand) to get its RxCUI, needed by check_coverage. Pick the entry matching the strength and form the person takes.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Drug name, e.g. "metformin" or "Ozempic" |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds value beyond that: it discloses that the call can return multiple candidate entries requiring disambiguation by strength/form, and that the RxCUI it yields is consumed by check_coverage. It stops short of describing empty/no-match behavior or the full result shape.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero filler, and the front-loaded sentence carries the purpose plus the downstream dependency. The second sentence earns its place by telling the agent how to choose among results.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter read tool with no output schema, the description covers purpose, return value (RxCUI), and the ambiguity an agent must resolve. Minor gap: no hint about what a no-match or overly broad query returns.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a worked example ("metformin" or "Ozempic"), so the baseline is 3. The description reinforces that either generic or brand names are accepted, which is a marginal addition over a schema whose examples already demonstrate exactly that; the minLength of 3 is not mentioned.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ("look up a medication by name"), names both accepted name types (generic or brand), and states the output that matters (RxCUI). It also distinguishes itself from the sibling by explaining the downstream hand-off to check_coverage, so an agent knows this is the entry point of a two-step flow.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Clear context: use this before check_coverage, and "Pick the entry matching the strength and form the person takes" tells the agent how to resolve multiple hits. No explicit when-not or excluded case, but none of the siblings (check_coverage, get_plan, search_doctors, search_plans) are competing drug searches, so no alternative needs naming.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find ACA Marketplace plans for a household, with the premium tax credit applied and plans ranked by estimated total yearly cost. Also reports the monthly tax credit, cost-sharing reduction (extra-savings Silver) eligibility and likely Medicaid eligibility.
| Name | Required | Description | Default |
|---|---|---|---|
| zip | Yes | 5-digit US ZIP code | |
| ages | Yes | Age of each person who needs coverage | |
| limit | No | ||
| metal | No | Only this metal tier | |
| tobacco | No | Tobacco use per person, same order as ages | |
| big_event | No | Anything big planned this year | none |
| annual_income | No | Expected household income (MAGI) for the coverage year, in dollars. Needed for the tax credit. | |
| expected_care | No | checkups = preventive only; some = a few visits; ongoing = a chronic condition or regular meds | some |
| household_size | No | People in the tax household, including those not enrolling. Defaults to the number of ages. | |
| immigration_status | No | Per person, same order as ages. citizen = U.S. citizen or national; eligible-alien = green card holder, Cuban/Haitian entrant or COFA migrant; lawfully-present = work or student visa, asylum, refugee, TPS, pending green card; not-lawfully-present = no lawful status, including DACA. From 2027 only citizens and eligible aliens get the tax credit. Defaults to citizen. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description earns credit for going beyond them: it discloses that results are ranked by estimated total yearly cost, that the tax credit is already applied, and that it also returns monthly tax credit, CSR/extra-savings eligibility and likely Medicaid eligibility. It does not say what happens when income is omitted or how ranking degrades without it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero filler, with the core capability and the ranking/subsidy behavior front-loaded. Nothing is repeated from the schema or annotations.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 10-parameter read tool with no output schema, the description covers enough: what goes in conceptually and what comes back (ranked plans plus credit, CSR and Medicaid determinations). It stops short of describing the shape of an individual plan result, which leaves the agent guessing at return fields.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 90%, so parameters are already well documented and the baseline is 3. The description adds only thematic framing (household, tax credit) and no formats, defaults, or interaction rules beyond what the schema states — including the notable interaction between annual_income and the credit it advertises.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ("Find ACA Marketplace plans for a household") plus two distinguishing behaviors: premium tax credit applied and ranking by estimated total yearly cost. It is clear enough to separate from get_plan (single plan) by implication, but it never names the sibling or explicitly rules out the adjacent tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the framing — you supply a household, income and ages and get ranked plans with subsidy math. There is no explicit when-to-use/when-not guidance, no mention of prerequisites (e.g. annual_income required for a meaningful tax credit), and no routing to check_coverage for a pure eligibility question.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
search_plans1 field changedInput schema / properties / immigration_statusAdded value: +{
+ "description": "Per person, same order as ages. citizen = U.S. citizen or national; eligible-alien = green card holder, Cuban/Haitian entrant or COFA migrant; lawfully-present = work or student visa, asylum, refugee, TPS, pending green card; not-lawfully-present = no lawful status, including DACA. From 2027 only citizens and eligible aliens get the tax credit. Defaults to citizen.",
+ "items": {
+ "enum": [
+ "citizen",
+ "eligible-alien",
+ "lawfully-present",
+ "not-lawfully-present"
+ ],
+ "type": "string"
+ },
+ "type": "array"
+}check_coverageget_plansearch_doctorssearch_drugssearch_plansSearch US hospital prices, compare costs, and find insurance-negotiated rates.
Real annual cost for every Texas electricity plan, from each retailer's Electricity Facts Label.
What US health plans pay for care: negotiated rates by plan, provider and billing code, near a ZIP.
Calculate Actuarial Value (AV) & metal tier of a health insurance plan from any document.
Add one secure layer between your agents and this server.
