SmartFin

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

Beyond the read-only, idempotent, non-destructive annotations, the description discloses the calculation model, the 60-year search limit, that returns and inflation are assumptions, and that taxes are excluded. This is rich behavioral context that tells the agent what the tool actually computes and its limitations.

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 but front-loaded with the core calculation, then use cases and exclusions. It is appropriately sized for a multi-output financial model, though the single long paragraph could be more scannable with minimal restructuring.

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, 100% parameter coverage, and rich annotations, the description still provides the calculation assumptions and exclusions an agent needs to call the tool correctly. Nothing essential about inputs, behavior, or output scope 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, but the description adds meaning about how parameters interact: annual_savings is added each year, expenses and FIRE number rise with inflation, and expected_return_pct and withdrawal_rate_pct drive the model. It does not map each parameter individually, but the added model context earns a 4.

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 calculation (FIRE number today as yearly expenses divided by a safe withdrawal rate) and the simulation that finds the first year savings reach that number. It explicitly distinguishes itself from smartfin_calculate_retirement_withdrawal, so an agent can identify its unique purpose 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?

It gives explicit example questions ('how much do I need to retire', 'when can I retire', 'what's my coast FIRE number') and a direct exclusion with the alternative tool to use instead. The when-to-use and when-not-to-use guidance is unambiguous.

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 this as a read-only, idempotent, closed-world calculation. The description adds a genuine behavioral constraint beyond them: the rate is a single fixed value rather than a varying official index, which materially changes what the result means. It does not discuss rounding, sign handling for negative rates, or result precision, keeping 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?

Two sentences, no filler, with the computation stated first and the exclusion second. Slightly dense in its opening clause, but every phrase earns its place and nothing is repeated from annotations or 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 present, the description need not explain return values, and annotations cover the safety profile. The three required parameters are fully documented in the schema. What remains unique to the description — the fixed-rate assumption and the sibling distinction — is present, so an agent has everything needed to call and interpret 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% with per-parameter descriptions ('Yearly inflation rate in %, e.g. 3'), so the schema carries the parameter burden. The description reinforces the fixed-rate interpretation of annual_inflation_pct but adds no format, unit, or edge-case detail (e.g. negative-rate behavior) beyond the schema. 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 gives a specific dual computation: discounted present value of an amount after inflation, and the future cost of something costing that amount today. It names the domain (buying power, future prices) and explicitly contrasts itself with historical CPI tooling, so it is distinguishable from siblings like compare_time_periods.

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 states the triggering context ('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'). That is a when-to-use plus a when-not-to-use with the reason.

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 non-structured behavior: real daily closing prices adjusted for splits and reinvested dividends, the exact trigger/buy semantics of each strategy, and hard coverage limits (508 US-listed symbols, USD, month granularity). Return-value explanation slightly overlaps the output schema, keeping it from 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?

Front-loaded with the core definition, then usage examples, then exclusions, then limits – a sensible priority order with no filler. The opening sentence is long and clause-heavy, but every clause (strategy semantics, price data, dividend/split adjustment) earns its place.

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, the description supplies the missing dimensions: methodology, universe limits, currency, and temporal granularity, and it routes to the correct siblings. An agent has everything needed 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 coverage is 100%, so the baseline is 3, but the description goes beyond the schema by defining the three strategy enum values operationally (lump_sum = all on first trading day, monthly = nearest trading day to the 1st, buy_the_dip = buys after set % falls from latest high), which the terse enum description 'Which way of investing' does not. dip_threshold_pct and dip_percent_per_buy are described in-schema but not in prose.

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 (past return of one investment strategy) and immediately names the two sibling tools it must not be confused with. An agent can separate it from smartfin_compare_investment_strategies and smartfin_project_savings_growth 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 examples ('what would $5,000 in Microsoft since 2015 be worth' for lump_sum; 'money into SPY every month since 2010' for monthly) plus explicit when-not-to-use 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 establish readOnlyHint, idempotentHint and openWorldHint=false, so the safety profile is covered by structured data. The description adds genuinely useful scope beyond that: the tool is limited to fixed-rate, monthly-payment loans and explicitly excludes taxes, insurance and fees, which is important context an agent cannot derive from the annotations. It does not need to describe return values since an output schema 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?

Front-loaded with the output and the scope, then trigger conditions, then exclusions, then caveats. Every sentence carries distinct information and none restate the name or title.

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 6-parameter schema at 100% description coverage, an output schema handling return values, and full annotations, the remaining burden on the description is scope and applicability, both of which are covered, including the fixed-rate assumption and the excluded cost components.

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 goes further by clarifying the two alternative input paths ('loan_amount, or home_price with down_payment_pct for a mortgage') in a single readable sentence, which helps the agent choose the right parameter combination rather than just reading each field in isolation.

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?

Opens with a specific verb-plus-resource statement ('Monthly payment, total interest and total paid for a fixed-rate loan with monthly payments') and immediately enumerates the loan categories it covers. An agent can distinguish it from siblings like smartfin_calculate_investment_return or smartfin_calculate_retirement_withdrawal 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 positive triggers ('Use when the user asks what a loan costs per month or in total, or how the rate or term changes the cost') and explicit exclusions ('Do not use for variable-rate loans, interest-only loans, or credit cards'). The when-to-use and when-not-to-use conditions are both stated, leaving nothing 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 this is a read-only, idempotent, non-destructive local calculation, and the description usefully adds that returns are an assumption and that taxes and fees are excluded, plus the compounding/frequency model. It stops short of detailing output shape or edge-case behavior, but adds genuine context beyond the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the shared model, then the two modes, then usage and exclusions in a compact block. Slightly dense with parenthetical asides, but every sentence carries information and none 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?

With an output schema present, return values need not be explained. The description covers the two modes, defaults, assumptions, and routing, which is sufficient for a read-only calculation tool; only minor model details (e.g. timing of withdrawals vs. return) are unstated.

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 parameters are already fully documented, and the baseline of 3 applies. The description reinforces the how_long/how_much parameter dependencies (inflation, lasts_forever) but adds little beyond what the schema entries already state.

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 capability (retirement withdrawal projection) and clearly delineates its two modes, how_long and how_much, with concrete meanings for each. It also explicitly names the sibling it is not (smartfin_calculate_fire_number), so an agent can route correctly.

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 explicit trigger phrases ('how long will my savings last', 'how much can I withdraw') and an explicit exclusion with the alternative tool to use instead for a savings target. When-to-use and when-not-to-use are both 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 declare a safe read-only, idempotent, closed-world operation. The description goes beyond them by specifying the data source and adjustments (real daily closing prices, split-adjusted, dividends reinvested), the output metrics, and hard limits (US-listed S&P 500 plus specific ETFs, USD only, month-level granularity, results are period-dependent and not a prediction). It does not mention performance or rate limits, keeping it from 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?

The description is front-loaded with the core operation before usage guidance, exclusions, and limits. Every sentence contributes necessary information—no filler—and the structure moves logically from what it does to when to use it to what it cannot do.

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 7-parameter tool with an output schema, the description covers purpose, alternatives, data scope, output metrics, and key caveats. An agent needs nothing more to decide to invoke it and interpret the results 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 every parameter in detail, including meanings of dip_threshold_pct and dip_percent_per_buy. The description explains what the three strategies mean conceptually but adds no syntax or format 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?

The description states a specific verb (runs/compares) and resource (three investment strategies on real daily closing prices) and explicitly distinguishes itself from sibling tools like smartfin_calculate_investment_return and smartfin_compare_time_periods. An agent can immediately tell this is a multi-strategy comparison, not a single-return or multi-period tool.

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 when-to-use (‘which way of investing would have done better…over a past period’) and when-not-to-use cases with named alternatives for each (‘Do not use for one strategy only (use smartfin_calculate_investment_return), for several reference periods at once (use smartfin_compare_time_periods), or for future projections’). No inference is required.

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 readOnly/idempotent/destructive/openWorld, so the safety profile is known. The description adds genuine context beyond them: results are computed on daily closing prices adjusted for splits and reinvested dividends, event dates are S&P 500 closing highs/lows, and periods predating the ticker's history are skipped and reported with a reason. Data basis and skip behavior are the valuable additions.

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 purpose and mostly information-dense, but the inline enumeration of every period and its date makes the opening sentence very long. Each element earns its place, yet the structure could be tightened 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?

With an output schema present and rich annotations, the description need not explain return values, and it still covers the edge cases that matter: skipped pre-history periods, currency (US dollars), and the non-predictive framing. Nothing an agent needs to invoke this correctly is missing, and it names the sole alternative for custom windows.

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 goes further by mapping period keys to real dates (dotcom_peak = 24 Mar 2000, crash_2009_low = 9 Mar 2009) and stating the amount default of 1000, meaning the individual enum values in the schema gain semantics they lack on their own.

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: what a fixed amount in a US stock or index ETF became across named reference periods. It enumerates the exact periods, including their anchor dates (dot-com peak 24 Mar 2000, COVID low 23 Mar 2020), so an agent knows precisely the scope without opening the schema. Clearly distinct from sibling calculation tools.

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 ('the user asks how a stock did over several time frames, or names one of these moments') with concrete example phrasings, and an explicit exclusion ('Do not use for a custom start month (use smartfin_compare_investment_strategies)') that routes to the correct sibling. Both the positive and negative conditions are 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?

Annotations already establish readOnly/idempotent/non-destructive/closed-world, and the description adds non-obvious traits: free, no sign-up, no cookies or tracking, responsive width, and light/dark mode following. It does not describe response shape or any failure modes, but with an output schema present that gap is minor.

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, benefits, and the use/don't-use rule are front-loaded effectively, but the eleven-item calculator enumeration largely duplicates the enum already in the schema, making the description longer than it needs to be for an agent.

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 rich annotations, a 100%-covered schema, and an output schema documenting the returned snippet, the description supplies the remaining decision-relevant context (what the widget looks like, that it is free and untracked, and the sibling exclusion). Complete enough for correct selection and invocation.

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 params have enums, so the baseline is already met; the description goes further by pairing each calculator key with a human-readable label and by explaining the widget behavior that currency selection affects. Adds meaning beyond the raw enum list.

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: returning the HTML snippet that embeds a SmartFin calculator on the user's site, and names the scope (one iframe line). It also explicitly separates itself from the calculation siblings, so an agent can route 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 both when to use ('user wants a calculator on their own site or asks how to add one') and when not to ('Do not use to calculate anything (use the other smartfin_ tools)'), naming the alternative family. 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, closed-world, so the safety profile is covered by structured data. The description adds genuine context beyond that: it names the returned quantities (balance, total paid in, interest earned) and warns that a fixed rate is an assumption, not a forecast. It does not discuss edge cases like negative rates, but the assumption caveat is a meaningful addition.

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 dense sentences: purpose and mechanics first, then return values, then routing and the caveat. No filler, and the most decision-relevant content 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?

With an output schema present the description need not explain returns, and it still names them briefly. Annotations cover safety, schema covers all five parameters, and the description covers purpose, routing, and the assumption caveat — nothing an agent needs to invoke 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 each parameter is already documented in the schema (including the enum mapping for compounds_per_year and default notes). The description references monthly contributions and compounding frequency but adds no format or constraint detail beyond the schema, 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?

The description states a specific computation ('future balance of savings or investment growing at a fixed yearly rate') with named modifiers (monthly contributions, compounding frequency) and cites the distinguishing sibling smartfin_calculate_investment_return. An agent can differentiate it from the other smartfin_* calculators 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?

It gives 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'), and names the alternative tool for the excluded case. Both the positive and negative routing conditions are stated.

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