Optimal yearly Roth vs traditional split: 401(k), IRA, HSA, brokerage, employer match. Free.
Scored across 3 tools
Each tool has a clearly distinct role: feasibility triage, example-input generation, and the actual optimization. The descriptions make the boundaries explicit, including which tools do not solve. There is no realistic risk of confusing the solver with either helper.
All names use snake_case with verb-led phrasing, which is consistent and readable. The only minor deviation is that check_request is more generic than the domain-specific get_contribution_example and optimize_retirement_contributions.
Three tools is well-scoped for a focused retirement contribution optimizer. One tool performs the solve, while the other two provide necessary intake and schema support without bloat.
The surface covers feasibility checking, input construction, and the core optimization with comparisons and milestones. Minor gaps remain, such as no tool to inspect assumptions or request sensitivity analysis, but core workflows are covered.
Say in plain words what the user wants (e.g. 'I'm self-employed with a solo 401k and a pension'). Returns whether this optimizer can do it and, if not, the closest thing it can do. Fast, no solve.
| Name | Required | Description | Default |
|---|---|---|---|
| description | Yes | The user's question in a sentence or two. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, idempotent, non-destructive behavior. The description adds useful behavioral detail: it returns whether the optimizer can do the request and, if not, the closest thing it can do, and it explicitly does not perform a solve.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short, front-loaded, and every sentence adds useful information: input style, return behavior, and the no-solve constraint.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With a single, fully documented parameter, safe annotations, and no output schema, the description covers what the tool does, what it returns, and which sibling-like behavior it avoids. Nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the input field is already documented. The description adds meaningful guidance beyond the schema by asking for the user's request in plain words and giving a concrete example of the expected style.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool checks whether the optimizer can handle a user's described situation and returns the closest alternative if not. The phrase "Fast, no solve" distinguishes it from the optimization sibling, though it does not explicitly name alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives a clear usage context: describe the situation in plain words and get a fast feasibility check rather than a full solve. It implies use before optimization, but does not explicitly say when to call optimize_retirement_contributions instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return a complete example input for optimize_retirement_contributions with a one-line explanation of every field. No solve. Edit it to the user's situation. kind 'single' (default) or 'married' (two earners, kids, HSA, two-tier match).
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No |
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 bar is lower. The description still adds real behavior: no solve is performed, the output includes a one-line explanation per field, and the two variants differ substantively (married adds two earners, kids, HSA, two-tier match).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four short sentences, zero filler, front-loaded with the outcome before the caveat and the parameter detail. Every sentence carries distinct information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, and the description compensates by describing the return value (a complete example input plus per-field explanations). It could go one step further and name the sequence of calls (this → optimize_retirement_contributions), but for a single-enum helper it is nearly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must carry the parameter. It does more than the enum allows: it names the default ('single') and qualitatively expands what 'married' models — two earners, HSA, two-tier match — which the bare enum values cannot convey.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: 'Return a complete example input for optimize_retirement_contributions.' It explicitly positions itself against the sibling solver with 'No solve,' so an agent can distinguish the example generator from the optimizer without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'No solve. Edit it to the user's situation' tells the agent what this tool is NOT for and what to do with the output, which is genuine routing guidance. It implies this is a precursor to calling optimize_retirement_contributions but never states the ordering or the condition that should trigger the call.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find the best yearly split of retirement savings between traditional and Roth 401(k), IRA/backdoor Roth, HSA and brokerage, including employer match, Roth conversions and retirement withdrawals. Returns this year's dollars per account, how the optimal mix compares with always-traditional and always-Roth, Roth share, lifetime totals, the first working years and retirement milestones. Runs in a few seconds (a few more with exact_income_limits). All money in today's dollars. Optimal for the stated assumptions; not tax advice. Call get_contribution_example first if unsure of the shape.
| Name | Required | Description | Default |
|---|---|---|---|
| age | Yes | Your age this year. The plan starts now. | |
| filing | No | Tax filing status. Default 'single'. 'married' = one joint return; fill in the spouse_* fields. | |
| salary | Yes | Your gross pay this year, in dollars. | |
| end_age | No | Plan until this age (default 92; horizon at most 90 years). | |
| accounts | No | Which accounts the user can use. Defaults: 401(k) and Roth 401(k) available, IRA allowed, no HSA, no match. | |
| balances | No | Current household balances, dollars. Omitted = 0. | |
| retire_age | Yes | Age you stop working. Must be above 'age'. | |
| assumptions | No | Modeling assumptions; the defaults are reported back. | |
| spouse_salary | No | Married only: spouse's gross pay this year (0 or omitted = spouse does not work). | |
| real_raise_pct | No | Yearly raise above inflation, whole percent (1 = 1%). Default 1. | |
| social_security | No | Expected Social Security (household). Omitted = none modeled. | |
| spouse_retire_age | No | Married only: the age YOU will be when your spouse stops working (all ages on this server are the primary earner's). Default = retire_age. | |
| children_birth_years | No | Birth years of dependent children (child tax credit, head of household). | |
| spending_in_retirement | Yes | Yearly spending after retiring, today's dollars (before income tax). | |
| spending_while_working | No | Yearly living costs while still working, today's dollars. Default = spending_in_retirement. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish this as a safe, read-only, idempotent computation. The description adds useful behavioral context beyond annotations: runtime expectations, today's-dollar convention, the scope of optimization, and a clear caveat that results are optimal only for stated assumptions and are not tax advice.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense, front-loaded, and free of filler. Every sentence adds a distinct piece of value: optimization scope, return contents, runtime, dollar convention, caveat, and helper-tool pointer.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex 15-parameter financial optimizer with no output schema, the description is complete enough. It explains what is optimized, summarizes the returned outputs, sets runtime expectations, states the dollar convention, and points to an example tool for input shape.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all 15 parameters are already well documented in the schema. The description does not add parameter-specific syntax or semantics beyond what the schema provides, which is acceptable at baseline 3 when the schema carries that burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific optimization verb and resource: finding the best yearly split of retirement savings across traditional/Roth 401(k), IRA/backdoor Roth, HSA, and brokerage. It clearly distinguishes the actual optimization tool from the sibling helper get_contribution_example by describing the detailed result it returns.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly routes uncertain users to get_contribution_example for input shape and gives practical runtime context. It does not mention when not to use the tool or clarify the role of the other sibling, check_request.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
check_requestget_contribution_exampleoptimize_retirement_contributionsRetirement Monte Carlo, tax-aware withdrawals, 2026 tax calculators, RMD, IRMAA, every-state tax.
Deterministic US financial planning: retirement Monte Carlo, Roth conversion, RMD, tax, IRMAA, SS
Retirement drawdown, 72(t) SEPP, RMD, Roth conversion, Social Security and state-tax calculators.
Equity comp tax/trade optimizer: ISO/AMT exercise, NSO, RSU, QSBS, concentration, hedging. 50-state.
Add one secure layer between your agents and this server.
