Skip to main content
Glama

Senaro Personal Finance

Debt Payoff vs. Invest

compare_payoff_vs_invest
Read-onlyIdempotent

Calculation, 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

NameRequiredDescriptionDefault
outputNoValid 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_yearNoTax 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_typeYesDebt type: 'credit_card', 'auto', 'student', 'personal', or 'mortgage'. REQUIRED, no default.
chart_titleNoOverride for the chart title. Must not contain em-dashes or en-dashes. Max 120 characters. Optional.
debt_apr_pctYesDebt annual percentage rate, e.g. 6.5 not 0.065. Decimal from 0 to 100. REQUIRED, no default.
debt_balanceYesCurrent debt balance. Decimal, greater than 0. REQUIRED, no default.
extra_monthlyYesExtra monthly amount available for debt payoff or investing, the amount in question. Decimal, greater than 0. REQUIRED, no default.
filing_statusNoTax filing status: 'single', 'married', or 'head_of_household'. Optional; matched case-insensitively. Required, with annual_gross_income, for the after-tax comparison.
full_scheduleNoWhether to return the full month-by-month schedule. Optional; defaults to false (compact schedule) when omitted.
minimum_paymentNoMinimum monthly payment. Decimal, at least 0. Optional; auto-calculated for amortizing loans when omitted or 0.
tax_bracket_pctNoMarginal 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_yearsNoProjection horizon. Integer, greater than 0. Optional; defaults to the greater of the payoff horizon or 10 years when omitted.
annual_gross_incomeNoAnnual 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_pctNoExpected 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_remainingNoMonths remaining on the debt. Integer, greater than 0. Required for non-credit-card debt types; optional for credit_card.
investment_tax_advantagedNoWhether 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_pctNoInvestment volatility. Decimal. Optional; adds a volatility risk note when supplied.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed5 schema fields changed
    • addedInput schema / properties / annual_gross_income
      Added value: +{
      +  "default": null,
      +  "description": "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.",
      +  "maximum": 1000000000,
      +  "minimum": 0,
      +  "type": [
      +    "number",
      +    "null"
      +  ]
      +}
    • addedInput schema / properties / filing_status
      Added value: +{
      +  "default": null,
      +  "description": "Tax filing status: 'single', 'married', or 'head_of_household'. Optional; matched case-insensitively. Required, with annual_gross_income, for the after-tax comparison.",
      +  "enum": [
      +    "single",
      +    "married",
      +    "head_of_household",
      +    null
      +  ],
      +  "type": [
      +    "string",
      +    "null"
      +  ]
      +}
    • changedInput schema / properties / investment_tax_advantaged / description
      Previous value: -"Whether the investment is tax-advantaged, e.g. 401k or IRA. Optional; defaults to false when omitted."New value: +"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."
    • changedInput schema / properties / tax_bracket_pct / description
      Previous value: -"Tax bracket, e.g. 22 not 0.22. Decimal from 0 to 100. Optional; enables an after-tax comparison when supplied."New value: +"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."
    • addedInput schema / properties / tax_year
      Added value: +{
      +  "default": null,
      +  "description": "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.",
      +  "maximum": 2026,
      +  "minimum": 2025,
      +  "type": [
      +    "integer",
      +    "null"
      +  ]
      +}
  2. Added

TDQS

A4.8/5.0
Behavior5/5

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

Goes well past the readOnly/idempotent annotations by disclosing the tool is a HEAVY computation with a summary/inline output trade-off, the exact fallback shape when no projection is possible ({ meta, not_representable }), that tax on gains is applied only once at the horizon and requires filing_status plus annual_gross_income, and that the response echoes debt_type and debt_type_label. It also sets a non-advice expectation, which matters for a financial comparison tool.

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?

Front-loaded with the core comparison and the sibling disambiguation before the mechanics; every paragraph carries distinct information (disclaimer, tax mechanics, routing rule, response shape, output modes, failure mode). Slightly long, but justified by 17 parameters and no output schema.

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 compensates by describing the return payload (echoed debt_type/debt_type_label), the heavy-tool output modes, and the not_representable error shape. Combined with full schema coverage, an agent has everything needed to call it and interpret the result.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is already 100%, so the baseline is 3, but the description adds cross-parameter meaning the schema does not: filing_status and annual_gross_income must be supplied together to unlock the after-tax comparison, and output='summary' is the default vs 'inline' for the full schedule. It does not elaborate on less obvious params like tax_bracket_pct's deduction-only role beyond what the schema says.

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?

States a specific verb and resource ('Compares the guaranteed return of debt payoff against expected investment returns over a time horizon') and explicitly names the sibling it must be distinguished from, calculate_opportunity_cost. An agent can route correctly without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit selection rule ('Pick this when the alternative to investing is paying down an existing debt balance') and the inverse condition for the alternative tool ('when there is no debt in the picture and the alternative is simply forgoing recurring spending'). Both when-to-use and when-not-to-use are covered.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources