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

TableJSON Schema

Name	Required	Description
`years`	No	For how_much: how many years the money should last
`balance`	Yes	Starting balance, in dollars
`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
`withdrawal_amount`	No	For how_long: each withdrawal, in dollars, at the chosen frequency
`expected_return_pct`	Yes	Assumed yearly return in %

Output Schema

TableJSON 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.

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.6/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 the safety profile is covered. The description adds genuinely useful behavioral context beyond that: withdrawals occur monthly/quarterly/annually with a yearly return between them, inflation optionally escalates the withdrawal, returns are an assumption, and taxes/fees are excluded. It stops short of describing the output shape, but an output schema exists.

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-loads the calculator's mechanics, then the two modes, then usage triggers and exclusions. Dense but every clause carries informational weight; the mode list and caveat sentences are tightly packed rather than wasteful.

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?

For an 8-parameter, read-only calculator with full schema coverage, an output schema, and complete annotations, the description supplies the remaining gaps: modeling assumptions, escalation behavior, and scope exclusions. Nothing an agent needs to invoke it correctly is missing.

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 the baseline is 3, but the description adds model-level meaning the schema cannot: how the two question modes pair with their required inputs, that inflation escalation applies only to how_long, and what lasts_forever conceptually means (never touching principal). This clarifies parameter interplay rather than merely restating field names.

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 capability with two named modes (how_long, how_much) and a concrete resource (retirement withdrawals), and explicitly distinguishes itself from smartfin_calculate_fire_number. An agent can route between this and its siblings 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?

Gives explicit trigger phrases ('how long will my savings last', 'how much can I withdraw') and an explicit exclusion ('Do not use to find a savings target (use smartfin_calculate_fire_number)'). When-to-use, when-not-to-use, and the named alternative are all present.

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?