calculators

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

No annotations are provided, so the description carries the full behavioral burden, and it discloses almost nothing beyond the conceptual math: no return format, no units for rates (percent vs. decimal), no mention of how inflation/volatility are applied, and no note that it is a pure read-only computation. The 'no further contributions' framing is the one useful behavioral hint.

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?

A single front-loaded sentence with no waste; the em-dash clause efficiently explains the milestone. It is appropriately sized, though the brevity contributes to the parameter gaps noted elsewhere.

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 10-parameter financial computation with zero schema descriptions, no annotations, and no output schema, the description is far too thin. An agent knows what the tool conceptually computes but not the units, the role of several optional parameters, or the shape of what comes back.

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 0% across 10 parameters, so the description is the only place meaning could be added — and it adds none. Key ambiguities (are expected_return_rate, inflation_rate, and safe_withdrawal_rate percentages or decimals? what does portfolio_volatility do to the result? why monthly_savings exists in a 'no further contributions' calculation?) are left entirely unresolved.

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 gives a specific verb ('Compute') and resource ('Coast FIRE milestone') and defines the concept precisely: capital that compounds to a retirement target with no further contributions. It is clear, though it never distinguishes itself from the sibling calculate_fire_target, so an agent must infer which FIRE variant to call.

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?

There is no statement of when to use this tool versus calculate_fire_target or project_wealth_plan, no prerequisites, and no exclusions. The definition of Coast FIRE implies a use case but the description provides no routing guidance.

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

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

With no annotations, the description carries full burden. It does disclose the method (Monte Carlo simulation) and the return value (probability the portfolio survives the horizon), which is genuinely useful behavioral context. But it omits that results are stochastic/non-deterministic across runs and says nothing about compute cost or edge-case behavior.

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?

Two tight sentences, front-loaded with the purpose then the method/return. No wasted words, though it is short enough that the missing usage guidance isn't an accident of length.

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 an 8-parameter stochastic tool with no annotations and no output schema, the description helpfully states the return value, partially compensating for the absent output schema. But it leaves sibling disambiguation and per-parameter semantics unaddressed, so it is only minimally 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 description coverage is 63%, and the description names no parameters at all. It adds zero meaning beyond the schema, leaving several inputs (e.g., inflation_rate, apply_inflation, currency enum) with no prose guidance to compensate for the coverage gap.

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+resource ('Estimate the savings target needed for Financial Independence / Early Retirement') so an agent knows exactly what is computed. However, it does not differentiate from the close sibling calculate_coast_fire, which an agent would reasonably confuse it with.

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 when-to-use guidance, prerequisites, or named alternatives are given. The presence of calculate_coast_fire as a near-identical FIRE calculator makes the absence of routing guidance a real gap.

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses accuracy limitations ('Educational estimate; commune surcharges and value-enhancing-improvement deductions are not modeled'), which is valuable context, but it says nothing about output form, precision, or computational assumptions beyond those exclusions.

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?

Three tight sentences: purpose first, then coverage/capabilities, then caveats. No filler, and the most important context (scope and limitations) is front-loaded.

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 6-parameter calculator with no output schema and no annotations, the description covers purpose, cantonal scope, key mechanics, and modeling limits well. It could say more about the deferral mechanics or the return shape, but it is largely sufficient to call the tool correctly.

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 only 50%, so the description must compensate. It adds meaning for years_held (holding-period adjustments) and the ersatzbeschaffung fields (replacement-residence deferral), but sale_price, purchase_price, and the interaction between sale/purchase price and tax base are left to inference.

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 ('Estimate') and a precise resource ('Swiss cantonal real-estate capital gains tax/Grundstueckgewinnsteuer for a property sale'), including scope (all 26 cantons). It is clearly distinguishable from the portfolio/FIRE siblings like rebalance_portfolio and project_wealth_plan.

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?

The description implies context by noting it is an 'Educational estimate' for a property sale and covering holding-period and Ersatzbeschaffung scenarios, but it gives no explicit when-to-use/when-not guidance or named alternatives. Usage is inferable but not stated.

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

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

No annotations exist, so the description carries the full burden. It usefully discloses data provenance (derived from real index data, historical, denominated per currency), which is more than a bare getter would offer. It does not address whether profiles are cached/static, how stale the data is, or failure modes for unsupported currencies.

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?

Two tight sentences, front-loaded with what is returned and immediately followed by why it matters. The phrase 'something defensible rather than guessing' is mildly editorial but reinforces intent rather than wasting space.

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 no output schema, the description does the necessary work of explaining the return shape (return % / volatility % pairs) and provenance. For a one-parameter read tool this is close to complete, missing only freshness/mutability of the data.

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% and the single parameter has an explicit enum, so the schema already defines the input fully. The description adds nothing beyond 'denominated in this currency,' which the schema already states — baseline 3 applies.

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?

Names a specific verb+resource (historical portfolio return profiles per currency) and clarifies the unit of return, a (return %, volatility %) pair. It implicitly separates itself from siblings by naming which tools consume this data, though it doesn't explicitly state what it is not.

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?

Gives clear context for when to reach for it: grounding assumptions in calculate_fire_target / project_wealth_plan rather than guessing. No explicit exclusions or prerequisites are stated, but the intended workflow is legible.

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

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

With no annotations, the description carries the full burden and delivers: codes are single-use and expire in 15 minutes, results include IBKR contract ids where known, and RetireCrunch never places orders itself. The expiry/single-use constraint is exactly the kind of behavioral trait an agent cannot get from the schema.

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, purpose front-loaded, followed by the constraint and the next-step routing. No filler or repetition of the name.

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?

No output schema exists, so the description compensates by describing the return payload (trades with IBKR contract ids) plus the downstream workflow. Nothing an agent needs to call and correctly use the result 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 description coverage is 100% for the single 'code' parameter, so the schema already defines it. The description restates the same origin (copied from the Rebalancer via 'Send plan to my AI') without adding syntax or format detail, so baseline 3 applies.

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 (Fetch) and resource (rebalancing trades the user decided on in the RetireCrunch Rebalancer), and identifies the input as a plan code. This clearly separates it from the sibling rebalance_portfolio, which performs the rebalancing rather than fetching a saved plan.

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?

Explicitly routes the agent to the follow-up action: create one create_order_instruction per trade, and notes the user reviews and submits each one in IBKR. It does not name an exclusion case (e.g., 'do not use rebalance_portfolio for this'), but the context for when this tool is needed is clear.

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

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

With no annotations, the description carries the full burden and does so: it discloses the single-use 15-minute link, the no-login encryption model, server-side retention and deletion on open, the share-at-your-own-risk caveat, and that RetireCrunch gives no allocation advice. This is unusually thorough behavioral disclosure for a mutation-like tool.

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?

Front-loaded with the purpose, then sequencing, then return-value semantics. Every sentence carries an instruction or a disclosure the agent must convey to the user, though the paragraph is dense and could be trimmed slightly without losing meaning.

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?

No output schema exists, and the description compensates by explaining exactly what is returned (a private one-time 15-minute link) and how to hand it to the user. Combined with the 100%-covered input schema and the explicit prerequisite tools, nothing needed to call this correctly 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 description coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema by requiring the IBKR payloads be passed through verbatim with no rounding or retyping. It does not add syntax detail for language or the summary object, so it falls short of 5.

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 precise verb and resource: opens the user's Interactive Brokers portfolio in the RetireCrunch Portfolio Rebalancer. This clearly separates it from rebalance_portfolio and get_rebalance_plan, which operate on already-loaded portfolios.

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?

Explicitly names the prerequisite tools (get_account_positions, get_account_balances, get_account_summary) and the required call order, plus a concrete prohibition: pass results UNCHANGED, do not re-type or round numbers. An agent knows exactly what to do before calling this.

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

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

With no annotations, the description carries the full burden. It usefully discloses the tax regime behavior (US bracket-based vs flat rate elsewhere) and the default output shape (compact summary with 5-year milestones vs full array). However, it omits significant behavioral traits for a 28-param simulation model — notably whether portfolio_volatility introduces stochastic/Monte Carlo paths or a single deterministic run, and whether the computation is expensive or long-running.

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?

Three sentences, front-loaded with the verb and scope, then modeling domains, then return behavior. Dense but nearly every phrase carries information. Slight over-listing of modeled domains ('mortgage amortization, optional property sale') where a grouping would read tighter.

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 28-parameter tool with no annotations and no output schema, the description covers the return format and tax behavior but leaves large gaps: no explanation of how volatility changes results, no units guidance, and it claims to model 'pensions' while the schema exposes no pension parameter. Adequate but not complete for this complexity.

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 57%, so the description must partially compensate. It adds real meaning for region (tax model selection), yearly_detail (return shape), and the growth→income switch/property-sale modeling themes, but the majority of the 28 parameters (partner survivor factors, mortgage/property amounts, household_type, currency) get no explanatory support in either place. Marginal value over the schema.

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 opens with a specific verb+resource: 'Run RetireCrunch's full year-by-year Wealth Plan projection for a household,' and enumerates the modeled domains (income, pensions, expenses, portfolio growth, phase switch, mortgage, property sale, tax). This distinguishes it from the narrower FIRE siblings (calculate_fire_target, calculate_coast_fire) as the comprehensive projection engine.

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?

Usage is implied by 'full year-by-year Wealth Plan projection' and the yearly_detail toggle, but the description never states when to choose this over calculate_fire_target or calculate_coast_fire, nor any prerequisites or exclusions. An agent must infer the routing from the sibling names alone.

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

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

With no annotations, the description carries the full burden and does reasonably well: it discloses the return shape (exact trades, per-currency cash movements, overdraft flags, summary) and an important scope limit (no costs/taxes). It stops short of stating determinism, error behavior on infeasible targets, or how locked holdings are treated.

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?

A single front-loaded sentence carries the inputs and outputs, followed by a short scoping clause; nothing is wasted. It is dense and slightly list-heavy but structurally sound.

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 nested, five-parameter planning tool with no output schema and no annotations, the description covers inputs, returned artifacts, and a key behavioral limit. Remaining gaps (target normalization, locked-holding effects, failure modes) are secondary but real.

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 the baseline is 3; the schema already documents fx_rates, class_targets, available_cash and every holding field. The description's mention of per-holding vs per-asset-class targets and FX/cash inputs maps to those parameters but adds no format or constraint detail beyond the schema.

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 names a specific verb and resource ('Rebalance a multi-currency portfolio') and enumerates both required inputs and returned artifacts (BUY/SELL trades, per-currency cash movements, summary). It does not, however, distinguish itself from the sibling get_rebalance_plan, which sounds like it may do the same thing.

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?

Usage is only implied by the input enumeration; there is no explicit statement of when to call this versus get_rebalance_plan or the other portfolio tools. The one scoping exclusion offered ('Planning math only — no transaction costs or taxes') narrows the domain but is a capability limit, not routing guidance.

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