SmartFin

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

Annotations cover the read-only/idempotent/no-destruction profile, and the description goes further by disclosing modeling assumptions an agent could not infer: constant growth rate, deposits at end of each month, unchanging home price, and no currency conversion. These materially affect interpretation of the results.

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 purpose, then usage, then caveats, and almost every clause carries information. The opening sentence is a dense run-on that takes effort to parse, and the enumerating of return fields is partly redundant given the output schema.

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 an output schema and fully covered parameters, the remaining description burden is scope and assumptions, both addressed (exclusions, constant rate, end-of-month deposits, no conversion). Some return-field restatement is unnecessary but harmless; nothing needed to call the tool 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 coverage is 100%, so baseline is 3, but the description adds role-level meaning beyond the schema: reach_within_months switches the tool into solving for the monthly amount, and down_payment_pct is framed as 'what a percentage down is on a price'. It does not add format/units detail beyond what the schema already states.

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 computation: time for savings (existing + monthly deposits at a fixed growth rate) to reach a down payment target, plus the reverse solve for a monthly amount given reach_within_months. It is clearly separable from sibling calculators, and it explicitly routes the mortgage-payment need to smartfin_calculate_loan_payment.

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 explicit triggers ('how long it takes to save for a down payment', 'how much a month reaches one by a date', 'what a percentage down is on a price') and explicit exclusions ('Do not use for how much to put down', mortgage approval, closing costs) with the named alternative for the mortgage payment case.

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?

Annotations cover the safety profile (readOnly, idempotent, closed-world, non-destructive), and the description adds substantive behavior beyond them: the FIRE search is capped at 60 years, returns and inflation are user assumptions rather than facts, taxes are excluded, and the coast FIRE number only appears when a traditional retirement age is supplied. These are real computational limits an agent should know before answering.

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 mechanism, then usage, then exclusion, then caveats, with no filler sentences. The algorithm walkthrough is somewhat long, but each clause carries information needed to interpret the result.

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 nine-parameter calculation tool with an output schema and full annotation coverage, the description supplies the model, the search bound, the optional coast FIRE branch, the exclusion, and the assumption caveats. Nothing material is missing for correct invocation or interpretation.

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 every parameter (currency, inflation, savings, withdrawal rate, retirement age) is already documented in the schema, and the description mostly restates that the withdrawal rate and return are assumptions. It adds no syntax or unit detail beyond the schema, so the 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 computation (the FIRE number and the year it is reached) and explains the underlying model: expenses divided by a withdrawal rate, savings growth, inflation on expenses. It also names the sibling it is not (smartfin_calculate_retirement_withdrawal), so an agent can route correctly 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.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit 'Use for early retirement / FIRE questions' with concrete user phrasings ('how much do I need to retire', 'when can I retire', 'what's my coast FIRE number'), plus a hard exclusion: 'Do not use to test how long an existing balance lasts (use smartfin_calculate_retirement_withdrawal).' Both the when and the when-not are present with the alternative named.

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?

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), so the description's job is to add context beyond that. It does, by framing the output as an assumption-driven forecast rather than a real outcome ('one fixed rate is an assumption'), which is meaningful framing an agent should repeat to a user. It does not, however, mention constraints like the year cap or rate bounds, which the schema carries instead.

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 operation and formula, then routing sentences, with zero filler. It is dense in places (three sibling redirects plus a forecast caveat), but each sentence earns its place by eliminating a specific mis-selection.

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?

An output schema exists, so return values need not be explained, and the description covers purpose, selection boundaries, and the interpretive caveat. For a five-parameter, fully documented calculation tool, an agent has everything needed to call it 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 description coverage is 100% and both enums are documented inline, so the baseline is 3. The description restates the parameter roles ('fixed yearly rate', 'chosen frequency') and the formula clarifies how the four required inputs interact, but it adds no syntax, default, or boundary 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?

States a precise verb+resource (what a single present amount grows to) and reinforces it with the exact formula FV = PV x (1 + r/n)^(n x t). It explicitly names the two closest siblings it is not (smartfin_project_savings_growth, smartfin_calculate_investment_return), so an agent can disambiguate without opening any 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?

Gives explicit when-to-use cases (a lump sum after some years, effect of compounding more often) and explicit when-not cases with named alternatives: regular contributions → project_savings_growth, actual stock performance → calculate_investment_return, and solving for another variable → calculate_missing_variable. Nothing is left to inference.

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?

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so safety is covered externally. The description adds genuine behavioral context the annotations cannot: the computation assumes one constant inflation rate rather than official index data, which bounds the trustworthiness of the result.

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, zero filler: what it computes, when to reach for it, when not to. The use-case and the caveat are front-loaded rather than buried.

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?

An output schema exists, so return-value detail is not the description's job, and annotations carry the safety profile. For a four-parameter calculator whose semantics are fully specified in the schema, the description supplies everything an agent needs to select and invoke it 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 description coverage is 100%, with units, ranges and enum values all documented in the schema itself (e.g. annual_inflation_pct as "Yearly inflation rate in %, e.g. 3", currency as display-only and never converted). The description adds no parameter-level meaning beyond that, so the 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?

The description states a concrete computation in both directions (eroded value of a sum, and the future cost of today's price) plus the rate basis, so the resource is unambiguous. It never names the conceptually adjacent siblings (smartfin_calculate_future_value, smartfin_calculate_present_value), which is the only thing keeping it from a 5.

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 an explicit trigger ("questions about buying power or future prices at an assumed inflation rate") and an explicit exclusion ("Do not use for historical CPI lookups: this uses one fixed rate, not official index data"). The when-not condition is exactly the kind of routing signal that separates this from index-based tools.

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?

Annotations already declare readOnly/idempotent/non-destructive/openWorld=false, so safety is covered. The description adds real behavioral context beyond that: data coverage limits (508 US-listed symbols, USD only, month-level periods) and methodology (split-adjusted, dividend-reinvested daily closes). It does not discuss latency, pagination, or failure modes, which keeps it just short of a 5.

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?

Purpose and strategy definitions are front-loaded, then examples, then exclusions, then limits – a logical order. The opening sentence is long and parenthesis-heavy, but nearly every clause carries load-bearing constraint information, so waste is minimal.

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 7-parameter tool with an output schema and full annotation coverage, the description supplies everything an agent needs: scope, strategy mechanics, exclusions against siblings, and domain limits. Return values are already covered by the output schema, so the brief return summary is sufficient.

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 baseline is 3, but the description adds meaning the schema lacks by defining each strategy enum value (lump_sum = all on first trading day, monthly = nearest trading day to the 1st, buy_the_dip = buys after a set % fall) and clarifying the adjusted-price basis. It does not add detail for dip_threshold_pct or dip_percent_per_buy 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?

States a precise verb+resource (what an amount invested became over a past period) and enumerates the three strategies it supports with their mechanics. It explicitly names the siblings it must not be confused with (compare_investment_strategies, project_savings_growth), so an agent can disambiguate without opening any 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?

Provides concrete trigger examples ('what would $5,000 in Microsoft since 2015 be worth' -> lump_sum, 'if I'd put money into SPY every month since 2010' -> monthly) and explicit when-not routing to two named alternatives. Nothing is left to inference.

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?

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely useful scope context that annotations cannot carry: what the figures exclude (taxes, insurance, fees) and which loan products are out of scope. It does not discuss rounding, payment timing, or amortization assumptions, which keeps it short of a 5.

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 tight sentences, each load-bearing: what it computes, how to supply principal, when to invoke, when not to. The result and routing conditions are front-loaded with zero filler.

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?

An output schema exists, so return values need no explanation, and annotations cover the safety profile. For a 7-parameter, 2-required calculation tool the description supplies everything an agent needs: output definition, input-mode rule, positive triggers, and hard exclusions.

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 baseline is 3, but the description adds cross-parameter meaning: the mutually exclusive loan_amount vs. home_price+down_payment_pct modes for mortgages, which is the main source of caller error. It does not add format or unit detail beyond the schema's own descriptions.

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 outcome (monthly payment, total interest, total paid) plus the exact loan class it covers, and names the distinction from siblings like mortgage_payoff and down_payment by scoping to fixed-rate amortizing loans. An agent can route correctly without opening any 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?

Gives an explicit trigger ('user asks what a loan costs per month or in total, or how the rate or term changes the cost') and explicit exclusions (variable-rate, interest-only, credit cards). It also states the input-mode rule: 'Give either loan_amount, or home_price with down_payment_pct for a mortgage.' Nothing is left to inference.

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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and closed-world, so the safety profile is covered. The description adds genuine interpretation context beyond that: one fixed rate is an assumption and a solved rate is arithmetic rather than an expected return. It does not discuss precision, rounding, or edge behavior when inputs are inconsistent, so it stops short of a 5.

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?

Purpose, formula, and usage trigger are front-loaded in the first two sentences. The exclusion sentence is a long run-on packing three alternatives plus a caveat, which slightly hurts scannability, but no sentence is wasted.

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?

An output schema exists, so return values need no explanation. The description covers the operation, the equation, the trigger condition, examples, and the sibling tools to use instead — everything an agent needs 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.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all seven parameters including enum meanings, bounds, and the 'leave out when solving for X' pattern. The description restates the four solvable quantities and maps present_value to 'the starting amount,' which is a marginal clarification rather than new information. Baseline 3 is appropriate when the schema does the heavy lifting.

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 (finds the one missing number) and resource (the four variables of FV = PV x (1 + r/n)^(n x t)), and even spells out the equation being solved. It distinguishes itself from siblings by naming smartfin_project_savings_growth, smartfin_calculate_investment_return, and smartfin_calculate_future_value as the wrong tools for adjacent tasks.

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 an explicit trigger condition ('Use when the user knows three of the four and wants the fourth') backed by three concrete natural-language examples. It also provides explicit exclusions with the replacement tool named for each, so routing decisions require no inference.

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?

Annotations already declare readOnly/idempotent/non-destructive, and the description adds real behavioral context beyond them: principal and interest only, taxes/insurance/escrow/prepayment penalties excluded, each extra payment applied to principal on its payment date, and no currency conversion. It also discloses the derived outputs, notably the 5-year/1-year-sooner minimum-extra calculation, which is non-obvious 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?

The purpose and usage guidance are front-loaded and the exclusions are crisp, but the second sentence is a long run-on that enumerates every return value in detail even though a full output schema exists — that enumeration is largely redundant and bloats the definition.

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 financial calculator with an output schema, the description covers what is needed: input mode constraint, unit/currency handling, what is excluded from the calculation, and stated assumptions about when extra payments apply. Nothing an agent needs to call it 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 coverage is 100% and the schema already carries ranges, defaults, and the years_left/monthly_payment either-or note, so the baseline is 3. The description reinforces the mutually exclusive constraint ('not both') and frames years_left as 'time left' and monthly_payment as 'principal and interest only (no escrow)', adding marginal interpretive value on top of 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?

States a specific verb and resource: computes how much sooner a fixed-rate mortgage ends with extra monthly, lump sum, or both, from today's balance. It explicitly names the sibling it is not for ('Do not use for the payment on a new loan (use smartfin_calculate_loan_payment)'), so an agent can separate it from the other calculate_* tools without opening a 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?

Gives explicit trigger conditions ('Use when someone asks how much sooner or with how much less interest extra payments or a lump sum pay off a mortgage'), explicit exclusions (refinancing, adjustable-rate/interest-only, pay-off-vs-invest), and the input rule 'Give the time left (years_left) or the monthly payment from the statement (monthly_payment), not both.' Nothing is left to inference.

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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description still adds real scope context beyond them: the tool holds no rate of its own and discounts exactly one amount at one fixed rate, which tells the agent this is a bounded single computation rather than a solver. It does not discuss precision or rounding, but the output schema is present.

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 definition and formula, then when-to-use, then exclusions, then the alternative. Three tight sentences with no redundant restatement of the name or title, and every clause carries routing or scope 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?

For a read-only single-formula calculator with a full output schema and 100% parameter documentation, the description supplies everything an agent lacks: the mathematical relationship, the scope limit (one amount, one fixed rate), and the sibling to use for the opposite direction. Nothing needed to select or call it 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 schema already documents future_value, annual_rate_pct, compounding_frequency, years and currency in detail. The description only echoes that the discount rate is user-supplied, adding no format or constraint detail beyond the schema. Baseline 3 applies when the schema does the heavy lifting.

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 (discount to present value) and resource (a single future amount), and even gives the formula PV = FV / (1 + r/n)^(n x t). It is clearly separable from smartfin_calculate_future_value, which it explicitly names as the inverse operation.

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 an explicit when-to-use (questions about the value today of money received later, at a user-supplied rate), three explicit when-not cases (picking a rate, multiple payments, market price), and names the alternative sibling for forward growth. Nothing is left to inference.

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?

Annotations already establish readOnly/idempotent/non-destructive, so the description wisely spends its budget on things annotations cannot convey: a negative margin is a valid result, the tool reports the figure without judging it, and the cost input is user-defined so gross vs net is undefined. It stops short of stating precision/rounding or failure behavior, so not a full 5.

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 output and formula lead, then usage, then caveats – properly front-loaded with no filler sentences. It is fairly dense at four sentences, and the closing gross/net sentence could arguably fold into the same-period sentence, keeping it just short of 5.

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?

An output schema exists so return values need no explanation, and annotations carry the safety profile. The description covers the remaining gaps – scope ambiguity (gross vs net), negative results, currency not being converted per the schema note, and sibling routing – leaving nothing an agent needs to call it 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 100%, so the baseline is 3 since the schema already documents revenue, total_costs and currency. The description still adds interpretation the schema lacks: both figures must cover the same period, and the cost figure's gross/net meaning depends entirely on the user, which changes how the result should be described.

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 (compute profit and margin %) and even spells out the formula, so the agent knows exactly what is produced. It explicitly contrasts itself with smartfin_calculate_roi, which is the closest sibling, and notes the required scope (two figures for the same period).

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 positive triggers (questions about profit as a share of sales), explicit exclusions (ROI, taxes, judging whether a margin is good), and the period-alignment precondition. This is a genuine when/when-not/alternative routing block rather than vague context.

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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description still adds real behavioral context: compounding conventions (balance earns a yearly return between withdrawals), frequency options, the lasts_forever edge case where 0% return yields no qualifying amount, and the caveat that returns are an assumption and taxes/fees are excluded.

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?

Dense and front-loaded: mode definitions precede usage cues and exclusions, and the tax/fee caveat closes cleanly. The opening clause about mirroring SmartFin's calculator is mildly redundant framing, but nothing else is padding.

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?

Nine parameters and two branching modes are handled, an output schema exists so return values need no explanation, and alternatives plus assumptions are covered. An agent has everything needed to select the right mode and required arguments.

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 per-parameter meaning is already documented and the baseline would be 3. The description earns above baseline by explaining the cross-parameter dependency structure (how_long requires withdrawal_amount; how_much requires years or lasts_forever), which the individual property descriptions do not state as a whole.

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 (calculating retirement withdrawals) and enumerates its two modes, how_long and how_much, with a one-line definition of each. It also names the sibling it is not (smartfin_calculate_fire_number), so an agent can disambiguate without opening another 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?

Explicit inclusion cues are given as quoted user phrasings ("how long will my savings last", "how much can I withdraw") plus an explicit exclusion routing to smartfin_calculate_fire_number. This is the when-to-use / when-not-to-use pattern at full strength.

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?

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the safety profile is covered. The description adds genuinely non-obvious behavior: negative results are valid, the figure is not annualized, and fees/taxes are the caller's responsibility to fold into final_value. Return format is left to the output schema, which exists.

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?

Formula and the 'negative results are valid / not annualized' caveats are front-loaded, then usage boundaries, then the fees/taxes caveat last. Every sentence carries distinct information; nothing is redundant with the title or annotations.

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 simple two-input calculator with a full output schema and complete annotation coverage, the description supplies everything an agent needs: formula, valid-input ranges implied by semantics, edge cases, and routing to alternatives. No material gap remains.

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 baseline is 3. The description adds interpretation value beyond the schema by clarifying that final_value may legitimately fall below initial_value and that fees/taxes must be embedded there, plus the non-conversion of currency.

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 and resource (calculate ROI), gives the exact formula, and states scope boundaries: 'not annualized', 'two values'. It clearly distinguishes itself from siblings like smartfin_calculate_investment_return and the CAGR calculator without requiring the agent to open any 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?

Explicit when-to-use ('questions about the total percentage return on money put in, from two values') and three explicit when-not-to-use cases, each with the correct alternative named (CAGR calculator link, smartfin_calculate_investment_return) plus handling guidance for fees/taxes. Nothing is left to inference.

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?

Annotations only establish the safety profile (readOnly, idempotent, closed-world), and the description adds substantial modeling context beyond them: rates are held constant every year, tax is taken as a simplified one-time assumption, fees are subtracted from return, balances are also shown in today's money, a fixed −2%/year case is included, and no currency conversion occurs. For a pure calculator this is unusually rich disclosure of assumptions and limits.

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?

Purpose and scope are front-loaded, and the paragraph follows a logical purpose -> inputs -> outputs -> examples -> exclusions order. It is somewhat long for a calculator, and the detailed enumeration of returned figures ('both modeled balances, money put in, interest, growth, fees and taxes...') partly duplicates the output schema, which costs a point.

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?

Given a 12-parameter tool with an output schema, the description covers everything an agent needs: modeling assumptions, which parameters are optional, the constant-rate simplification, the no-conversion currency rule, sibling alternatives, and the fact that it does not give a recommendation. Nothing material 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 schema already defines every parameter; baseline is 3. The description adds value by grouping the inputs into core (savings rate, investment return, both held constant) versus optional features (contribution step-up or inflation-linked, investment fee, interest/gains tax), which helps an agent understand how the 12 parameters interact before diving into 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?

States a specific verb and resource ('Compares the modeled balances of a savings account and of an investment') plus scope (1-50 years, same starting amount and contribution), and explicitly distinguishes itself from siblings by naming smartfin_compare_investment_strategies for historical returns. It also clarifies what it does not do ('does not say which option to choose'), so an agent can select it unambiguously.

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 concrete trigger examples ('how do 10,000 in savings at 4% and the same amount invested at 7% compare after 20 years') and explicit exclusions with the alternative tool named for each (historical index returns -> smartfin_compare_investment_strategies; account types/tax rules -> not modeled). This is textbook when-to-use / when-not-to-use 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?

Annotations already declare read-only, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds domain behavior beyond annotations: it is non-compounded simple interest and applies no taxes or fees, which helps set expectations for what the calculation includes.

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 definition, then use cases, then exclusions. Every sentence carries routing or calculation information, and there is no filler.

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 simple, read-only calculator with annotations and an output schema, the description provides enough context: what it computes, when to use it, when not to use it, and which alternatives handle those cases. Return-value details are appropriately left to the output schema.

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 schema already documents principal, annual_rate_pct, years, and currency. The description adds the relationship 'interest = principal x rate x time' and clarifies non-compounding, but it does not add per-parameter detail beyond the schema's own descriptions.

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 the exact computation: simple interest and final amount from principal, fixed yearly rate, and years. It also states the formula and distinguishes the tool from compounding, loan-payment, and tax/fee alternatives, so an agent can identify it precisely.

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 explicit positive use cases (simple interest on a loan or deposit, short-term note, flat-rate bond coupon) and explicit exclusions with named alternatives: compounding tools, loan-payment tool, and taxes/fees. This is exactly the when/when-not routing guidance needed among many sibling calculators.

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?

Annotations already declare read-only, idempotent, non-destructive, non-open-world behavior, so the safety profile is covered. The description adds genuinely useful context beyond that: the pricing basis (daily closes adjusted for splits and reinvested dividends), the coverage limits (US-listed S&P 500 names plus major ETFs, USD, month-level granularity), and an explicit caveat that results are period-dependent and not a prediction.

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?

Purpose and the three strategies are front-loaded before the usage guidance, and every sentence carries information. It is on the long side for a single paragraph, but the length is justified by three distinct strategies plus sibling routing; no filler sentences.

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 7-parameter analytical tool with an output schema present, the description covers methodology, universe constraints, granularity, usage routing, and interpretation caveats. An agent has everything needed to select and invoke it correctly without needing return-value details, since the output schema supplies those.

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 baseline is 3, but the description adds real meaning by defining what each strategy does — lump sum on the first trading day, monthly on the trading day nearest the 1st, and buy-the-dip after a set % fall from the latest high — which is exactly the semantics behind dip_threshold_pct and dip_percent_per_buy that the schema only names.

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 (runs one amount through three buying strategies) and resource (US stock/index ETF over a period), and explicitly differentiates from siblings by naming smartfin_calculate_investment_return and smartfin_compare_time_periods. The three strategies are enumerated concretely, so an agent knows exactly what is computed.

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 explicit when-to-use ('user asks which way of investing would have done better for a specific stock or index over a past period') and when-not-to-use cases with named alternatives for single-strategy and multi-period comparisons, plus an exclusion for future projections. Nothing is left to inference.

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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so credit is for added context: it explains the simulation mechanics (same cash, same monthly spend, difference invested), states key modeling limitations (rates held constant, income-tax effects and sale tax not modeled), and clarifies it reports modeled money only rather than a recommendation. The limitations are the valuable additions here.

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-loads the comparison method and behavior before usage guidance, which is well-ordered. However, the description is dense and lists many return fields (first-year crossover, break-even rent, monthly payment, month-one costs) in one long sentence that could be trimmed, especially since an output schema exists.

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?

Given a 21-parameter tool with an output schema and full annotations, the description covers the algorithm, limitations, exclusions, currency handling, and the distinction between modeled output and advice. Nothing material for correct invocation 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 every parameter is already documented with ranges and defaults. The description adds only high-level modeling context (currency never converted, rates fixed) rather than per-parameter meaning. Baseline 3 is correct when the schema does the heavy lifting.

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 (compares buying vs renting) and immediately distinguishes itself from siblings like calculate_savings_vs_investing by naming the exact methodology: fixed-rate mortgage vs investing the difference. An agent can select this 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.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly gives three triggering questions ('how renting and buying compare', 'how long they would need to stay', 'what rent matches buying a home') and four exclusions (rental-property investing, borrowing capacity, tax planning, ARMs). This is model when-to-use/when-not-to-use 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?

Annotations already declare readOnly, idempotent and non-destructive, so the safety profile is covered. The description adds substantive context beyond them: daily closing prices adjusted for splits and reinvested dividends, US-dollar denomination, skipped periods surfaced with a reason, and an explicit 'not a prediction' caveat. It stops short of stating rate limits or latency, which keeps it at a 4.

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 core operation, then usage routing, then limits. The long enumeration of periods is justified because the underlying enum values are opaque, but the single dense paragraph could be broken up and a few clauses ('Each row gives lump sum and monthly investing results...') lean toward return-format detail that the output schema already covers.

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 4-parameter read tool with an output schema, the description covers what an agent needs: scope, period definitions, ticker universe expectations, currency, skip behavior, and an explicit not-a-prediction boundary. Return-shape details are present but non-essential, and nothing material 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 baseline is 3. The description earns above baseline by decoding the cryptic enum labels into real semantics, mapping dotcom_peak, covid_low, low_2022 etc. to actual dates and explaining that they are S&P 500 closing highs and lows, plus clarifying that event dates are index-level while the ticker drives the result.

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: what a fixed amount in a named US stock or index ETF became across defined reference periods ending today or on as_of_date. It explicitly names the sibling it is not (smartfin_compare_investment_strategies) and enumerates the exact period set, so an agent can distinguish it without opening a 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?

Gives positive triggers ('how a stock did over several time frames', or naming a moment like 'from the COVID low') and an explicit exclusion with the correct alternative for custom start months. Nothing about when to reach for this tool is left to inference.

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?

Annotations cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description goes well beyond them: it discloses the exact computation basis, that both series start on the same trading day with later-start tickers truncating both, and that the summary flags this. It also clarifies the tool never picks a winner, which is a genuine behavioral constraint.

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 purpose, then usage, then limits, and essentially every clause carries information. It is a very long run-on sentence, which slightly hurts scannability, but there is little filler to cut.

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?

Despite six parameters, a complex return shape, and date-alignment edge cases, the description covers scope limits, alignment rules, monthly-contribution behavior, and the no-recommendation guarantee. With an output schema present, return formatting need not be re-explained, and nothing an agent needs to call it 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; the description nevertheless adds real meaning beyond the schema by explaining the monthly_amount mechanics (added once per 1st of month after start, executed on the nearest trading day) and the shared-start-date alignment behavior, which the schema does not spell out.

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 (compares two US-listed stocks or index ETFs on identical dates) and pins down the methodology (split-adjusted closing prices, dividends reinvested). It explicitly names the siblings it is not (smartfin_calculate_investment_return, smartfin_compare_investment_strategies), so an agent can route without opening schemas.

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 concrete positive triggers ('apple vs microsoft stock over 10 years', 'voo vs qqq since 2015') and explicit exclusions with the correct alternative named for each (one stock, buying strategies, future returns, buy recommendations). Limits on coverage (S&P 500 + major ETFs only) are stated up front.

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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, not open-world), so the bar is lower; the description still adds real context: free, no sign-up, no cookies or tracking, the widget fills its container width, and it follows the reader's light/dark mode. What it does not cover is the exact shape of the returned HTML or any sizing/attribute caveats, which is the only remaining gap.

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 value proposition (one iframe line, free, no sign-up, no tracking) and the routing rules are front-loaded, and the closing exclusion sentence is well placed. The 21-item calculator enumeration is bulky, but it is partly justified because it annotates bare enum keys with display names.

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 an output schema present, return-value explanation is not required, and the description covers purpose, trigger, exclusion, embed properties, and the calculator catalogue. Currency behavior is left entirely to the schema, and no guidance is given on placement or sizing caveats beyond width-filling, leaving a small completeness gap.

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% and both parameters have enums, so the schema carries the syntax burden (baseline 3). The description adds value by mapping every cryptic enum key to a human-readable calculator name (e.g. rule_of_72 → 'Rule of 72 calculator'), which helps the agent pick the right one; the currency parameter itself is not elaborated in the description.

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 deliverable ('The HTML to put one of SmartFin's free calculators on a website') and immediately differentiates from the sibling smartfin_calculate_* tools by declaring it is not for computing anything. An agent can route correctly 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.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives an explicit positive trigger ('Use when the user wants a calculator on their own site or asks how to add one') and an explicit exclusion with the alternative ('Do not use to calculate anything (use the other smartfin_ tools)'). Both when-to-use and when-not-to-use are covered.

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?

Annotations already establish readOnly/idempotent/non-destructive, and an output schema exists, so the description's remaining burden is light. It still adds genuine value by calling out what the result contains (balance, total paid in, interest earned) and, importantly, framing the fixed rate as an assumption rather than a forecast — a real interpretive caveat. It stops short of behavioral detail like sign conventions for negative rates, but that is minor here.

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 sentences, each earning its place: purpose, output, use-case routing, and a caution. The scoping and the sibling alternative are front-loaded rather than buried.

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?

A read-only, idempotent calculator with a full output schema and 100% parameter documentation. Purpose, routing, and the interpretive caveat are all present; nothing an agent needs to call it 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% and two parameters carry enums with defaults, so the schema does the heavy lifting. The description echoes 'monthly contributions' and 'compounding frequency' but adds no format, default, or interaction detail beyond what the schema already provides. 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?

The opening sentence states a specific computation — future balance of savings/investment at a fixed yearly rate with optional contributions and compounding — and the exclusion clause names the sibling it must not be confused with (smartfin_calculate_investment_return). An agent can distinguish this from the ~19 other calculators without opening any 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?

Explicit when-to-use ('forward-looking how much will I have questions at an assumed rate') and when-not ('what a real stock did in the past'), with the alternative tool named. Nothing is left to inference.

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