Debt Consolidation Comparison
compare_debt_consolidationRead-onlyIdempotent
Calculation, not advice. Verify with a professional before acting. Should you consolidate credit card debt with a personal loan? Compares keeping cards vs. consolidation loan vs. optional balance transfer offers (single offer or head-to-head multi-offer comparison via bt_offers[]). Supports partial balance transfers via bt_transfer_limit: transfers only up to that dollar amount (choosing cards by highest APR, highest balance, or manually), then runs a combined simulation of the BT card + remaining original-card balances together, so freed minimum payments are correctly redistributed. Shows total cost, interest saved, monthly payment change, origination fee breakeven, hidden risks (reracking), promo-trap detection per offer, and what-if scenarios. Works with multiple cards including cash advance balances. The response includes chart_hints with rendering directives any client can use. The senaro-charts MCP server renders them locally over stdio only. HEAVY tool: use output='summary' (default) for the headline comparison or output='inline' for the full payload. output='capture' writes the full payload to a file on this server's local disk for the chart-render pipeline; available on the local stdio transport only, and rejected with a structured error on the hosted HTTP transport.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| toolArguments | Yes | JSON object with these parameters: cards (REQUIRED array, max 20): - name: string (optional) - purchase_balance: decimal >= 0 (REQUIRED) - purchase_apr_pct: decimal 0-100 as percentage, e.g. 22.99 (REQUIRED) - cash_advance_balance: decimal >= 0 (optional, default 0) - cash_advance_apr_pct: decimal > 0, <= 100 (required if cash_advance_balance > 0) - minimum_payment: decimal >= 0 (optional, 0 = auto-calculate). Used as the locked floor for the constant keep-cards payment: each card pays max(your minimum, the bank minimum), held constant and rolled forward as cards clear. - segments: NOT SUPPORTED by this tool (rejected with a parse_error if supplied). This tool always reads the flat purchase_balance / cash_advance_balance fields above, never segments[] balances; supply those instead. segments[] input is supported by calculate_cc_payoff and compare_strategies. - monthly_spend / stop_spend_month: NOT SUPPORTED by this tool (rejected with a validation error if supplied). Ongoing spend on cards a consolidation loan or transfer just paid off is not modeled by any arm here; supported by calculate_cc_payoff and compare_strategies. consolidation_loan (REQUIRED object): - annual_rate_pct: decimal 0-36 as percentage, e.g. 10.99 (REQUIRED) - term_months: int 12-84 (REQUIRED) - origination_fee_pct: decimal 0-10 (optional, default 0) - origination_fee_flat: decimal (optional, default 0, takes precedence if > pct-based fee) - include_fee_in_principal: bool (optional, default true) extra_monthly_payment: decimal >= 0 (optional, default 0) current_strategy: 'avalanche' | 'snowball' (optional, default 'avalanche') (Note: fixed_payments is NOT a parameter of this tool, unlike calculate_cc_payoff. The keep-cards baseline is always simulated under the canonical constant rolled-forward payment, see comparison_basis in the response. Passing fixed_payments returns an unknown_parameter error.) Balance transfer, SINGLE OFFER (legacy, all optional): include_balance_transfer: bool (default false) bt_apr_pct: decimal 0-100 (required if include_balance_transfer: true, use 0 for 0% promo) bt_promo_months: int 1-60 (optional, default 18) bt_regular_apr_pct: decimal 0-100 (optional, default 25.20) bt_fee_pct: decimal 0-10 (optional, default 3.0) Balance transfer, MULTI-OFFER (preferred when comparing two or more offers): bt_offers: array of objects (max 10), when supplied, takes precedence over the scalar bt_* fields Each object: - apr_pct: decimal 0-100 (REQUIRED) - promo_months: int 1-60 (optional, default 18) - regular_apr_pct: decimal 0-100 (optional, default 25.20) - fee_pct: decimal 0-10 (optional, default 3.0) - label: string (optional, defaults to "<apr_pct>% / <months>mo") The response includes a balance_transfer_offers block with per-offer simulation results, selected_offer_index, selected_offer_label, selected_offer_reason, and all_offers_trap. Partial balance transfer (use when the BT offer has a transfer limit < your total debt): bt_transfer_limit: decimal >= 0.01 (optional), cap on total transferred amount. When set, only this amount moves to the BT card; remaining balances stay on original cards. A combined simulation runs both halves together, correctly redistributing freed minimum payments. When omitted, the entire balance is transferred (legacy behavior). bt_transfer_strategy: 'highest_apr_first' | 'highest_balance_first' | 'manual' (optional, default 'highest_apr_first') highest_apr_first: transfer from highest-APR segments first (maximizes interest savings) highest_balance_first: transfer largest balances first manual: use bt_manual_transfers to specify exact amounts per card bt_manual_transfers: array of objects (required when bt_transfer_strategy='manual') Each object: - card_name: string (must match a card name in cards[]) - amount: decimal > 0 full_schedule: bool (optional, default false, compact schedule by default) windfalls: array of one-time principal payments (optional, default empty, max 12). Same shape as calculate_cc_payoff. Each item: - month: int >= 0 (REQUIRED). 0 means applied before month 1's interest. N >= 1 applies at the END of calendar month N. - amount: decimal > 0 (REQUIRED). - label: string (optional). e.g. 'Tax refund', 'Year-end bonus'. When non-empty the response adds windfalls_applied[] and windfalls_unused[] on keep_cards, on each balance_transfer scenario (and on each offer in balance_transfer_offers.offers[]), on consolidation_loan (single-row per windfall since the loan is a single-balance instrument), and on optimized_consolidation.keep_subset. All scenarios use with-windfalls totals so cross-option ranking stays apples-to-apples. chart_title: string (optional) override for the chart title. Must not contain em-dashes or en-dashes. Max 120 characters. ENVELOPE: output: 'summary' (default) | 'inline' | 'capture' summary: compact response with a data_preview block. No heavy array exists on this response today, so summary and inline are currently identical in content; the envelope is wired ahead of the future chart-render pipeline. inline: full payload (currently identical to summary; will diverge once a heavy array is added for chart rendering). capture: full payload written to ~/.senaro/captures/; capture_ref URI returned. Available on the local stdio transport only; the hosted HTTP transport rejects 'capture' with a structured error naming 'summary' and 'inline' as the valid alternatives. |