401k.loans: 401(k) loan and withdrawal calculators

Compare a 401(k) loan with a hardship withdrawal, personal loan and HELOC

compare_401k_loan_alternatives

Read-onlyIdempotent

Prices four ways to raise the same cash with the 401k.loans comparison tool: 401(k) loan, hardship withdrawal (grossed up for tax and the 10% additional tax), personal loan (rate plus origination fee) and HELOC. For each: amount taken out, monthly payment, money gone for good (interest to others, fees, tax, penalty), interest paid back to yourself, how much smaller the 401(k) is at term end and at 65, and whether it is allowed.

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": {
      "cash_needed": "<cash_needed>",
      "vested_balance": "<vested_balance>"
    },
    "name": "compare_401k_loan_alternatives"
  }
}

Input Schema

Name	Required	Description
`age`	No	Your age today, 18 to 80. Default 40.
`years`	No	Years to pay back, 1 to 5. Default 3.
`cash_needed`	Yes	Cash you need in hand, in dollars, e.g. 10000.
`plan_loan_fee`	No	Flat 401(k) loan fee in dollars. Default 0.
`plan_rate_pct`	No	401(k) plan loan rate in percent, 0 to 20. Default: the prime rate plus 1 point, as an example.
`state_tax_pct`	No	State income tax rate in percent, 0 to 15. Default 0.
`heloc_rate_pct`	No	HELOC rate in percent, 0 to 20. Default: the prime rate alone, before the margin a lender adds.
`vested_balance`	Yes	Vested 401(k) balance in dollars, e.g. 60000.
`penalty_exception`	No	true if an exception to the 10% early withdrawal tax applies (for example, you left this employer in or after the year you turned 55). The 10% is never applied at 59.5 or older. Default false.
`assumed_return_pct`	No	Annual return you assume the 401(k) would earn, in percent (-20 to 20). An assumption, not a forecast. Default 6.
`federal_bracket_pct`	No	2026 federal income tax bracket in percent (Rev. Proc. 2025-32): 10, 12, 22, 24, 32, 35 or 37.
`heloc_closing_costs`	No	HELOC closing costs in dollars. Default 0.
`origination_fee_pct`	No	Personal loan origination fee in percent of the loan, 0 to 12. Default 0.
`personal_loan_rate_pct`	No	Personal loan interest rate in percent (not the APR), 0 to 36. Default 11.9, the Federal Reserve G.19 average on 24-month bank loans (Q3 2026).

Schema Changelog

Changes observed during successful MCP inspections.

First observedNov 1, 2026

TDQS

A4.1/5.0

Behavior4/5

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

Annotations already declare readOnly/idempotent/non-destructive, so safety is covered. The description adds real modeling context beyond that: hardship withdrawals are grossed up for tax plus the 10% additional tax, and personal loan cost includes rate plus origination fee — disclosing the assumptions baked into the comparison rather than raw arithmetic.

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?

One dense sentence with zero filler, front-loaded on the four-option comparison, followed by the output list. It is slightly run-on as a long comma chain, but every clause carries information an agent needs.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 14 parameters and no output schema, the description carries the return-value burden and does so by enumerating the per-option outputs (amount taken, monthly payment, money gone for good, self-paid interest, balance impact at term and at 65, eligibility). What is under-specified is how defaults are resolved when optional inputs are omitted, but the core call is well covered.

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 coverage is 100%, so baseline is 3. The description earns above baseline by linking inputs to the model: tax gross-up ties to federal/state bracket and penalty_exception, the origination fee ties to origination_fee_pct, and 'whether it is allowed' signals eligibility logic driven by vested_balance.

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 scope: prices four named ways to raise the same cash (401(k) loan, hardship withdrawal, personal loan, HELOC), and enumerates each. The 'same cash' framing distinguishes it from the sibling single-path calculators (calculate_401k_loan_cost, calculate_401k_early_withdrawal) without needing to name them.

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

Usage Guidelines3/5

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

Usage is implied by 'four ways to raise the same cash' — an agent can infer it is for comparing funding options — but there is no explicit when-to-use/when-not guidance and no reference to the sibling tools that calculate a single path. The choice between this and calculate_401k_loan_cost is left to inference.

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

All 401k.loans: 401(k) loan and withdrawal calculators tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?