SmartFin

Retirement withdrawals: how long or how much

smartfin_calculate_retirement_withdrawal

Read-onlyIdempotent

Works the way SmartFin's withdrawal calculator does, with withdrawals monthly, quarterly or annually and the balance earning a yearly return between them. how_long: how many years a balance lasts at a set withdrawal, optionally rising each year with inflation. how_much: the withdrawal that lasts a given number of years, or that never touches the principal (lasts_forever). Use for "how long will my savings last" or "how much can I withdraw". Do not use to find a savings target (use smartfin_calculate_fire_number). Returns are an assumption; excludes taxes and fees.

Input Schema

Name	Required	Description
`years`	No	For how_much: how many years the money should last
`balance`	Yes	Starting balance, in the currency chosen
`currency`	No	Currency symbol for the amounts in the summary only; amounts are never converted. The link opens the page in US dollars, and how_to says to pick the currency there. Default USD
`question`	Yes	how_long needs withdrawal_amount; how_much needs years or lasts_forever
`frequency`	No	How often money is withdrawn. Default monthly
`inflation_pct`	No	For how_long, optional: the withdrawal rises by this % each year
`lasts_forever`	No	For how_much: the withdrawal that never touches the principal. At a return of 0% or below no amount qualifies, and withdrawal_per_period is 0
`withdrawal_amount`	No	For how_long: each withdrawal, in the currency chosen, at the chosen frequency
`expected_return_pct`	Yes	Assumed yearly return in %

Output Schema

Name	Required	Description
`cite`	Yes	How to credit this result
`data`	Yes
`next`	Yes	Suggested follow-up calls
`links`	Yes
`how_to`	Yes	Steps for the user to see or redo this on smartfin.fyi
`source`	Yes
`summary`	Yes	Plain-language result the assistant can quote

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedNov 1, 2026
- changedInput schema / properties / balance / maximum
```
Previous value: -10000000000New value: +100000000
```
- changedInput schema / properties / balance / minimum
```
Previous value: -0New value: +1
```
- changedInput schema / properties / inflation_pct / maximum
```
Previous value: -100New value: +20
```
- changedInput schema / properties / withdrawal_amount / maximum
```
Previous value: -1000000000New value: +10000000
```

Changed4 schema fields changedOct 18, 2026

changedInput schema / properties / balance / description

Previous value: -"Starting balance, in dollars"New value: +"Starting balance, in the currency chosen"

addedInput schema / properties / currency

Added value: +{
+  "description": "Currency symbol for the amounts in the summary only; amounts are never converted. The link opens the page in US dollars, and how_to says to pick the currency there. Default USD",
+  "enum": [
+    "USD",
+    "EUR",
+    "GBP",
+    "CHF",
+    "AUD",
+    "CAD",
+    "SGD",
+    "HKD",
+    "INR",
+    "JPY"
+  ],
+  "type": "string"
+}

changedInput schema / properties / lasts_forever / description

Previous value: -"For how_much: the withdrawal that never touches the principal"New value: +"For how_much: the withdrawal that never touches the principal. At a return of 0% or below no amount qualifies, and withdrawal_per_period is 0"

changedInput schema / properties / withdrawal_amount / description

Previous value: -"For how_long: each withdrawal, in dollars, at the chosen frequency"New value: +"For how_long: each withdrawal, in the currency chosen, at the chosen frequency"

Changed1 schema field changedSep 29, 2026

addedOutput schema / properties / links / properties / page

Added value: +{
+  "description": "SmartFin's page for this stock, when it has one",
+  "type": "string"
+}

First observedSep 29, 2026

TDQS

A4.3/5.0

Behavior4/5

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description's job is to add domain caveats — and it does: returns are an assumption, taxes and fees are excluded, and it flags the lasts_forever edge case where nothing qualifies at 0% or below. It stops short of describing output shape or how the link/currency handoff behaves beyond the summary.

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 mechanics and then the mode definitions, with zero filler sentences. The opening clause "works the way SmartFin's withdrawal calculator does" is slightly circular and less informative than the rest, but overall it is tight.

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 rich annotations, a full output schema and fully described parameters, the description covers what an agent needs: two modes, their required inputs, the exclusion set, and the alternative tool. The currency-not-converted caveat lives only in the schema, so it is not fully self-contained, but nothing critical is missing.

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

Parameters3/5

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

Schema description coverage is 100% and each parameter is documented in place, including the mode-parameter dependencies, so the description is not required to carry parameter detail. It reinforces the mode-to-parameter mapping but adds no syntax or format information the schema lacks, which is the baseline-3 case.

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?

The description names both specific modes (how_long, how_much), the resource (retirement withdrawals), the compounding cadence, and states the boundary against a named sibling tool. An agent can tell exactly what computation this performs without opening the 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?

It gives explicit routing: use for "how long will my savings last" or "how much can I withdraw", and explicitly excludes savings-target questions with a pointer to smartfin_calculate_fire_number. Mode selection is also mapped to inputs (how_long needs a withdrawal, how_much needs years or lasts_forever), leaving nothing to inference.

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

All SmartFin 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?