ACA Premium Tax Credit Calculator

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantial behavioral context beyond them: the exact statutory tables per year, the 400% FPL cliff for 2026, and the enumerated return values. The warning that models often misapply the 8.5% cap to 2026 is unusually valuable disclosure.

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?

Front-loaded with the core purpose, then year-specific rules, then return values, then a targeted caveat. Dense but every sentence carries decision-relevant information; nothing is padding.

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?

No output schema exists, but the description enumerates the returned fields (FPL percentage, applicable figure, expected contribution, annual/monthly credit, net premium), so an agent knows what to expect. Combined with 100% schema coverage and annotations, nothing material is missing.

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%, so the baseline is 3, but the description adds meaning the schema cannot: the 'year' parameter's behavioral consequences (which table and cap apply) are spelled out. It does not add detail on state FPL variation or premium_period beyond what the schema already documents.

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 ('Calculates the ACA Marketplace premium tax credit (IRC sec. 36B)') and anchors it to a concrete reference implementation ('the way Form 8962 does'). This clearly separates it from siblings like get_federal_poverty_level (an input) and get_aptc_repayment_cap (a different computation).

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?

Gives strong conditional guidance on which rule set applies by year (2025 enhanced table vs 2026 Rev. Proc. 2025-25 table, no credit above 400% FPL in 2026). It does not explicitly name when to prefer a sibling tool, but the year-based routing is clear context for invocation.

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

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

Annotations already mark this as read-only, idempotent, non-destructive, and closed-world, and the description adds substantial behavioral detail: exactly which cliff outputs are produced and how results expand when household_income is supplied. It also discloses the comparison against expired 2021-2025 enhanced rules and the MAGI-reduction calculation.

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 front-loaded with the primary cliff output and efficiently covers optional behavior. It is a single dense sentence, so slightly heavy, but every clause adds useful output or comparison information.

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 explains the return values in enough detail for correct invocation and interpretation. It also covers the optional household_income branch and the policy comparison context, which are the key behavioral complexities for this calculator.

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%, so all five parameters are already well documented in the schema. The description adds the conditional meaning of household_income triggering extra outputs, but otherwise relies on the schema for parameter semantics; baseline 3 is appropriate.

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 calculation and scope: the dollar effect of the 400% FPL subsidy cliff for 2026, including cliff income, credit at 400%, credit at $1 more, and loss. This is clearly distinguishable from generic premium tax credit or poverty-level siblings, even without naming them.

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 makes clear when the tool is useful: analyzing the returned subsidy cliff and, optionally, comparing 2026 rules with expired enhanced rules. It does not explicitly name when to choose a sibling like calculate_premium_tax_credit instead, but the cliff-specific framing gives strong usage context.

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

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

Annotations already cover the read-only, idempotent, closed-world profile, so the bar is lower; the description still adds real behavioral context by disclosing that output changes materially by tax year, that the cap is repealed for 2026+, and that pre-2026 training data will mislead. It stops short of saying how the parameters interact to select a bracket, but it goes well beyond restating annotations.

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?

Front-loaded with the core answer, then the year-specific detail, then the stale-model warning. The parenthetical dollar tables are dense but each figure earns its place as a return-value preview; a slightly tighter phrasing would help.

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 and 6 parameters, the description carries the return-value burden itself and does so fully: it gives concrete caps for 2025 by FPL band and states the 2026+ outcome. Nothing essential to calling or interpreting the result is missing.

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%, so the baseline is 3; the description still adds meaning by tying filing_status and household_income/household_size to the Table 5 columns and FPL brackets, and by flagging the 400% FPL boundary behavior. It does not explain how state-specific poverty lines alter the result beyond what the schema already says.

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 precise verb and resource: returns the cap on repaying excess APTC. It is immediately distinguishable from siblings (credit calculation, subsidy cliff, poverty level) because it names the exact quantity and the tax-time repayment context.

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 makes clear this is the tool for repayment-cap questions and explains the year split (2025 caps vs 2026+ no cap), but it never explicitly routes to or away from siblings like calculate_premium_tax_credit or get_federal_poverty_level, leaving the agent to infer the boundary.

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

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

Annotations already declare readOnly, idempotent, closed-world, so the safety profile is covered. The description adds real context beyond that: provenance ('Copied from the Federal Register notices, not model memory') and the lag rule tying coverage year Y to year Y-1 guidelines, which is the kind of correctness detail an agent cannot get from annotations.

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?

Front-loaded with the resource and scope, then the year rule, then the provenance note. The parenthetical dollar figures are somewhat heavy but serve as a concrete sanity anchor; nothing is genuinely wasted.

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?

There is no output schema, and the description compensates by enumerating the returned thresholds (100% through 400%) and the FPL basis. The only real gap is the unexplained optional household_income input, which matters if the tool also derives an income percentage.

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%, so all four parameters are documented and the baseline is 3. The description does add the Y-1 guideline-year mapping, but it never mentions the optional household_income parameter or what it is for, leaving that input's role to the schema alone.

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 ('Returns the federal poverty line') plus the exact scope (coverage year, household size, state) and the derived thresholds returned. An agent can distinguish this pure lookup from the sibling calculation tools (calculate_premium_tax_credit, check_subsidy_cliff) without opening a schema.

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?

Gives clear operating context: the coverage-year-to-guideline-year rule and the AK/HI/rest-of-country split tell the agent how to frame a call. It never explicitly says when to use this versus the sibling tools that consume an FPL, so the routing is inferred rather than stated.

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