PoliErgaleio

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

With no annotations provided, the description carries the full behavioral burden and does so: it states the read-only boundary ('Never create transactions or holdings records'), defines the null-and-reason behavior when pre-flow valuations are absent, explains internal-transfer netting for combined TWR and the requirement to confirm both legs, and discloses the 'performance-from-today' fallback when acquisition cost is missing. These are non-obvious edge-case behaviors an agent could not infer from the schema.

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

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

Front-loaded with the purpose and output list, then prerequisites, then edge cases — a sensible ordering. The middle-to-end sentences are dense run-ons stacking several conditional behaviors, which costs some scanability, but almost no content is redundant.

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 multi-sleeve calculation tool, the description covers inputs, prerequisites, and the trickiest modeling decisions, and an output schema exists so return values needn't be spelled out. A minor remaining gap is the absence of any note on failure modes or partial results beyond the TWR-null case.

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 earns above that by tying FX rates to per-transaction granularity and explaining that TWR requires a valuation immediately before each later external cash flow and at the end date — semantics the 'Value' enum and valuation items alone don't convey. It does not further clarify asOfDate or baseCurrency 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 specific verb and resource ('Analyses an investment portfolio from its transaction history') and then enumerates the exact outputs: net invested capital, current value, absolute return, TWR, CAGR, per-sub-portfolio breakdown and allocation shares. This is clearly distinguishable from siblings like parse_portfolio_csv or compare_investment_vehicles, which parse or compare rather than compute portfolio performance metrics.

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 applicability condition: 'Use to analyze actual portfolio ledgers or current holdings and valuation data,' and follows with prerequisites (real transactions/holdings, a current valuation per holding, FX rates where currencies differ). What it lacks is sibling routing — it never says to use parse_portfolio_csv first to obtain the ledger, or that compare_investment_vehicles handles cross-vehicle comparison.

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

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

With no annotations, the description carries the burden and does well: it explains the internal fitting procedure, that results are ranked by RMS error, and crucially that inferred day-count and capitalisation conventions are estimates rather than confirmed bank terms. It omits runtime/cost expectations for a grid search over up to 2000 rows, which keeps it out of 5 territory.

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 mechanism, then prerequisites, then the accuracy caveat — a sensible ordering. The opening sentence is long and clause-heavy, but every clause describes a distinct part of the computation rather than 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?

An output schema exists, so return shape need not be described. The description covers inputs, fitting methodology, and interpretive limits, which is enough for a nested-schema, four-parameter analytical tool. A note on how confidence degrades with few checkpoints would have completed it.

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 still adds real meaning by stating that the rows must be chronological with at least one ratePct and that balance checkpoints are what the fit uses. Those constraints are not obvious from the schema alone, so it edges above baseline.

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 concrete verb and resource ("forensic audit of a mortgage statement") and then specifies the mechanism: day-by-day replay, grid search over day-count/capitalisation/rounding conventions, RMS ranking, and overcharge reporting. This is clearly distinguishable from the sibling parse_mortgage_statement_text, which only extracts data, and from simulate_mortgage, which projects rather than audits.

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?

"Use to audit an actual mortgage statement" plus explicit preconditions (statement rows, at least one usable rate, sufficient balance checkpoints) tells the agent when the tool applies and what makes an input valid. It stops short of naming the alternative parse tool or saying when not to use it, so it earns a 4 rather than a 5.

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

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

With no annotations, the description carries the full behavioral burden and does well: it discloses year-specific rule selection, the 20% CGT rate, CPI indexation, the 0.4% transfer fee, the EUR modelling-convention default, and the non-inference rule for first-disposal eligibility. It stops short of describing error behavior or result shape, but an output schema exists to cover returns.

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, with the core purpose in the first clause and defaults and pitfalls after. There is mild redundancy between the opening sentence and 'Use for Cyprus capital-gains tax on an immovable-property sale', which restates the purpose without adding 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 an 8-parameter tax calculator with full schema coverage and an output schema, the description supplies everything an agent needs: when to use, defaults, year selection, exemption-claim semantics, and instructions to elicit missing required inputs rather than guess.

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 3 is the baseline; the description goes slightly beyond it by flagging which inputs are essential to collect (acquisition price/year, disposal tax year, sale price, property type) and by framing the currency default as a modelling convention rather than a real-world assumption. The remaining parameters (agentFees, isFirstDisposal) are left to 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 (calculates Cyprus Capital Gains Tax on an immovable property disposal) and pins the scope to 2025/2026 rules. This is unambiguously distinct from siblings like calculate_cyprus_income_tax, so an agent can select it 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 says 'Use for Cyprus capital-gains tax on an immovable-property sale' and instructs the agent to ask for missing essentials rather than fabricate values. It also clarifies the default-to-2026 rule and that omission of isFirstDisposal means no exemption is claimed. It does not name an alternative tool to use when the disposal is outside Cyprus, but no sibling is close enough to be a likely confusion.

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

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

With no annotations, the description carries the full burden and does so well: it warns that 2026 rules are a default that must be flagged, states that optional inputs must come from the user, and forbids inferring exemption eligibility. It omits nothing obviously safety-critical for a pure calculator, though it adds no note on computational assumptions/rounding or error 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?

Front-loaded with purpose and preconditions, which is good, but it repeats itself: the qualifying-remuneration/rent rule for employee SI and the €180,000 GESY ceiling are each stated twice in near-identical phrasing. Trimming the duplication would lose no 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 33-parameter, nested-object calculator with an output schema, the description supplies the required inputs, the employment-category semantics, the default-year caveat and the no-inference rules. Return values are covered by the output schema, so nothing essential is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

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

Schema coverage is 64% on 33 params, and the description compensates by explaining the required path: gross annual salary in EUR with explicit 0 for self-employed-only cases, plus turnover and occupational category for sole proprietors. It adds real meaning for the two required parameters but leaves many optional deduction/relief fields (evExpense, energyEfficiencyExpense, homeInsurancePremium) entirely to 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 (calculates) with a precise set of outputs: Cyprus income tax, employee/self-employed SI, GESY and take-home pay. This clearly separates it from siblings like calculate_cyprus_capital_gains or calculate_cyprus_state_pension, which cover different tax domains.

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 scopes usage to 'a Cyprus resident or non-resident employee or sole proprietor tax estimate' and adds hard prerequisites: confirm monthly vs annual salary and employment category, do not infer either. It does not name sibling alternatives or when-not conditions, but the applicability conditions for calling are unusually concrete.

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

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

With no annotations, the description carries the full burden and discloses key assumptions: 2026 tax bands, projected SI rate increases in 2029/2034/2039, dependants handling, and anti-inference of contribution history. It does not state determinism, error behavior, or side effects (though a calculator is implicitly pure), leaving minor gaps.

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 and usage, but the first sentence and the second sentence redundantly restate what the tool estimates. The guidance is otherwise dense and earns its place, but trimming the duplication would improve conciseness.

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 7 parameters, conditional requirements, no annotations, and an existing output schema, the description covers modes, required inputs, assumptions, and anti-inference rules well. It does not elaborate on edge cases like out-of-range retirementAge or on the exact nature of the returned result, though the output schema handles the latter.

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. The description adds cross-parameter semantics beyond the schema: mode and retirementAge are always required; quick mode needs currentAge, yearsWorked, totalInsuranceUnits; advanced mode needs yearlyUnits. It also reinforces that yearsWorked/totalInsuranceUnits must not be inferred and that legacy unit maps are accepted.

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 (estimates), resource (Cyprus state contributory pension amount at retirement), and the exact basis (insurance units, contribution history, 2026 tax bands). This clearly distinguishes it from siblings like get_pension_reference_data, parse_pension_statement, and run_retirement_stress_test.

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 says when to use it ('Use to estimate contributory Cyprus state pension entitlement'), and provides detailed conditional guidance for quick vs advanced mode, required fields per mode, and the dependants assumption. It also instructs never to infer contribution history and to ask only for missing essentials.

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

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

With no annotations, the description carries the full burden and does so: it discloses the rate structure (60% basic, +20pp spouse, +10pp per dependant capped at three), the supplement formula and its cap at one weekly basic insurable earning, and the graceful-degradation rule of reporting 'entitlement undetermined' plus asking each missing question. This is well beyond what the schema reveals.

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 formula and guardrails are front-loaded and useful, but the opening sentence and the following 'Use to estimate…' sentence restate the same purpose, and the eligibility checklist is repeated across two sentences. Modest redundancy costs it 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?

For a 10-parameter calculator with an output schema, this is complete: the description supplies the domain rules, the required-input story, the eligibility criteria, and the missing-data behavior. Return values are covered by the output schema, so no 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 coverage is 100%, so the baseline would be 3, but the description adds genuine semantic value by explaining how parameters combine (percentage-point additions, per-dependant weighting, cap at three, the supplement being 50% of supplementary earnings). It does not, however, map every one of the ten parameters to its role, leaving some entitlement fields to the schema alone.

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 (estimates) and resource (Cyprus unemployment benefit), and explicitly splits the tool into two functions: amount estimation and separate entitlement assessment. This distinguishes it clearly from sibling calculators such as calculate_cyprus_income_tax or calculate_cyprus_state_pension.

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 preconditions for the calculation path (claim date, relevant-year insurable earnings, dependants) and the entitlement path (insurance history, employee status, registration, availability for work). It also names a prohibition — 'Do not infer those facts from annual earnings' — and prescribes fallback behavior when facts are missing.

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

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

With no annotations, the description carries the burden and does well: it discloses the conditional dependency (solar share requires spare solar production) and the output caveat that omitting extraEvCost suppresses the payback estimate. It does not describe the shape of the returned savings series, though an output schema exists to cover that.

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, front-loaded with the computation and then the data-gathering rules. The sentence 'Use to compare EV and petrol/diesel running costs' largely restates the opening and is mild redundancy, but nothing else 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?

For a 20-parameter calculator with an output schema, the description covers the collection policy, the conditional requirements, and the one output caveat, which is everything an agent needs to invoke it correctly. Units and defaults are handled by the schema, so no 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 coverage is 100%, so the parameter meanings are already given; the description adds genuine value beyond that by explaining the cross-field condition (solarDirectShare > 0 requires spareSolar) and the optionality semantics of extraEvCost. It could have said more about how the three charging shares interact, which keeps it from a 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb and resource: compares annual running cost of an EV against a petrol/diesel car in Cyprus, with the charging split (solar, home grid, public) and outputs (yearly savings, payback on extra purchase cost). This clearly distinguishes it from siblings like compare_rent_vs_buy or compare_investment_vehicles without needing to open 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?

Gives concrete invocation guidance: ask for annual distance, consumption, fuel price, charging shares and tariffs, and require spare solar production when solar charging is selected. It also says to reuse supplied facts and only ask for missing essentials. It does not name sibling alternatives or say when NOT to use it, so it falls short of a 5.

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

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

No annotations are provided, so the description must carry behavioral disclosure; it discloses the compared rule sets, the 2x salary annual cap, the €1m rolling 10-year cap, and the hard gate against presenting figures before status confirmation. It still does not explicitly say whether the tool is purely computational or has any side effects, leaving a small gap for a no-annotation tool.

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

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

The first sentence front-loads the comparison and the following sentences cover prerequisites and guardrails, so structure is good. However, 'Use to compare...' repeats the opening purpose and the confirmation rule is restated in multiple ways, making it longer than necessary.

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 tax calculator with 100% schema coverage and an output schema, the description supplies the rule context, caps, currency, and required confirmation gate. It is nearly complete, but without annotations it could explicitly state that the operation is a pure calculation with no persistence or side effects.

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 explains all six parameters, including the optional prior10YearOptionIncome. The description reinforces salary/status meaning and currency but does not add parameter-level detail beyond the schema, and it omits any prose mention of the optional prior-income parameter.

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 uses a specific verb, 'compares', and a precise resource, 'Cyprus tax on an employee stock option exercise', naming the two rule regimes and caps. Although it does not name sibling tools, the stock-option scope is distinct from the other Cyprus tax calculators in the sibling list.

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 when to use ('to compare Cyprus tax on an employee's share-option exercise') and gives a clear precondition: require confirmed approved-scheme status and ask if missing rather than infer. It does not explicitly route to alternative sibling tools such as calculate_cyprus_income_tax, so it is not a full 5.

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

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

With no annotations, the description carries the full behavioral burden and does substantial work: it discloses the cost-matching method (equalizing true out-of-pocket cost), the fee/tax mechanics applied (entry/exit fees, AUM fees, first-year commission, exit tax), and flags that forecast returns and omitted fee/tax inputs are modelling assumptions rather than user facts. The explicit prohibition on inventing personal contribution amounts is valuable guardrail context. It stops short of describing result shape or horizon behavior, though 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 comparison definition and followed by usage, prerequisites, and assumption warnings in a logical order. The second sentence ('Use to compare taxable investment with a tax-deductible investment vehicle') largely restates the first and could be merged, but no sentence is otherwise 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?

For a 14-parameter financial modelling tool with no annotations, the description covers required inputs, fee/tax mechanics, assumption policy, and the no-invention guardrail; return values are covered by the output schema. What remains thin is guidance on the many optional fee/tax parameters (e.g., when an omitted value is safe versus must be asked for), though the schema descriptions carry that detail.

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 would be 3, but the description adds a genuinely non-obvious semantic: the two options are compared at matched out-of-pocket cost, which explains why only option 2's gross contribution is required. It also names the three required inputs, reinforcing which fields cannot be defaulted.

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 a taxable investment (option 1) against a tax-deductible vehicle such as a provident fund or life-insurance savings plan (option 2). The scope is narrow enough that an agent can distinguish it from neighbors like compare_rent_vs_buy or analyze_portfolio 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 says when to use it ('Use to compare taxable investment with a tax-deductible investment vehicle') and names the three inputs that must be present (annual contribution, tax-relief rate, option 2 management fee). It adds an operating rule — reuse supplied facts and ask only for missing essentials — but gives no when-not guidance or named alternative for cases outside this comparison.

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

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

With no annotations, the description carries the burden and does well: it discloses mortgage payoff behaviour, symmetric investment of cost differences, included cost categories, and requires a post-calculation summary of defaults and exclusions via structuredContent.assumptions. It stops short of stating whether the calculation is pure/read-only or persisted, which is a meaningful gap for a tool with save/update siblings.

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 length is warranted for a 28-parameter financial model, and purpose is front-loaded. There is some redundancy around the deposit-unit rule ('never infer the unit' repeated in different phrasing), but no sentence is idle.

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 28 parameters, no annotations, and an existing output schema, the description covers the decisions an agent must make before calling: required core terms, ambiguity handling, assumption acceptance, and disclosure of defaults/exclusions. Return-value explanation is correctly delegated 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 coverage is 100%, so the schema already documents the 28 parameters; the description adds real value by mandating clarification of the downPayment unit, forbidding unit inference, and requiring acceptance of optional growth/inflation/return assumptions. That goes beyond the schema's per-field text and addresses the two most error-prone parameters.

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 a home against renting') and pins the scope to a Cyprus home over a stated horizon. The modelling stance (actual period mortgage payments, symmetric investment of the lower-cost side) distinguishes it from siblings like simulate_mortgage 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?

Explicitly restricts use to rent-vs-buy over a stated horizon, forbids carrying values from other chats, and enumerates the required core terms that must be asked for if missing. It also names the alternative behaviour for ambiguous deposit units and requires user acceptance for unstated assumptions.

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

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

With no annotations, the description carries the full burden and does disclose a real output behavior: encrypted sides 'report locked instead of contents,' which the agent cannot learn from the schema or output schema alone. It leaves unstated whether the tool is strictly read-only and what happens if an id is missing or invalid, so it stops short of full behavioral disclosure.

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 short sentences, front-loaded with the core action, then the routing guidance, then the edge-case caveat. There is no filler or repeated 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?

The output schema covers the return shape and the schema covers both parameters, so the description is nearly complete for a two-arg read tool. Minor gaps remain around failure behavior for unknown ids and the meaning of diff direction.

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 UUID parameters are already documented in the schema, so the baseline is 3. The description adds only that these are saved calculations being compared, which is already implied, and does nothing with directionality (whether A is the baseline and B is the comparison).

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 ('Diffs two saved calculations') and narrows the scope to inputs and results field by field. It also implicitly separates itself from load_saved_calculation, which the agent would otherwise need to reason about.

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 use case ('compare my mortgage before/after' style questions) and an explicit alternative to avoid ('instead of reconstructing the diff from two loads'). The selection condition between this tool and the sibling load_saved_calculation 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?

With no annotations, the description must carry the full behavioral burden. It usefully discloses ownership scoping and that encrypted saves are also deletable, but never states that the deletion is permanent/irreversible or what happens when the ID is unknown or already deleted — significant gaps for a destructive operation.

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 short sentences, front-loaded with the action and scope, then the trigger, then the encrypted-save caveat. Every sentence carries 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?

An output schema exists, so return values need not be explained, and the single param is fully documented. But for a destructive tool with zero annotations, the description omits irreversibility and failure behavior, leaving the agent without the confirmation context it would need.

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 single parameter is documented as "ID returned by list_saved_calculations," so the schema does the work. The description adds nothing about the ID format or provenance beyond it, which is the baseline case.

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 ("Deletes one saved calculation") plus a scoping constraint ("belonging to the authenticated API key's user"). The singular "one" implicitly separates it from list_saved_calculations and compare_saved_calculations, though no sibling is named explicitly.

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?

"Use when the user asks to delete or forget a saved scenario" gives a clear, concrete trigger condition. It lacks any when-not guidance or pointer to alternatives such as update_calculation for modification versus deletion.

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

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

No annotations are provided, so the description must carry behavioral disclosure. It conveys that this returns 'official' tables (provenance/authoritativeness) and strongly implies a side-effect-free lookup, but never states it is read-only or describes failure handling for unavailable years or out-of-range inputs. Adequate but with clear gaps for a zero-annotation tool.

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

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

The scope is front-loaded in the first sentence, but the second sentence largely restates it ('retrieve official Cyprus social-insurance reference figures for a user-specified calendar year') rather than adding new information. Only the final clause about not assuming the year earns its place beyond sentence one.

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 one-parameter, fully documented lookup with an output schema, the description covers purpose, sourcing, and year-selection behavior well enough to call it correctly. Missing only edge-case behavior (what happens for years with no published table or outside the 1981+ range).

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?

With a single parameter at 100% schema coverage the baseline is 3, but the description genuinely adds semantics: it tells the agent to reuse a year already provided and not to guess the applicable tax/reference year. That is guidance the schema's bare 'Reference year' field does not supply.

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 — returning official Cyprus Social Insurance reference tables for a given year — which is clearly a data lookup rather than a calculation, distinguishing it from siblings like calculate_cyprus_state_pension or calculate_cyprus_income_tax. It does not explicitly name an alternative sibling, so it stops short of 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?

Gives usable when-to-use context ('retrieve official Cyprus social-insurance reference figures for a user-specified calendar year') plus concrete behavioral guidance: reuse a year already supplied rather than re-asking, and don't assume which tax/reference year applies. No explicit exclusions or named alternatives, so not a 5.

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

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

With no annotations, the description carries the full burden and does add real value: it states the data is scoped to the authenticated user (an auth requirement) and that encrypted contents are never returned. It says nothing about paging cost, rate limits, or that unauthenticated calls fail, which a mutation-free list tool would still benefit from.

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

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

Two tight sentences: the resource and scope come first, then the usage rationale, then the output constraint. Every sentence earns its place with 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?

An output schema exists, so return-shape explanation is unnecessary, and the six parameters are well covered by the schema. The description supplies purpose, auth scoping, and the encrypted-contents caveat; only paging behavior and error conditions are left entirely to structured fields.

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 83%, so the schema already documents sort, cursor, offset, and the type filters thoroughly. The description adds no parameter-level detail beyond 'by calculator type'; 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?

Specific verb 'Lists' + resource 'saved calculations' + scope 'metadata ... by calculator type', which clearly separates it from load_saved_calculation (contents) and compare_saved_calculations (comparison). It stops short of naming a sibling explicitly, so it lands at 4 rather than 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?

'Use so an agent can help a user find a previously saved scenario before loading it' supplies a clear usage context and implicitly routes to load_saved_calculation as the follow-up step. There are no explicit when-not conditions or named alternatives, so it is not a 5.

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

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

With no annotations provided, the description carries the full burden and does disclose two non-obvious behaviors: results are scoped to the authenticated key's user, and locked saves return locked: true with no contents. It does not cover failure behavior for a nonexistent or foreign calculationId, which is the remaining gap for an unannotated read tool.

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

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

Three short sentences, zero padding, with the ownership constraint front-loaded and the edge case last. Every sentence carries distinct information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be described, and the description still covers ownership scope, call sequencing, and the locked-save edge case. The only omission is error/not-found behavior, which leaves it slightly short of fully complete for a lookup tool.

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 single parameter's description already says 'ID returned by list_saved_calculations,' so the tool description adds essentially nothing new about the parameter. Baseline 3 applies when the schema fully documents the input.

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 ('Loads') and resource ('one saved calculation') with explicit ownership scope ('belonging to the authenticated API key's user'), which cleanly separates it from list_saved_calculations and compare_saved_calculations. An agent can identify this as the single-item retrieval tool 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 sequencing instruction: 'Use after list_saved_calculations to retrieve full details of a specific saved scenario,' which tells the agent both the precondition and the intent. It does not mention when to prefer compare_saved_calculations or what to do when the ID is unknown, so it stops short of full when/when-not coverage.

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

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

With no annotations, the description carries the behavioral burden and does disclose key traits: hard input ceiling, pre-solve rejection of over-limit values, a bounded/fixed solver evaluation budget, and the €2,000 admin cost as a disclosed modelling assumption. It does not cover determinism, runtime, or what happens when the optional salary allocation is omitted (beyond the schema note).

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 scope and use case are front-loaded and the whole entry is a few short sentences. It is slightly repetitive, restating the €1,000,000 ceiling three times ('up to €1,000,000', 'may not exceed €1,000,000', 'larger values are rejected'), which costs some efficiency.

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 described; within that, the description supplies the required inputs, the solver's bounded nature, and a modelling assumption. Missing are the outcome of omitting directorSalaryAllocation (delegated to the schema) and any note on solver runtime or result 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 the schema already documents every parameter including defaults, enums and maxima; the description largely restates these. The one genuine addition is that over-limit monetary inputs are rejected before solving, which clarifies failure behavior rather than parameter meaning.

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 ('Optimizes Cyprus LTD company-director remuneration') and narrows the scope to monetary inputs up to €1,000,000, which cleanly separates it from the personal-tax and pension siblings. The follow-up sentence 'Use for a Cyprus LTD director remuneration comparison' reinforces the exact use case.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

Gives clear usage context ('Use for a Cyprus LTD director remuneration comparison') and prerequisites ('Require company profit/revenue, deductible expenses, tax year and domicile status'). It does not name a competing sibling (e.g. calculate_cyprus_income_tax) or state when this tool should not be chosen, so it falls short of explicit alternative routing.

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

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

With no annotations, the description still discloses key behavior: only supported fields are extracted, missing fields should be reported, and statement rows must not be created or inferred. It does not explicitly state read-only/no-side-effect behavior, but the parsing constraints are meaningfully described.

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 three tight sentences with no waste. The core purpose is front-loaded, followed by usage and a clear extraction constraint.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given one fully described parameter and an output schema, the description provides enough context for correct selection and invocation. It identifies the source text, the target audit step, and the no-inference rule.

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?

The single text parameter has 100% schema description coverage, so the schema already explains the expected pasted statement lines. The description reinforces the mortgage-statement context but does not add syntax or format details beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific transformation: turning pasted bank mortgage-statement rows into audit_mortgage_statement inputs. It clearly distinguishes parsing/extraction from the downstream audit and from other sibling calculators.

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 says to use the tool for extracting supported fields from actual mortgage statement text and implies this happens before audit_mortgage_statement. It does not explicitly compare against alternatives or list when not to use it, but the context is clear.

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

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

With no annotations provided, the description carries the behavioral burden and does well by stating that it will not fill gaps or create contribution records and that missing or unreadable details must be reported. It does not discuss authentication, rate limits, or malformed-input handling, but the core extraction constraints are disclosed.

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 definition is front-loaded and appropriately short, with purpose, usage, and a behavioral guardrail. It repeats the Cyprus Social Insurance statement context slightly, which keeps it from being maximally tight.

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 simple one-parameter parsing tool with a full output schema, the description covers the essential purpose, usage context, and important non-fabrication behavior. Minor gaps around malformed input or output shape are mitigated by the output schema and simple parameter contract.

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?

The schema has 100% description coverage for the single text parameter, so the schema already explains that it expects pasted statement text. The description adds context about the domain but does not add syntax, format, or validation details beyond what the schema provides.

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 and resource: extracting structured contribution history from pasted Cyprus Social Insurance Services pension statement text. It also scopes the output to supported contribution years and units, and implicitly distinguishes itself from calculation tools by saying it does not fill gaps or create contribution records.

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 clearly says to use this tool on an actual pasted Cyprus Social Insurance statement, which gives useful context for when it applies. It does not explicitly name alternative sibling tools such as get_pension_reference_data or calculate_cyprus_state_pension, so the routing guidance is clear but not exhaustive.

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

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

With no annotations, the description carries the burden and does disclose meaningful behavior: it reports missing/unreadable values rather than silently succeeding, refuses to fabricate transactions, and will not default to EUR. What it does not define is what counts as a 'supported' transaction, which is the main behavioral unknown for a parser.

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 action, but the second sentence ('Use to extract supported transactions from actual pasted broker CSV or ledger text') largely repeats the first rather than adding new information. The requirement/error-handling sentence does earn 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?

Output schema exists, so return shape needn't be described, and both required params are covered. The description gives the agent what it needs to call the tool safely; only the definition of 'supported transactions' is left open.

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 both parameters are already documented in the schema, and the description's restatement ('Require the source text and actual base currency') adds no format detail or example. Baseline 3 applies since 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?

Names a specific verb and resource ('Turns pasted broker CSV or ledger text into analyze_portfolio transactions') and scopes it to 'supported transactions'. It is clearly distinguishable from the sibling parsers (parse_mortgage_statement_text, parse_pension_statement) and from analyze_portfolio itself, which it feeds.

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 states when to use it ('Use to extract supported transactions from actual pasted broker CSV or ledger text') and describes the workflow handoff ('Output rows can be sent to analyze_portfolio'), plus the preconditions (source text, actual base currency). It stops short of naming when NOT to use it or which sibling to pick for non-broker text.

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

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

No annotations are provided, so the description carries the behavioral burden, and it discloses normalization to monthly, automatic T1-T4 tiering, computed outputs, and explicit default/disclosure behavior for missing frequency and omitted investments. It does not explicitly state whether the calculation is persisted or has side effects, which matters given sibling tools like save_calculation.

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 action and result, then covers usage, data-quality expectations, and edge-case defaults. Every sentence adds operational information, and there is no filler or repetition.

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 fully explained, and the schema already documents all six parameters in detail. The description adds important data-integrity and default-handling context, though it could state more explicitly that the tool is a pure calculation and does not itself save the result.

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 rich per-field descriptions already documenting income, expenses, frequency, investments, projection horizon, and return assumptions. The description adds some meaning, such as treating omitted investments as zero and disclosing frequency defaults, but most parameter semantics remain supplied by the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: 'Builds a monthly budget.' It also enumerates normalization, tiering, and returned metrics, and scopes the tool to a household's actual monthly net income and expense items, which distinguishes it from the tax, pension, mortgage, and investment siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

It explicitly says 'Use to summarize a household's actual monthly net income and expense items' and instructs the agent to ask for the actual expense ledger or item amounts and never fabricate expenses. It does not name a when-not condition or an explicit alternative sibling, but no sibling tool clearly overlaps with this budgeting purpose.

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

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

With no annotations, the description carries the full burden and does so: it discloses the deterministic-plus-Monte-Carlo structure, tax aggregation order (progressive allowance, one foreign-pension allowance, shared €180,000 GESY ceiling), the 2026 flat 5% foreign-pension rate, that omitted state pension excludes pension income, that omitted modelling inputs fall back to disclosed defaults, and that seedless runs are stochastic while seeded runs repeat for a given implementation version.

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 and use case, then units, then tax mechanics, then determinism — a logical order. It is dense and earns most of its length, but repeats the GESY ceiling and foreign-pension allowance points twice, which is minor waste.

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 13-parameter, no-annotation tool, the description covers the essential gaps an agent needs: input sourcing discipline, units, tax/aggregation behavior, default assumptions, and stochastic-vs-repeatable execution. An output schema exists, so return values need not be explained.

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; the description still adds real meaning beyond the schema by stating units and cadence (EUR, monthly contributions/drawdown, ages in years) and explaining how concurrent pensionStreams are aggregated and how netAnnualOverride is treated. Marginal duplication of the GESY/foreign-allowance rules already in the stream schema keeps it from a 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Runs a deterministic projection plus Monte Carlo simulation of a retirement savings plan') and explicitly scopes the output to sustainability/longevity. It is clearly distinguishable from siblings like calculate_cyprus_state_pension or analyze_portfolio, which cover narrower pieces.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

Gives clear when-to-use ('retirement savings sustainability or portfolio-longevity projection') and strong input-sourcing rules ('Reuse the user's ages, savings... ask for each missing essential input and never use example personal values'). It does not explicitly name a sibling alternative or state when not to use it, so it falls short of a 5.

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses that inputs are stored unencrypted, that server-computed results are included, and that saved data is later retrievable via list/load. It omits details like overwrite behavior for duplicate names or authentication/error conditions.

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

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

Three tight sentences, each earning its place: purpose, when to use, and storage behavior. The key constraint (unencrypted storage) is front-loaded after the core purpose.

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 full output schema and 100% parameter documentation, the description covers the essential behavioral traits. It could be more complete by mentioning handling of existing scenarios (overwrite vs. error) and pointing to 'update_calculation' as the alternative for saved scenarios.

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 three parameters, including the calculationType enum and nested inputs. The description adds no parameter-specific meaning beyond what the schema provides, making the baseline 3 appropriate.

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 and resource ('Saves a calculator scenario to the authenticated user's stored history'), making the operation clear. It does not explicitly differentiate itself from the sibling 'update_calculation' or 'list_saved_calculations', so it stops short of 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 a clear triggering context: 'Use when the user asks to save, keep or remember a scenario.' However, it offers no exclusions or alternative routing, such as using 'update_calculation' for an already-saved scenario, which would be needed for a 5.

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

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

With no annotations, the description carries the behavioral burden and does well: it discloses that over-requests are capped and flagged, that self-funded surrender taxes affect household cash flows and IRR, and that forecast returns are assumptions requiring labeling. It could be stronger by explicitly stating that the tool is a pure simulation with no persistent side effects.

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 is front-loaded, but the description repeats the same capping/executed-withdrawals concept in two separate sentences. The core information is useful, yet the redundancy costs some conciseness.

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 14-parameter simulation with no annotations and an output schema, the description covers the key domain constraints: required real policy data, no generated history, capping behavior, and assumption labeling. The schema and output schema handle the detailed parameter and return semantics.

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 parameter meanings are already fully documented in the input schema. The description adds domain-level expectations such as using actual policy terms and not fabricating history, but it does not add parameter-specific syntax or constraints 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 specific verb and resource: simulates a Cyprus unit-linked life insurance policy and calculates tax and returns from executed withdrawals. The added instruction 'Use to model withdrawals from an existing Cyprus life-insurance policy' clearly separates it from generic tax, pension, or portfolio siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

Gives clear context for when to use the tool and lists required inputs (actual policy terms, tax rate, historical records, future projections). It also instructs the agent to ask for missing items and never generate policy history, though it does not explicitly name when not to use it or point to a specific alternative.

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

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

With no annotations, the description carries the burden and delivers substantive behavior: fixed-then-variable phases, monthly and lump-sum overpayments, interest-only mechanics ('minimum payments track the remaining balance, with principal due at maturity'), and unsupported KFIK/cash-collateral modes. It also imposes input-integrity rules ('never substitute example loan terms or rates', EUR amounts and APR expected). Not fully disclosed are determinism/statelessness and rounding conventions on the produced schedule.

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

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

A single front-loaded paragraph that leads with the purpose, then capabilities, then exclusions, then input requirements — good ordering. Slight bloat in the trailing meta-instruction ('without narrating tool selection'), which is agent-directed rather than tool-descriptive.

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 16-parameter, annotation-free calculator, the description supplies the capability scope, the exclusion set, the input-integrity contract, and the currency/rate conventions, while the output schema covers return values and the schema covers each parameter's type and bounds. 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 coverage is 100%, so the schema already documents every parameter including enums and ranges; baseline is 3. The description adds useful framing — which inputs are mandatory in practice (actual loan amount, term, fixed-period length, rate inputs per applicable phase), the EUR/APR units, and the prohibition on fabricated example values — but it does not explain parameter interactions such as bankMargin vs variableBaseRate or overpaymentPeriodType/overpaymentYearsCount beyond what the schema 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?

Opens with a specific verb and resource: 'Simulates a Cyprus mortgage with a payment schedule that reconciles paid amounts to principal and interest.' The Cyprus/mortgage framing plus the amortization-and-reconciliation scope clearly separates it from siblings like audit_mortgage_statement, parse_mortgage_statement_text and compare_rent_vs_buy.

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 ('estimate a Cyprus mortgage payment, amortization, overpayments or rate scenarios') and when-not ('For document checklists or general mortgage information, do not call the calculator; answer or research directly'), plus an unsupported-configuration exclusion (KFIK and cash-collateral). An agent can route correctly without 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?

No annotations are provided, so the description carries the full burden. It discloses two genuinely useful traits: replacing inputs triggers a server-side recompute (a side effect the agent must anticipate), and encrypted saves remain locked, implying the operation will not take effect on them. It omits permission requirements and behavior when neither field is supplied, so not perfect.

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 short sentences, front-loaded with the core action, then the usage trigger, then the constraint. Every sentence adds distinct information with no restatement of the title or name.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Output schema exists, so return values need no explanation, and all three parameters are documented in-schema. The description covers the mutation semantics and the encrypted-save caveat. Minor gaps remain around whether a call with neither optional field errors out.

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 reinforces the optional/partial nature of the update via 'and/or' and restates that inputs cause recomputation, but adds no format or format-specific 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?

Specific verbs and resource: 'Renames a saved calculation and/or replaces its inputs (recomputing results).' An agent can distinguish this mutation from save_calculation, load_saved_calculation and delete_saved_calculation from the description alone. No sibling is named explicitly, so not 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?

Explicit trigger condition: 'Use when the user asks to rename a save or re-run it with different inputs.' That maps user intent directly to tool choice. No explicit when-not or named alternatives (e.g. use save_calculation to create a new one), which keeps it below 5.

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