{"openapi":"3.1.0","info":{"title":"Nest API","version":"0.1.0","description":"US retirement-planning calculators: 401(k)/403(b)/IRA/HSA contribution and catch-up limits, compound-growth savings projections, Social Security claiming-age adjustments, RMDs, Roth-vs-traditional comparison, Roth IRA income limits, and a glossary — all local, from bundled verified IRS/SSA figures.\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://nest.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"hr@unifydynamics.com","url":"https://connectorbay.com/nest/docs"},"termsOfService":"https://connectorbay.com/nest/terms"},"servers":[{"url":"https://nest.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/nest/docs"},"security":[{},{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/contribution_limits":{"post":{"operationId":"contribution_limits","summary":"Current IRS employee contribution limit and catch-up limit for a 401(k), 403(b), traditional IRA, Roth IRA,","description":"Current IRS employee contribution limit and catch-up limit for a 401(k), 403(b), traditional IRA, Roth IRA,\n    or HSA in 2025 or 2026, including the SECURE 2.0 age 60-63 super catch-up for 401(k)/403(b). Use for \"401k\n    limit for 2026\", \"HSA family limit 2025\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"year":{"default":"2026","description":"Tax year: 2025 | 2026","title":"Year","type":"string"},"account_type":{"default":"401k","description":"401k | 403b | ira_traditional | ira_roth | hsa","title":"Account Type","type":"string"}},"title":"contribution_limitsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/retirement_savings_projection":{"post":{"operationId":"retirement_savings_projection","summary":"Compound-growth projection of a retirement account to a target age, with a year-by-year schedule; the","description":"Compound-growth projection of a retirement account to a target age, with a year-by-year schedule; the\n    contribution may grow annually (e.g. with raises). Use for \"what will $10,000 now plus $6,000/year at 7%\n    become by 65, with 3% raises\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"current_age":{"maximum":120,"minimum":0,"title":"Current Age","type":"integer"},"retirement_age":{"maximum":120,"minimum":0,"title":"Retirement Age","type":"integer"},"current_balance":{"minimum":0,"title":"Current Balance","type":"number"},"annual_contribution":{"minimum":0,"title":"Annual Contribution","type":"number"},"expected_return_pct":{"description":"Expected annual return, %.","title":"Expected Return Pct","type":"number"},"contribution_growth_pct":{"default":0.0,"description":"Annual increase to the contribution, % (e.g. for raises). 0 = flat contribution.","title":"Contribution Growth Pct","type":"number"}},"required":["current_age","retirement_age","current_balance","annual_contribution","expected_return_pct"],"title":"retirement_savings_projectionArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/required_sip_for_goal":{"post":{"operationId":"required_sip_for_goal","summary":"Reverse calculator: the flat annual (and approximate monthly) contribution needed to reach a target","description":"Reverse calculator: the flat annual (and approximate monthly) contribution needed to reach a target\n    retirement corpus by a given age. Use for \"how much do I need to save each year to have $1.5 million by 67\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"current_age":{"maximum":120,"minimum":0,"title":"Current Age","type":"integer"},"retirement_age":{"maximum":120,"minimum":0,"title":"Retirement Age","type":"integer"},"target_corpus":{"exclusiveMinimum":0,"title":"Target Corpus","type":"number"},"current_balance":{"minimum":0,"title":"Current Balance","type":"number"},"expected_return_pct":{"description":"Expected annual return, %.","title":"Expected Return Pct","type":"number"}},"required":["current_age","retirement_age","target_corpus","current_balance","expected_return_pct"],"title":"required_sip_for_goalArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/social_security_estimate":{"post":{"operationId":"social_security_estimate","summary":"Adjusts a known Primary Insurance Amount for claiming early (as early as 62, using SSA's 5/9%-per-month","description":"Adjusts a known Primary Insurance Amount for claiming early (as early as 62, using SSA's 5/9%-per-month\n    then 5/12%-per-month reduction) or delayed (up to 70, at SSA's 8%/year delayed credit). Does NOT compute PIA\n    from an earnings history — that requires SSA's own record. Use for \"I claim at 62 with a $2,400 PIA, what's\n    my check\", \"what if I wait until 70\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"birth_year":{"maximum":2100,"minimum":1900,"title":"Birth Year","type":"integer"},"claiming_age":{"description":"Age at which benefits start, 62-70.","maximum":70,"minimum":62,"title":"Claiming Age","type":"number"},"estimated_pia_at_fra":{"description":"Primary Insurance Amount at full retirement age, from your own SSA statement.","exclusiveMinimum":0,"title":"Estimated Pia At Fra","type":"number"}},"required":["birth_year","claiming_age","estimated_pia_at_fra"],"title":"social_security_estimateArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/full_retirement_age":{"post":{"operationId":"full_retirement_age","summary":"Looks up a birth year's Social Security full retirement age (65-67) from the published SSA table. Use for","description":"Looks up a birth year's Social Security full retirement age (65-67) from the published SSA table. Use for\n    \"what's my full retirement age if I was born in 1988\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"birth_year":{"maximum":2100,"minimum":1900,"title":"Birth Year","type":"integer"}},"required":["birth_year"],"title":"full_retirement_ageArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/rmd_calculator":{"post":{"operationId":"rmd_calculator","summary":"Required Minimum Distribution using the current SECURE 2.0 start age (73 through 2032, 75 from 2033) and","description":"Required Minimum Distribution using the current SECURE 2.0 start age (73 through 2032, 75 from 2033) and\n    the IRS Uniform Lifetime Table divisor. Use for \"RMD on $400,000 at age 75 in 2026\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"account_balance":{"description":"Prior year-end account balance.","minimum":0,"title":"Account Balance","type":"number"},"age":{"description":"Age the account owner turns (or turned) this year.","maximum":130,"minimum":0,"title":"Age","type":"integer"},"year":{"maximum":2100,"minimum":2023,"title":"Year","type":"integer"}},"required":["account_balance","age","year"],"title":"rmd_calculatorArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/roth_vs_traditional":{"post":{"operationId":"roth_vs_traditional","summary":"Illustrative ending after-tax value of Roth vs. traditional contributions of the same pre-tax dollars,","description":"Illustrative ending after-tax value of Roth vs. traditional contributions of the same pre-tax dollars,\n    under stated current/retirement tax-rate assumptions — real computed math, clearly not a full tax projection.\n    Use for \"Roth or traditional if I'm in the 22% bracket now and 12% in retirement\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"current_tax_rate_pct":{"description":"Your marginal tax rate today, %.","exclusiveMaximum":100,"minimum":0,"title":"Current Tax Rate Pct","type":"number"},"expected_retirement_tax_rate_pct":{"description":"Your assumed marginal tax rate in retirement, %.","exclusiveMaximum":100,"minimum":0,"title":"Expected Retirement Tax Rate Pct","type":"number"},"annual_contribution":{"description":"Pre-tax dollars available to contribute each year.","exclusiveMinimum":0,"title":"Annual Contribution","type":"number"},"years":{"exclusiveMinimum":0,"title":"Years","type":"integer"},"expected_return_pct":{"description":"Expected annual return, %.","title":"Expected Return Pct","type":"number"}},"required":["current_tax_rate_pct","expected_retirement_tax_rate_pct","annual_contribution","years","expected_return_pct"],"title":"roth_vs_traditionalArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/roth_ira_income_limit_check":{"post":{"operationId":"roth_ira_income_limit_check","summary":"Checks a filing status and MAGI against the current-year Roth IRA phase-out range: full, partial (phased),","description":"Checks a filing status and MAGI against the current-year Roth IRA phase-out range: full, partial (phased),\n    or not allowed for a direct contribution. Use for \"can I contribute to a Roth IRA at $170,000 MAGI married\n    filing jointly in 2026\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"filing_status":{"description":"single | head_of_household | married_filing_jointly | married_filing_separately","title":"Filing Status","type":"string"},"magi":{"description":"Modified Adjusted Gross Income.","minimum":0,"title":"Magi","type":"number"},"year":{"default":"2026","description":"Tax year: 2025 | 2026","title":"Year","type":"string"}},"required":["filing_status","magi"],"title":"roth_ira_income_limit_checkArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/catch_up_contribution_check":{"post":{"operationId":"catch_up_contribution_check","summary":"Whether someone at a given age qualifies for the standard catch-up, or the SECURE 2.0 age 60-63 \"super","description":"Whether someone at a given age qualifies for the standard catch-up, or the SECURE 2.0 age 60-63 \"super\n    catch-up\" (401(k)/403(b) only, since 2025), for a given account type and year. Use for \"am I eligible for the\n    super catch-up at 61 in a 401k in 2026\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"age":{"maximum":130,"minimum":0,"title":"Age","type":"integer"},"account_type":{"description":"401k | 403b | ira_traditional | ira_roth | hsa","title":"Account Type","type":"string"},"year":{"default":"2026","description":"Tax year: 2025 | 2026","title":"Year","type":"string"}},"required":["age","account_type"],"title":"catch_up_contribution_checkArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/retirement_glossary":{"post":{"operationId":"retirement_glossary","summary":"Definitions of common US retirement-planning terms (RMD, catch-up contribution, vesting, FRA, PIA, Roth","description":"Definitions of common US retirement-planning terms (RMD, catch-up contribution, vesting, FRA, PIA, Roth\n    conversion, the 4% rule, ...). Use for \"what does vesting mean\", \"what's the 4% rule\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"term":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"A specific term to look up; omit to list all.","title":"Term"}},"title":"retirement_glossaryArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}