QuantCalc Retirement Engine

2027 ACA marketplace benchmark, poverty line and the 400% cliff

aca_premium_tax_credit

Read-only

Returns a household's 2027 ACA marketplace position from its state, the ages on the plan, household size and income: the county's benchmark (second-lowest-cost silver) premium from CMS's plan-year-2027 files for the HealthCare.gov states, or a given one; the poverty line that sets 2027 credits (2026 HHS guidelines) and the income as a percentage of it; the 400% cliff income and the headroom below it or the amount over it; and whether the income is below the Medicaid line of an expansion state or below the poverty line. The premium tax credit itself is not figured. Not tax advice.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "coverage_year": "<coverage_year>",
      "state": "<state>",
      "ages": "<ages>",
      "income": "<income>"
    },
    "name": "aca_premium_tax_credit"
  }
}

Input Schema

Name	Required	Description
`ages`	Yes	The ages of the people on the marketplace plan. Ages 21-64 are priced; 65 and over (Medicare) and under 21 are not.
`state`	Yes	Two-letter state of residence, or DC.
`county`	No	The county (name, e.g. Miami-Dade, or 5-digit FIPS code) whose CMS plan-year-2027 benchmark premium is read; published for the HealthCare.gov states. Default: none, stated in the result.
`income`	Yes	The household's modified AGI for the credit: AGI plus tax-exempt interest plus the Social Security not taxed, for the coverage year.
`coverage_year`	Yes	The coverage year: 2027 (the CMS county benchmark, the poverty line, the 400% cliff and the headroom, from published data).
`household_size`	No	Tax family size for the poverty line (the filer, a spouse on a joint return, dependents). Default: the number of ages given, stated in the result.
`benchmark_monthly`	No	The household's own monthly benchmark (second-lowest-cost silver) premium for the people on the plan, from healthcare.gov or the state's marketplace. Default: the county's CMS figure when county is given; stated in the result.

Schema Changelog

Changes observed during successful MCP inspections.

Changed5 schema fields changedNov 10, 2026

changedInput schema / properties / benchmark_monthly / description

Previous value: -"The household's own monthly benchmark (second-lowest-cost silver) premium for the people on the plan, from healthcare.gov or the state's marketplace. Default: 2026, the state-level benchmark at each age; 2027, the county's CMS figure; stated in the result."New value: +"The household's own monthly benchmark (second-lowest-cost silver) premium for the people on the plan, from healthcare.gov or the state's marketplace. Default: the county's CMS figure when county is given; stated in the result."

changedInput schema / properties / county / description

Previous value: -"2027 only: the county (name, e.g. Miami-Dade, or 5-digit FIPS code) whose CMS plan-year-2027 benchmark premium is read; published for the HealthCare.gov states. Default: none, stated in the result."New value: +"The county (name, e.g. Miami-Dade, or 5-digit FIPS code) whose CMS plan-year-2027 benchmark premium is read; published for the HealthCare.gov states. Default: none, stated in the result."

changedInput schema / properties / coverage_year / description

Previous value: -"The coverage year: 2026 (the premium tax credit from QuantCalc's federal tax API, Form 8962; needs a licence) or 2027 (open enrollment now: the CMS county benchmark, the poverty line, the 400% cliff and the headroom from published data, and with a licence the 2027 credit from the API)."New value: +"The coverage year: 2027 (the CMS county benchmark, the poverty line, the 400% cliff and the headroom, from published data)."

changedInput schema / properties / coverage_year / enum

Previous value: -[
-  2026,
-  2027
-]New value: +[
+  2027
+]

removedInput schema / properties / filing_status

Removed value: -{
-  "description": "2026 only: the filing status of the return the credit is claimed on (married filing separately generally gets no credit). Default: single for a household of 1, else married filing jointly, stated in the result.",
-  "enum": [
-    "single",
-    "mfj",
-    "mfs",
-    "hoh"
-  ],
-  "type": "string"
-}

AddedNov 1, 2026

TDQS

A4.4/5.0

Behavior5/5

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

Well beyond the readOnlyHint/openWorldHint annotations, the description discloses the data source and vintage (CMS plan-year-2027 files, 2026 HHS guidelines for the poverty line), the resolution order for overrides ('or a given one'; county default none, benchmark_monthly defaults to the county figure), and that defaults are restated in the result. It also flags a real limitation - the credit is not computed - so an agent knows the return is an input set, not a final tax number.

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

Conciseness4/5

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

The outcome is front-loaded in the first clause and the two trailing sentences ('The premium tax credit itself is not figured. Not tax advice.') earn their place as scope limits. The middle is a single long semicolon-chained enumeration that is dense but ordered to match the return, costing it the top score.

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?

With no output schema, the description carries the burden of describing returns, and it does so explicitly by listing the four result components and the flag conditions. For a 7-parameter, read-only calculator whose schema is fully documented, nothing an agent needs to call it or interpret the response is missing.

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%, so every parameter already carries its own explanation; the description mainly echoes the same fields (state, ages, household size, income). The one genuine addition is the override behavior for county and benchmark_monthly, which the schema treats only as defaults. That is real but marginal value, so baseline 3 applies.

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 opens with a specific verb+resource ('Returns a household's 2027 ACA marketplace position') and then enumerates exactly which outputs are produced: county benchmark silver premium, poverty line and income as a percentage of it, the 400% cliff and headroom, and Medicaid/poverty-line flags. That is enough to separate it from the sibling set of deduction, RMD, IRMAA and projection tools, none of which return marketplace benchmark or cliff data.

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?

It makes the operating context clear (a 2027 HealthCare.gov-state benchmark lookup plus credit-threshold check) and adds a negative boundary: 'The premium tax credit itself is not figured' plus 'Not tax advice', which tells an agent not to route actual credit computation here. What it lacks is an explicit pointer to an alternative when the agent does want the credit amount, and it never states prerequisites such as which states are non-HealthCare.gov and require the caller to supply benchmark_monthly.

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

All QuantCalc Retirement Engine 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.