Calculation, not advice. Verify with a professional before acting. Compare avalanche and snowball payoff strategies side-by-side. Pick this to compare avalanche against snowball ordering on the same set of cards; pick `calculate_cc_payoff` once a strategy is chosen and the need is a single payoff timeline with windfalls or fixed payments.
Returns months, total interest, payoff order, savings, total_balance, weighted_average_apr_pct, monthly_interest_now, and cost_breakdown array. When an arm is not projected to reach a zero balance, the savings.* fields for that arm carry status: "none" with value: null and an explanation, not a number.
savings.strategies_convergence separately discloses the avalanche/snowball arms' own convergence:
- "both_converge" (ordinary case),
- "worst_never_amortizes" (the losing strategy arm does not reach a zero balance in this projection but the winning arm does, so savings.best_vs_worst_months/interest carry status: "none"), or
- "neither_converges" (the WINNING strategy arm does not reach a zero balance either, so no dollar or month figure derived from either strategy arm is reportable).
lower_total_interest_strategy names whichever of avalanche or snowball has the lower total interest, or "tie" when the two arms' total interest and months are exactly equal. A "tie" can co-occur with savings.strategies_convergence="neither_converges". It reports only that comparison, never that either arm pays off.
chart_hints.title and chart_hints.annotations[0].label report a dollar figure only when the comparison they describe is Defined, and otherwise state plainly that no figure is reportable, matching the "none" status on the corresponding savings.* field. Unlike chart_hints, summary and savings.savings_summary hedge rather than decline a figure, and the two always carry the same sentence as each other: when the compared arm does not converge (savings.baseline_never_amortizes=true, or savings.strategies_convergence=worst_never_amortizes) but the winning side still does, both report a figure hedged as a floor, "saves at least $X and N months ..., so the true saving could be higher than reported". Only when strategies_convergence=neither_converges do summary and savings.savings_summary also state that no figure is reportable. No savings.* sentinel object carries a hedged floor in its value key; the only place a floor ever appears is the savings.savings_summary sentence.
This tool carries no domain-shaped warnings[].type entries (unlike calculate_cc_payoff); warnings[] here is exclusively validation disclosures emitted as warnings[].code, e.g. MINIMUM_PAYMENT_NOT_BINDING_IN_BASELINE plus the general portfolio findings (MANY_CARDS, HIGH_CARD_BALANCE, etc.) shared with every card-based tool.
The response includes `chart_hints` with rendering directives any client can use.
This tool takes no strategy, fixed_payments, full_schedule or per_segment parameter: it always compares avalanche against snowball over the full schedule, so all four are rejected as unknown_parameter.
View input schema
{
"type": "object",
"properties": {
"cards": {
"description": "Credit cards to compare, 1 to 20, the same shape calculate_cc_payoff takes. Required: omitting the field answers contract_error MISSING_REQUIRED_FIELD, while an explicit JSON null answers parse_error (\"cards is required and must be an array.\"); the two are not the same rejection. Every card may carry segments[]. Max 100 segments total across all cards in the request. Per-card, per-type caps: 1 purchase, 1 cash_advance, 5 balance_transfer, 1 promotional, 10 installment_plan.",
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"description": "Card label, e.g. 'Chase Sapphire', 120 characters or fewer. Optional; a card without a name is auto-numbered ('Card 1', 'Card 2', and so on). Echoed into per-card results and warning text. A name over the cap is replaced in error field paths by a key built from its zero-based card index, written as '#0 (name over cap)', '#1 (name over cap)' and so on.",
"type": [
"string",
"null"
]
},
"purchase_balance": {
"description": "Purchase balance in dollars, $0 to $1,000,000,000. Required unless segments[] carries at least one segment: an omitted purchase_balance would silently report a $0, 0-month payoff. Supplying a POSITIVE value alongside a non-empty segments[] is rejected, since the two would be competing sources for the same balance. An explicit 0 is accepted.",
"type": [
"number",
"null"
]
},
"purchase_apr_pct": {
"description": "Purchase APR as a percentage, 0 to 100, e.g. 24.99 not 0.2499. Required when purchase_balance is greater than 0: an omitted APR would silently compute $0 interest.",
"type": [
"number",
"null"
]
},
"cash_advance_balance": {
"description": "Cash advance balance in dollars, $0 to $1,000,000,000. Optional; defaults to 0 when omitted. A POSITIVE value alongside a non-empty segments[] is rejected, the same way purchase_balance is. An explicit 0 is accepted.",
"type": [
"number",
"null"
]
},
"cash_advance_apr_pct": {
"description": "Cash advance APR as a percentage, greater than 0 and up to 100. Required when cash_advance_balance is greater than 0. These flat fields have no promo input, so 0 is rejected: nothing would say when a 0% rate ends. For a promotional cash advance, such as a 0% direct-deposit or check offer, use segments[] with a cash_advance segment carrying promo_expires_month and revert_apr_pct.",
"type": [
"number",
"null"
]
},
"minimum_payment": {
"description": "Minimum payment in dollars, $0 to $1,000,000,000 (optional, omit or set 0 to auto-calculate). Where it binds, the card is locked at max(minimum_payment, that card's issuer minimum computed at month 1), and that locked amount is paid every month. On calculate_cc_payoff it binds ONLY when fixed_payments = true; on the DEFAULT path (fixed_payments = false) it is NOT used, because the plan recomputes each card's issuer minimum from its current balance every month, and the response discloses that as MINIMUM_PAYMENT_NOT_BINDING. On compare_payoff_strategies there is no fixed_payments parameter and supplying one is rejected: the avalanche and snowball arms ALWAYS run locked, so the value binds in both arms wherever it is higher than that card's month-1 issuer minimum, while the minimum-payments-only baseline always recomputes and ignores it, disclosed as MINIMUM_PAYMENT_NOT_BINDING_IN_BASELINE.",
"type": [
"number",
"null"
]
},
"annual_fee": {
"description": "Annual fee in dollars, $0 to $1,000,000,000. Optional; defaults to 0. Charged at month 1 and every twelfth month after, while the card carries a balance.",
"type": [
"number",
"null"
]
},
"plan_fees_monthly": {
"description": "Recurring monthly card fee in dollars, $0 to $1,000,000,000, e.g. a pay-over-time plan fee. Optional; defaults to 0. Charged every month while the card carries a balance.",
"type": [
"number",
"null"
]
},
"monthly_spend": {
"description": "Recurring monthly purchase amount charged to this card's purchase balance before interest accrues, $0 to $50,000 per month. Optional; defaults to 0. Use the segment-level monthly_spend instead when supplying segments[].",
"type": [
"number",
"null"
]
},
"stop_spend_month": {
"description": "Month index at which this card's recurring spend stops, 0 or more. Optional; omit to spend for the whole projection.",
"type": [
"integer",
"null"
]
},
"segments": {
"description": "Per-segment breakdown of this card's balances. Optional; when it carries at least one segment it SUPERSEDES purchase_balance and cash_advance_balance, and a POSITIVE value in either of those is rejected. An empty segments[] is treated as absent, so purchase_balance is then required. At most 100 segments across the whole request. Per card, per type: 1 purchase, 1 cash_advance, 5 balance_transfer, 1 promotional, 10 installment_plan. Each item carries its own type, balance, rate and payment priority; see the type field on the item for the per-type field matrix.",
"type": [
"array",
"null"
],
"items": {
"type": "object",
"properties": {
"type": {
"description": "Segment type. REQUIRED on every segment: omitting it is rejected. Per-type field matrix. Every field below is classified for every segment type: REQUIRED (omitting it is rejected), OPTIONAL (accepted either way and read), PAIRED (read when supplied together with its partner as a usable pair: promo_expires_month and revert_apr_pct both supplied beside a supplied apr_pct, each within its value rule; a pair that is not usable is rejected when the segment carries a balance and its apr_pct is omitted, 0 or below, and otherwise is not used, with an INPUT_NOT_USED warning; omitting both, or sending both as null, is accepted), IGNORED (accepted and never read for this type, though a value can still fail the field's own range check), or REJECTED (supplying a disallowed value is an error; the field's own rule below says exactly which values are disallowed). Value rules are stated separately from applicability, because a field can be accepted on a type and still be restricted there. The validators are the authority; this matrix describes them.\n- type: REQUIRED on every type. Values: one of purchase, cash_advance, balance_transfer, promotional, installment_plan.\n- balance: REQUIRED on every type. Values: $0 to $1,000,000,000; above $50,000 returns a HIGH_CARD_BALANCE warning, not an error.\n- apr_pct: REQUIRED on purchase, cash_advance, balance_transfer, promotional; OPTIONAL on installment_plan. Values: 0 to 100 as a percentage, e.g. 24.99 not 0.2499. The REQUIRED classification above applies when balance is greater than 0; a zero-balance segment may omit it. Must be greater than 0 on cash_advance carrying a balance, unless that segment carries a usable promo pair (promo_expires_month and revert_apr_pct). Must equal 0 on installment_plan, where omitting it is the correct shape.\n- revert_apr_pct: REQUIRED on balance_transfer, promotional; PAIRED on cash_advance; IGNORED on purchase; REJECTED on installment_plan. Values: 0 to 100, and at least apr_pct. Rejected on installment_plan with FIELD_NOT_ALLOWED_HERE: an expired plan's residual keeps its existing rate.\n- promo_expires_month: REQUIRED on balance_transfer, promotional; PAIRED on cash_advance; IGNORED on purchase, installment_plan. Values: 1 to 480.\n- monthly_fee: OPTIONAL on installment_plan; REJECTED on purchase, cash_advance, balance_transfer, promotional. Values: $0 or more, and no greater than plan_payment_due, on installment_plan. On every other type a POSITIVE value is rejected with FIELD_NOT_ALLOWED_HERE; 0 and a negative value are accepted and dropped there.\n- plan_payment_due: REQUIRED on installment_plan; REJECTED on purchase, cash_advance, balance_transfer, promotional. Values: greater than $0, at least monthly_fee, and no more than $1,000,000,000, on installment_plan. On every other type a POSITIVE value is rejected with FIELD_NOT_ALLOWED_HERE; 0 and a negative value are accepted and dropped there.\n- remaining_payments: OPTIONAL on installment_plan; IGNORED on purchase, cash_advance, balance_transfer, promotional. Values: 0 or more. 0 means the stated term has ALREADY ended and is valid with any balance. From 1 up, balance must be clearable within the stated term.\n- min_payment_order: OPTIONAL on every type. Values: 1 or more; breaks a tie only between segments sharing both the same current APR and the same installment-plan status.\n- extra_payment_order: OPTIONAL on every type. Values: 0 or more; 0 means skip. Breaks a tie only between segments sharing the exact same current APR.\n- merchant_name: OPTIONAL on installment_plan; IGNORED on purchase, cash_advance, balance_transfer, promotional. Values: 120 characters or fewer.\n- monthly_spend: OPTIONAL on purchase; REJECTED on cash_advance, balance_transfer, promotional, installment_plan. Values: $0 to $50,000 per month. A negative value is rejected as NEGATIVE_BALANCE on every type, purchase included. On every type other than purchase a POSITIVE value is rejected with FIELD_NOT_ALLOWED_HERE; an explicit 0 is accepted.\n- stop_spend_month: OPTIONAL on purchase; IGNORED on cash_advance, balance_transfer, promotional, installment_plan. Values: 0 or more; range checked on every type, read only on purchase.",
"type": "string"
},
"balance": {
"description": "Segment balance in dollars, $0 to $1,000,000,000. REQUIRED on every segment type: an omitted balance would silently report a $0, 0-month payoff, so it is rejected instead. An explicit 0 is valid, for example a paid-off balance_transfer segment kept for schedule continuity.",
"type": "number"
},
"apr_pct": {
"description": "Annual percentage rate for this segment, 0 to 100, e.g. 24.99 not 0.2499. Required when balance is greater than 0 on purchase, cash_advance, balance_transfer and promotional. On cash_advance with a balance it must be supplied and greater than 0, unless the segment also carries a usable promo_expires_month and revert_apr_pct: then it is the promotional rate and may be 0. Must be 0 on installment_plan, which uses monthly_fee instead, so omitting it there is the correct shape.",
"type": [
"number",
"null"
],
"default": null
},
"revert_apr_pct": {
"description": "Rate this segment reverts to once its promo expires, 0 to 100, and at least apr_pct: the post-promo APR the offer disclosed, wherever the offer or the statement prints it. Only when neither prints one for this balance, take the regular rate of this balance's category, not the promo rate. A direct-deposit or check cash advance reverts to the cash-advance APR for those advances, which can differ from the bank cash-advance APR and is not the balance-transfer APR. Required on balance_transfer and promotional. On cash_advance, supply it with promo_expires_month: alone or invalid, the pair is not used and an INPUT_NOT_USED warning says why, except at an apr_pct of 0 with a balance, where the request is rejected. Ignored on purchase. Rejected on installment_plan with FIELD_NOT_ALLOWED_HERE: an expired plan's residual keeps its existing rate rather than repricing.",
"type": [
"number",
"null"
],
"default": null
},
"promo_expires_month": {
"description": "Last month charged at apr_pct, 1 to 480; revert_apr_pct applies from the next month. Month 1 is the first statement cycle after the statement the balance comes from. From a statement, count the closing dates after it, up to and including the last one on or before the promo end date; a cycle the end date splits counts at revert_apr_pct. If no closing date qualifies, the promo ends inside month 1: enter the post-promo rate as both apr_pct and revert_apr_pct, with promo_expires_month 1. Required on balance_transfer and promotional. On cash_advance, supply it with revert_apr_pct, under the rule stated on revert_apr_pct. Ignored on purchase and installment_plan.",
"type": [
"integer",
"null"
],
"default": null
},
"monthly_fee": {
"description": "Fixed fee charged each month while an installment plan's term is active, $0 or more and no greater than plan_payment_due. Optional on installment_plan. On every other type a positive value is rejected with FIELD_NOT_ALLOWED_HERE, while 0 and a negative value are accepted and dropped.",
"type": [
"number",
"null"
],
"default": null
},
"plan_payment_due": {
"description": "Locked monthly payment for an installment plan, principal plus monthly_fee. Required on installment_plan, greater than $0, at least monthly_fee, and no more than $1,000,000,000. On every other type a positive value is rejected with FIELD_NOT_ALLOWED_HERE, while 0 and a negative value are accepted and dropped.",
"type": [
"number",
"null"
],
"default": null
},
"remaining_payments": {
"description": "Payments left in an installment plan's stated term, 0 or more. Optional on installment_plan, ignored on every other type. 0 means the term has ALREADY ended and is valid with any balance, including a positive residual. From 1 up, the balance must be clearable within the stated term and must not be clearable a month early.",
"type": [
"integer",
"null"
],
"default": null
},
"min_payment_order": {
"description": "Minimum-payment tie-break priority, 1 or more. Optional on every type. The minimum first pays any installment_plan's locked plan_payment_due in full, then the lowest-current-APR segment; this value only breaks a tie between segments sharing both the same current APR and the same installment-plan status.",
"type": [
"integer",
"null"
],
"default": null
},
"extra_payment_order": {
"description": "Extra-payment tie-break priority, 0 or more, where 0 means this segment never receives extra payment. Optional on every type, and the default for installment_plan. Only breaks a tie between segments sharing the exact same current APR, since the Credit CARD Act (TILA §164(b), 15 U.S.C. §1666c(b)) / 12 CFR 1026.53(a) always pays the highest-current-APR segment first regardless of this value.",
"type": [
"integer",
"null"
],
"default": null
},
"merchant_name": {
"description": "Label for an installment plan's merchant, 120 characters or fewer. Optional on installment_plan, ignored on every other type.",
"type": [
"string",
"null"
],
"default": null
},
"monthly_spend": {
"description": "Recurring monthly purchase amount posted to this segment before interest accrues, $0 to $50,000 per month. Optional on purchase. A negative value is rejected as NEGATIVE_BALANCE on every type. On every type other than purchase a positive value is rejected with FIELD_NOT_ALLOWED_HERE, since those balances do not accept new purchases; an explicit 0 is accepted.",
"type": [
"number",
"null"
],
"default": null
},
"stop_spend_month": {
"description": "Month index at which recurring spend stops, 0 or more. Read on purchase only, and range checked on every type. Omit to spend for the whole projection.",
"type": [
"integer",
"null"
],
"default": null
}
},
"required": [
"type",
"balance"
]
}
}
}
}
},
"extra_monthly_payment": {
"description": "Extra monthly payment in dollars, $0 to $1,000,000,000, applied on top of the required minimums. Optional; defaults to 0 when omitted.",
"type": [
"number",
"null"
],
"default": null
},
"apply_rate_cap": {
"description": "Whether to cap each card's APR at the regulatory ceiling before simulating. Optional; defaults to false when omitted.",
"type": [
"boolean",
"null"
],
"default": null
},
"output": {
"description": "Valid values: 'summary' (default), 'inline'. summary returns the headline comparison with a data_preview block; inline returns the full payload.",
"type": [
"string",
"null"
],
"enum": [
"summary",
"inline",
null
]
},
"chart_title": {
"description": "Override for the chart title. Optional; must not contain an em dash or en dash. Max 120 characters.",
"type": [
"string",
"null"
],
"default": null,
"maxLength": 120
}
},
"required": [
"cards"
]
}