Senaro Personal Finance

401(k) Match Optimizer

optimize_401k_match

Read-onlyIdempotent

Calculation, not advice. Verify with a professional before acting. Deterministic 401(k) employer-match optimizer. Given your annual salary, pay frequency, current contribution percent, and your employer's match formula (as a named preset or a custom tier list), computes:

the annual match you receive today;
the maximum match available (full match entitlement);
the match forfeited at your current rate;
the minimum contribution percent to receive the full match;
whether front-loading contributions would forfeit match at a no-true-up plan; and
a per-period schedule showing level vs. front-load paths side by side.

Pick this to size 401(k) contributions against the employer match formula; pick compare_payoff_vs_invest when the question is putting an extra monthly amount toward a debt versus investing it (that tool takes no employer-match input), not how much of the match to receive.

IRS limits (402(g) elective deferral, 401(a)(17) compensation cap, 415(c) annual additions) are applied and cited in provenance. Catch-up contribution ceilings for ages 50+ and 60-63 (SECURE 2.0) are computed when participant_age is provided; when a catch-up allowance applies, applied_caps[].cap_name reads '402(g) elective deferral plus 414(v) catch-up' and limit_value carries the combined ceiling, not the bare 402(g) amount.

HEAVY tool: use output='summary' (default) for the headline scalars or output='inline' for the full per-period schedule.

Input Schema

TableJSON Schema

Name	Required	Description
`output`	No	Valid values: 'summary' (default), 'inline'. Response envelope. 'summary': headline scalars, period_schedule stripped. 'inline': full payload including period_schedule[].
`chart_title`	No	Override for the chart title. Reserved for the chart pipeline. Must not contain em-dashes or en-dashes. Max 120 characters. Optional.
`has_true_up`	No	Whether the plan provides an annual true-up. false is the conservative assumption: surfaces front-loading forfeiture risk. Optional; defaults to false when omitted.
`match_tiers`	No	Custom match-formula tier list. Example: [{"match_frac": 1.0, "up_to_deferral_pct": 3}, {"match_frac": 0.5, "up_to_deferral_pct": 2}] = safe_harbor_basic. Exactly one of match_preset or match_tiers is required. Optional; omit when supplying match_preset.
`match_preset`	No	Named match-formula preset: 'safe_harbor_basic' (100% of first 3% + 50% of next 2%), 'safe_harbor_enhanced_simple' (100% of first 4%), 'qaca' (100% of first 1% + 50% of next 5%), 'fifty_pct_of_first_six_pct' (50% of first 6%). Exactly one of match_preset or match_tiers is required. Optional; omit when supplying match_tiers.
`annual_salary`	Yes	Annual gross salary. Decimal > 0. REQUIRED, no default.
`participant_age`	No	Determines which catch-up limit applies (age 50+, or age 60-63 SECURE 2.0 super catch-up). Integer >= 0. Optional; omit when age is unknown or participant is under 50.
`contribution_pct`	Yes	Current employee contribution as a percent of gross pay. Decimal in [0, 100]. REQUIRED, no default.
`pay_periods_per_year`	Yes	Pay periods per year (12=monthly, 24=semi-monthly, 26=biweekly, 52=weekly). Integer in [1, 365]. REQUIRED, no default.

Schema Changelog

Changes observed during successful MCP inspections.

Changed9 schema fields changedSep 24, 2026
- addedInput schema / properties / chart_title / maxLength
```
Added value: +120
```
- addedInput schema / properties / contribution_pct / maximum
```
Added value: +100
```
- addedInput schema / properties / contribution_pct / minimum
```
Added value: +0
```
- addedInput schema / properties / match_preset / enum
```
Added value: +[
+  "safe_harbor_basic",
+  "safe_harbor_enhanced_simple",
+  "qaca",
+  "fifty_pct_of_first_six_pct",
+  null
+]
```
- addedInput schema / properties / match_tiers / maxItems
```
Added value: +10
```
- changedInput schema / properties / output / enum
```
Previous value: -[
-  "summary",
-  "inline"
-]New value: +[
+  "summary",
+  "inline",
+  null
+]
```
- changedInput schema / properties / output / type
```
Previous value: -"string"New value: +[
+  "string",
+  "null"
+]
```
- addedInput schema / properties / pay_periods_per_year / maximum
```
Added value: +365
```
- addedInput schema / properties / pay_periods_per_year / minimum
```
Added value: +1
```

Changed4 schema fields changedSep 22, 2026

removedInput schema / properties / output / default
```
Removed value: -null
```

changedInput schema / properties / output / description

Previous value: -"Response envelope. 'summary' (default): headline scalars, period_schedule stripped. 'inline': full payload including period_schedule[]. 'capture': full payload written to ~/.senaro/captures/, capture_ref URI returned; local stdio transport only, rejected with a structured error on the hosted HTTP transport naming 'summary' and 'inline' as the valid alternatives."New value: +"Valid values: 'summary' (default), 'inline'. Response envelope. 'summary': headline scalars, period_schedule stripped. 'inline': full payload including period_schedule[]."

addedInput schema / properties / output / enum

Added value: +[
+  "summary",
+  "inline"
+]

changedInput schema / properties / output / type

Previous value: -[
-  "string",
-  "null"
-]New value: +"string"

Changed11 schema fields changedSep 19, 2026

addedInput schema / properties / annual_salary

Added value: +{
+  "description": "Annual gross salary. Decimal > 0. REQUIRED, no default.",
+  "type": "number"
+}

addedInput schema / properties / chart_title

Added value: +{
+  "default": null,
+  "description": "Override for the chart title. Reserved for the chart pipeline. Must not contain em-dashes or en-dashes. Max 120 characters. Optional.",
+  "type": [
+    "string",
+    "null"
+  ]
+}

addedInput schema / properties / contribution_pct

Added value: +{
+  "description": "Current employee contribution as a percent of gross pay. Decimal in [0, 100]. REQUIRED, no default.",
+  "type": "number"
+}

addedInput schema / properties / has_true_up

Added value: +{
+  "default": null,
+  "description": "Whether the plan provides an annual true-up. false is the conservative assumption: surfaces front-loading forfeiture risk. Optional; defaults to false when omitted.",
+  "type": [
+    "boolean",
+    "null"
+  ]
+}

addedInput schema / properties / match_preset

Added value: +{
+  "default": null,
+  "description": "Named match-formula preset: 'safe_harbor_basic' (100% of first 3% + 50% of next 2%), 'safe_harbor_enhanced_simple' (100% of first 4%), 'qaca' (100% of first 1% + 50% of next 5%), 'fifty_pct_of_first_six_pct' (50% of first 6%). Exactly one of match_preset or match_tiers is required. Optional; omit when supplying match_tiers.",
+  "type": [
+    "string",
+    "null"
+  ]
+}

addedInput schema / properties / match_tiers

Added value: +{
+  "default": null,
+  "description": "Custom match-formula tier list. Example: [{\"match_frac\": 1.0, \"up_to_deferral_pct\": 3}, {\"match_frac\": 0.5, \"up_to_deferral_pct\": 2}] = safe_harbor_basic. Exactly one of match_preset or match_tiers is required. Optional; omit when supplying match_preset.",
+  "items": {
+    "properties": {
+      "match_frac": {
+        "description": "Employer match fraction for this tier (0.5 = 50%). Must be in (0, 1].",
+        "type": [
+          "number",
+          "null"
+        ]
+      },
+      "up_to_deferral_pct": {
+        "description": "Width of this tier as a percent of pay (e.g. 3 = the first 3% of pay). Must be > 0.",
+        "type": [
+          "number",
+          "null"
+        ]
+      }
+    },
+    "type": [
+      "object",
+      "null"
+    ]
+  },
+  "type": [
+    "array",
+    "null"
+  ]
+}

addedInput schema / properties / output

Added value: +{
+  "default": null,
+  "description": "Response envelope. 'summary' (default): headline scalars, period_schedule stripped. 'inline': full payload including period_schedule[]. 'capture': full payload written to ~/.senaro/captures/, capture_ref URI returned; local stdio transport only, rejected with a structured error on the hosted HTTP transport naming 'summary' and 'inline' as the valid alternatives.",
+  "type": [
+    "string",
+    "null"
+  ]
+}

addedInput schema / properties / participant_age

Added value: +{
+  "default": null,
+  "description": "Determines which catch-up limit applies (age 50+, or age 60-63 SECURE 2.0 super catch-up). Integer >= 0. Optional; omit when age is unknown or participant is under 50.",
+  "type": [
+    "integer",
+    "null"
+  ]
+}

addedInput schema / properties / pay_periods_per_year

Added value: +{
+  "description": "Pay periods per year (12=monthly, 24=semi-monthly, 26=biweekly, 52=weekly). Integer in [1, 365]. REQUIRED, no default.",
+  "type": "integer"
+}

removedInput schema / properties / toolArguments

Removed value: -{
-  "description": "JSON object with parameters:\n\nREQUIRED:\n  annual_salary: decimal > 0. Annual gross salary.\n  pay_periods_per_year: integer in [1, 365]. Pay periods per year (12=monthly, 24=semi-monthly, 26=biweekly, 52=weekly).\n  contribution_pct: decimal in [0, 100]. Current employee contribution as a percent of gross pay.\n\nMATCH FORMULA (exactly one required):\n  match_preset: one of 'safe_harbor_basic' (100% of first 3% + 50% of next 2%), 'safe_harbor_enhanced_simple'\n    (100% of first 4%), 'qaca' (100% of first 1% + 50% of next 5%), 'fifty_pct_of_first_six_pct' (50% of first 6%).\n  match_tiers: array of tier objects [{ match_frac: decimal (0,1], up_to_deferral_pct: decimal > 0 }, ...].\n    match_frac is the employer fraction (0.5 = 50%). up_to_deferral_pct is the tier width as a percent of pay.\n    Example: [{ match_frac: 1.0, up_to_deferral_pct: 3 }, { match_frac: 0.5, up_to_deferral_pct: 2 }] = safe_harbor_basic.\n\nOPTIONAL:\n  has_true_up: bool (default false). Whether the plan provides an annual true-up.\n    false is the conservative assumption: surfaces front-loading forfeiture risk.\n  participant_age: integer >= 0 (optional). Determines which catch-up limit applies (age 50+, or age 60-63 SECURE 2.0 super catch-up).\n    Omit when age is unknown or participant is under 50.\n  chart_title: string (optional). Reserved for the chart pipeline. Must not contain em-dashes or en-dashes. Max 120 characters.\n\nENVELOPE:\n  output: 'summary' (default) | 'inline' | 'capture'\n  summary: headline scalars (match captured/forfeited, full-match threshold, front-load flag, applied_caps, citations);\n    the per-period period_schedule is stripped.\n  inline: full payload including the period_schedule[] (for chart rendering).\n  capture: full payload written to ~/.senaro/captures/; capture_ref URI returned.\n    Available on the local stdio transport only; the hosted HTTP transport rejects 'capture'\n    with a structured error naming 'summary' and 'inline' as the valid alternatives."
-}

changedInput schema / required

Previous value: -[
-  "toolArguments"
-]New value: +[
+  "annual_salary",
+  "pay_periods_per_year",
+  "contribution_pct"
+]

First observedSep 11, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations already supply readOnlyHint=true, idempotentHint=true, and destructiveHint=false; the description then adds substantial non-redundant behavior: determinism, the 'Calculation, not advice' disclaimer, IRS 402(g)/401(a)(17)/415(c) limits applied and cited in provenance, and precise catch-up semantics ('applied_caps[].cap_name reads \'402(g) elective deferral plus 414(v) catch-up\' and limit_value carries the combined ceiling'). It also flags output weight ('HEAVY tool') so agents can choose summary vs. inline. Nothing contradicts the annotations.

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?

Purpose is front-loaded (brief disclaimer, then the 'Deterministic 401(k) employer-match optimizer' statement), and each subsequent block - computed outputs, sibling routing, IRS/catch-up behavior, output-mode guidance - earns its place. It is long, but the density is justified for a 9-parameter financial tool with complicated limit behavior; the catch-up paragraph is the densest and could be tightened slightly.

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 a tool this complex with no output schema, the description is remarkably complete: it enumerates the computed results in prose, names the output envelope modes (summary/inline), specifies period_schedule and applied_caps[] behavior, and covers limits, conservative defaults, and when-not-to-use. Combined with 100% schema coverage and safety annotations, an agent has everything needed to select and invoke this tool correctly.

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 schema already documents all nine parameters thoroughly, putting the baseline at 3. The description adds genuine value by connecting participant_age to concrete output behavior (catch-up ceilings for ages 50+ and 60-63, plus the applied_caps cap_name/limit_value semantics) and by framing the preset-vs-custom-tier choice in prose. It does not restate per-parameter schema details, so 4 rather than 5.

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 leads with a specific, differentiated purpose: a 'Deterministic 401(k) employer-match optimizer' that computes match entitlement from salary, pay frequency, contribution percent, and match formula. It lists six concrete computed outputs (current match, max match, forfeited match, minimum percent to full match, front-loading risk, per-period schedule) and explicitly distinguishes itself from sibling compare_payoff_vs_invest. An agent can tell exactly what this tool does and does not do.

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?

Explicit guidance is embedded: 'Pick this to size 401(k) contributions against the employer match formula; pick `compare_payoff_vs_invest` when the question is putting an extra monthly amount toward a debt versus investing it.' It even notes the sibling takes no employer-match input, removing ambiguity. The 'HEAVY tool: use output=\'summary\'...' sentence also tells the agent when to invoke cheaply vs. request the full schedule.

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

All Senaro Personal Finance 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?