Debt Payoff vs. Invest
compare_payoff_vs_investCalculation, not advice. Verify with a professional before acting. Compares the guaranteed return of debt payoff against expected investment returns over a time horizon.
Accounts for post-payoff investing, optionally taxes the investment gain once at the horizon (this needs filing_status and annual_gross_income), and finds the break-even investment return rate. Works for credit cards, auto loans, student loans, personal loans, and mortgages.
Pick this when the alternative to investing is paying down an existing debt balance; pick calculate_opportunity_cost when there is no debt in the picture and the alternative is simply forgoing recurring spending to invest it instead.
The response echoes debt_type (canonical lowercase enum the projection was computed for) and debt_type_label (display-ready string, e.g. 'student loan') at the top level.
HEAVY tool: use output='summary' (default) for the headline comparison or output='inline' for the full month-by-month schedule.
When no projection can be computed (very long horizon, very high rate, or very large amounts), the response is { meta, not_representable: { code, explanation } } instead.
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": {
"debt_type": "<debt_type>",
"debt_balance": "<debt_balance>",
"debt_apr_pct": "<debt_apr_pct>",
"extra_monthly": "<extra_monthly>"
},
"name": "compare_payoff_vs_invest"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| output | No | Valid values: 'summary' (default), 'inline'. 'summary' returns headline comparison scalars, milestones, and citations with monthly_schedule stripped. 'inline' returns the full payload including the month-by-month monthly_schedule[]. | |
| tax_year | No | Tax year, 2025 or 2026. Year 1 of the time horizon, so the assumed sale of the investments falls in tax year tax_year plus the horizon in years, rounded up, minus 1. Optional; defaults to 2026 when omitted. | |
| debt_type | Yes | Debt type: 'credit_card', 'auto', 'student', 'personal', or 'mortgage'. REQUIRED, no default. | |
| chart_title | No | Override for the chart title. Must not contain em-dashes or en-dashes. Max 120 characters. Optional. | |
| debt_apr_pct | Yes | Debt annual percentage rate, e.g. 6.5 not 0.065. Decimal from 0 to 100. REQUIRED, no default. | |
| debt_balance | Yes | Current debt balance. Decimal, greater than 0. REQUIRED, no default. | |
| extra_monthly | Yes | Extra monthly amount available for debt payoff or investing, the amount in question. Decimal, greater than 0. REQUIRED, no default. | |
| filing_status | No | Tax filing status: 'single', 'married', or 'head_of_household'. Optional; matched case-insensitively. Required, with annual_gross_income, for the after-tax comparison. | |
| full_schedule | No | Whether to return the full month-by-month schedule. Optional; defaults to false (compact schedule) when omitted. | |
| minimum_payment | No | Minimum monthly payment. Decimal, at least 0. Optional; auto-calculated for amortizing loans when omitted or 0. | |
| tax_bracket_pct | No | Marginal tax bracket, e.g. 22 not 0.22. Decimal from 0 to 100. Optional; used only for the mortgage or student loan interest deduction warning. It is never applied to investment gains. | |
| time_horizon_years | No | Projection horizon. Integer, greater than 0. Optional; defaults to the greater of the payoff horizon or 10 years when omitted. | |
| annual_gross_income | No | Annual gross income in dollars, used as adjusted gross income for the tax on investment gains at the horizon. Optional; with filing_status it enables the after-tax comparison. Held at this amount in the year of the assumed investment sale. Must be zero or more and no more than $1,000,000,000. | |
| investment_return_pct | No | Expected investment return, an EFFECTIVE ANNUAL rate; the monthly compounding step is (1+pct/100)^(1/12)-1. Decimal from 0 to 30. Optional; defaults to the cited long-run S&P 500 nominal return, about 10%, when omitted. | |
| term_months_remaining | No | Months remaining on the debt. Integer, greater than 0. Required for non-credit-card debt types; optional for credit_card. | |
| investment_tax_advantaged | No | Whether the investments sit in a tax-advantaged account, e.g. 401k or IRA. Optional; defaults to false. When true, no after-tax comparison is computed: withdrawal tax depends on the account type, which this tool does not model. | |
| investment_volatility_pct | No | Investment volatility. Decimal. Optional; adds a volatility risk note when supplied. |