HomeCalc — Canadian Mortgage & Tax Calculators

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

Annotations cover only readOnly/openWorld, so the description carries real weight and delivers it: 20% tapering to 0% over 366-730 days, a $20,000 deduction gated on 365+ days held. That is genuine model behavior beyond structured fields, though it doesn't note estimation limits or whether other exemptions (e.g. deaths, divorces) are handled.

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?

One dense sentence, rate schedule front-loaded followed by the deduction condition. No filler and no redundancy with the title 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?

For a read-only calculator with a fully documented 3-parameter schema and no output schema, the description supplies the full rate model and deduction rule. It could still state whether the result is a plain tax amount or a breakdown, and confirm the estimate-only caveat.

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 already 100%, so the baseline is 3, but the description adds the interaction the schema does not spell out: the deduction applies only if held at least 365 days, which ties isPrimaryResidence to daysHeld and clarifies why taxableIncome can be negative.

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 ("Estimate") plus a precise resource ("British Columbia's home flipping tax") and scope ("sold within 730 days"). This clearly separates it from siblings like capital_gains_tax and house_flipping 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?

The 730-day window and residency condition imply the applicable scenario, but there is no explicit when-to-use instruction and no routing against the near-identical sibling "house_flipping". Usage is inferable rather than 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 declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description goes further by disclosing the computational model: a flat 50% inclusion rate, principal-residence exemption, LCGE for QSBC shares, capital-loss offsets, rental CCA recapture, and stacking on other income at federal + provincial brackets. 'Estimate' honestly signals an approximation rather than a filed figure.

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, front-loaded with the action and scope, and the methodology list is compact rather than padded. It is dense but every clause carries information; only the long exemption enumeration risks being skimmed.

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 19-parameter tax engine with no output schema, the description gives an unusually complete picture of the calculation pipeline and the conditions each branch responds to. It omits how taxYear affects brackets and whether results break down by federal vs provincial components, which are the remaining gaps.

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 89%, so the schema already documents nearly every parameter, and the description mostly restates the same mechanisms (PRE, LCGE, CCA recapture) without naming parameters or adding input-format detail. The one genuinely additive point is that the gain stacks on top of other income, which clarifies the role of annualIncome.

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 — 'Estimate Canadian capital gains tax on a disposition' — and enumerates the covered asset classes (real estate, stocks, crypto, business, rental). That scope cleanly separates it from siblings like income_tax, land_transfer_tax, and bc_home_flipping_tax.

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

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

The asset-type list implies when the tool applies, but there is no explicit when-to-use/when-not guidance and no routing to alternatives. With twelve siblings — including income_tax and bc_home_flipping_tax, which overlap on Canadian property taxation — the agent is left to infer which calculator to pick.

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=true and openWorldHint=false, so safety is covered. The description adds genuine behavioral context beyond that: the mortgage math uses Canadian semi-annual compounding, and the output includes a local-market cap-rate benchmark. It does not discuss error conditions or assumption caveats, but for a stateless calculator this is solid.

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 with no filler. The metric list comes first and the Canadian-compounding caveat is placed last as a scoping note, which is the right front-loading.

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

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

With no output schema, the description usefully enumerates the returned metrics, and it flags the Canadian-specific calculation convention, which matters for a 9-parameter domain tool. It stops short of explaining required-vs-optional inputs or the benchmark source, leaving minor gaps.

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 78% and most parameters carry their own descriptions (including units and the all-cash downPayment tip). The description only indirectly explains the 'city' parameter via the local-market benchmark sentence, adding little beyond the schema. Baseline 3 is 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?

States a specific verb ('Analyze') and resource ('a Canadian rental property') and enumerates exactly which metrics are produced (cap rate, NOI, GRM, expense ratio, cash flow, cash-on-cash return). An agent can distinguish it from siblings like mortgage_payment or mortgage_affordability 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?

Usage is implied by 'Analyze a Canadian rental property' plus the market-benchmark comparison, so an agent can infer this is the investment-return tool rather than a financing tool. However, no explicit when-to-use/when-not guidance or named alternative (e.g. mortgage_payment for pure loan math) is given.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description usefully adds behavioral detail beyond that: the 65% LTV revolving cap, 80% total secured borrowing limit with an A lender, OSFI stress-test TDS qualification, and coverage of B/Private tiers. It stops short of describing edge cases or default fallbacks.

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

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

Two tight sentences, front-loaded with the comparison purpose followed by a compact enumeration of the computed outputs. Every clause carries information; 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?

With 14 parameters and no output schema, the description carries the return-value burden and does so well by naming the outputs (borrowing capacity, monthly payments, TDS qualification, tier equivalents). It is nearly complete, though it omits the optional default behaviors (e.g., prime rate, tier rate defaults) that the schema documents.

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 71%, so the schema already documents most inputs. The description adds domain meaning that maps to parameters (65% LTV tie to homeValue/outstandingFirstMortgage, A/B/Private lending to secondMortgageLenderTier, OSFI rate), but does not explain individual parameters beyond the schema 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 specific verb (compare) and two named resources (HELOC vs second mortgage) for a distinct jurisdiction (Canada), which clearly separates it from siblings like mortgage_payment or mortgage_affordability. An agent can tell what it does 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?

Usage is implied by 'Compare a HELOC against a second mortgage for tapping home equity,' but there is no explicit when-to-use, when-not-to-use, or routing to sibling tools (e.g., 'for a plain affordability check use mortgage_affordability'). The agent must infer the context.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds real behavioral context beyond that: it explains the CRA residential flipping rule's consequence (held under 12 months = 100% business income, no capital gains treatment) and states that the tool flags the rule and computes the savings from crossing the 12-month line. It stops short of disclosing estimation assumptions or rounding conventions.

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, front-loaded with the core action and then the tax-rule behavior; nothing is redundant with the title. The first sentence is a dense comma-list that reads as an inventory of inputs rather than a calculation story, which slightly blurs the read but wastes no words.

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 tool with no output schema, the description usefully names what comes back (estimated profit, tax bill, flipping-rule flag, 12-month savings), so an agent knows the shape of the result. What is missing is guidance on the Canadian scope boundary versus the BC-specific sibling and any note on model assumptions, but the core is complete.

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

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

Schema description coverage is 92%, so the schema already documents nearly every parameter, and the baseline is 3. The description organizes the inputs into a calculation flow (rebate, contingency, holding costs, commission, closing costs, marginal rate) and adds the business-income vs capital-gains consequence for holdingPeriodMonths, but it introduces no parameter syntax, units, or defaults the schema lacks.

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 ('Estimate the profit on a Canadian house flip') and then enumerates exactly what is included: land transfer tax with rebate, renovation contingency, holding costs, commission, closing costs, and the tax bill. This clearly differentiates it from siblings like land_transfer_tax or capital_gains_tax, which each cover only one slice of the same flip.

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

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

Usage is implied rather than stated: an agent can infer this is the whole-flip calculator that includes the CRA 12-month rule, and the description names the comparison it enables ('tax saving from waiting past the 12-month line'). However, it gives no explicit when-to-use/when-not guidance and does not route away from overlapping siblings such as bc_home_flipping_tax (BC-specific) or capital_gains_tax.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds real context beyond that: the 2026 tax year, which contribution programs are included (CPP/QPP, EI, QPIP), Quebec-specific deductions, and that net take-home pay is produced. It stops short of describing permissions, edge cases, or return structure.

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?

Single front-loaded sentence covering the full calculation scope with no filler. The long parenthetical list of contributions is dense but each item earns its place by defining coverage.

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

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

With no output schema, the description should clarify what is returned. It indicates net pay and the tax components computed, which is partially sufficient, but it does not describe the shape of the result (breakdown per component, deductions vs. tax) that an agent would need to interpret the response.

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 75%, so the schema already documents province, annualIncome and rrspContribution; the only undocumented parameter is employmentType. The description adds nothing about how rrspContribution or employmentType affect the calculation, so it does not compensate for the small gap.

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

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

States a specific verb ('Calculate') and a well-scoped resource: 2026 federal + provincial income tax, CPP/QPP, EI, QPIP, Ontario surtax and Health Premium, plus net pay. That enumeration distinguishes it from sibling tax tools like capital_gains_tax or land_transfer_tax, though it never names an alternative 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?

The description says what is calculated but never when to choose this tool over capital_gains_tax or the property-tax siblings, and gives no prerequisites (residency, employment type, tax-year constraints) or exclusions.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds real behavioral context beyond that: what is bundled into the result (transfer tax + registration fee + total due) and, critically, what is excluded (mortgage registration fee), which prevents misreading the output as an all-in cost.

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

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

Three sentences, no filler, with the core scope front-loaded and the exclusions and edge cases trailing in order of importance. Dense but every clause carries information about coverage or output composition.

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

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

No output schema exists, and the description compensates by enumerating what the result contains (LTT estimate, registration fee, total due at registration). Combined with the parameter-level coverage notes, an agent has enough to call it and interpret the answer, though exact return field names remain unspecified.

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 80% and the description supplements it meaningfully by mapping parameters to real-world cases: Toronto triggers the municipal MLTT, Montreal uses welcome-tax brackets, and first-time buyer rebates apply. It doesn't spell out the province-by-province fee schedule, but the semantics of each input are clear.

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

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

States a specific verb (estimate) and resource (land transfer tax on a home purchase), and scopes it precisely: 13 provinces/territories, Toronto MLTT, Montreal welcome tax, first-time buyer rebates, plus registration fee and total due. An agent can distinguish this from siblings like capital_gains_tax or mortgage_payment 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?

Gives clear usage context and useful exclusions: it explains that AB, SK, NL and the three territories charge only the registration fee, and that the mortgage registration fee is a separate cost not included. It doesn't name a sibling tool as an alternative, but the domain boundaries are 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 readOnlyHint=true and openWorldHint=false, so the safety profile is clear. The description adds meaningful behavioral context by disclosing the exact down payment tiers and that it also reports CMHC insurance applicability and premium rate, though it does not discuss output format or edge-case 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 a single front-loaded sentence that immediately states the main calculation, followed by necessary rule detail in a parenthetical. Every clause earns its place by specifying the calculation and outputs.

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 calculator with no output schema, the description sufficiently explains what is computed and returned: the minimum down payment, whether CMHC insurance applies, and the premium rate. An agent has enough context to 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?

The single homePrice parameter has 100% schema description coverage, so the schema already defines its meaning and constraints. The description does not add parameter-level detail beyond what the schema provides, making the baseline score 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?

States a specific verb (Calculate) and resource (minimum down payment) with the exact Canadian CMHC rule set and additional outputs (CMHC insurance applicability and premium rate). The scope is unambiguous and clearly distinct from sibling mortgage or tax 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?

The description implies when the tool is useful by stating its purpose, but it does not explicitly say when to use it versus alternatives such as mortgage_payment or mortgage_affordability. No exclusions or routing guidance are provided.

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 it a read-only, closed-world operation, so the safety bar is low. The description then adds genuine behavioral context beyond that: the binary-search approach, the two ratio thresholds applied, the stress-test rate, the down-payment tier logic, and the insurability ceiling — none of which the annotations supply.

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: the first front-loads the purpose and the qualifying rules, the second lists the return values. It is dense but every clause earns its place; minor credit withheld only because the first sentence packs several distinct constraints into one long clause.

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

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

With no output schema, the description correctly spells out the returns (max price, max mortgage, CMHC premium, monthly payment, GDS/TDS ratios), and annotations cover the safety profile. For a 12-parameter domain calculator this is nearly complete, though it does not tie the ratio rules back to the specific inputs that drive them.

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 67%, so the schema carries most of the parameter meaning (units, defaults, ranges, enums). The description adds domain framing — down-payment tiers and the CMHC ceiling — but does not clarify individual parameter behavior (e.g. how downPaymentMode interacts with downPayment) beyond what the schema states. Baseline 3 is 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?

States a specific verb+resource ('work out the maximum home price a Canadian buyer qualifies for') and pins down the exact domain scope: GDS 39%, TDS 44%, OSFI stress-test, Dec-2024 down-payment tiers, $1.5M CMHC ceiling. This clearly separates it from siblings like mortgage_payment and minimum_down_payment, which compute payments or down payments rather than qualification.

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

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

The description conveys when the tool is applicable (a buyer evaluating affordability under Canadian rules) but never routes the agent against the obvious alternatives. It does not say how it differs from, or when to prefer it over, mortgage_payment or minimum_down_payment, despite the sibling list containing both.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description goes further, disclosing that CMHC insurance is applied when the down payment is under 20%, that the loanAmount path takes the amount as principal with no premium, and that wrong-path input changes the result by several percent. It stops short of describing the return payload (no output schema exists, so a brief note on what comes back would help).

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 tightly written sentences, each earning its place, with the two-branch decision front-loaded ahead of the cautionary exclusion. No filler.

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

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

For a 10-parameter, non-trivial calculator with no output schema, the description nails the one genuinely ambiguous decision (which of two input paths to take) and the CMHC consequence. It omits guidance on the remaining options (frequency, term, amortization, province), leaving those to the 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 60%, and the description adds real meaning beyond it: the homePrice+downPayment pairing, the mutual exclusivity of loanAmount, and the CMHC trigger condition. Parameters like province, rateType, termYears, paymentFrequency, and amortizationYears are not addressed in the description, though the schema covers several of them.

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 ('Calculate the periodic mortgage payment for a Canadian home') with clear scope. It is immediately distinguishable from siblings like mortgage_affordability, minimum_down_payment, and mortgage_penalty, which do different jobs.

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 two explicit calling modes keyed to what the user provided (purchase price vs. mortgage amount), plus an explicit exclusion: 'Do NOT invent a purchase price in order to reach a loan amount.' An agent knows exactly when to use each path and what error to avoid.

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

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

Annotations only cover read-only/open-world, so the description carries the behavioral load and does so well: it discloses the illustrative-default fallback, that omitting rates can skew results several-fold, and that the response reports assumed values in `assumedInputs` with instructions to surface them. This is exactly the accuracy caveat an agent needs.

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 method logic before the IMPORTANT caveat, and every sentence is load-bearing. Slightly dense in the opening clause, but nothing 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?

With 8 parameters, 3 required, and no output schema, the description covers the critical unknowns: which inputs are commonly missing, what happens then, and that `assumedInputs` appears in the response. It stops short of describing the rest of the return shape, but the accuracy-relevant part is complete.

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

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

Schema coverage is already 88%, so the baseline is 3, but the description adds meaning beyond the schema by framing the three optional rate inputs as lender-specific values most users will not have, and explaining the fallback when they are omitted. It doesn't add format/syntax detail beyond that.

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 (estimate the penalty to break a Canadian mortgage) and immediately scopes the calculation methods (three months' interest vs IRD, big-bank posted-rate method). This cleanly separates it from the other real-estate calculators such as mortgage_payment or mortgage_affordability.

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 use (breaking a fixed vs variable Canadian mortgage) and explains the branching rule. It does not name an alternative sibling or state when not to use it, but for a self-contained calculator the when-to-use guidance 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so an agent knows this is a safe, closed-world computation. The description adds the legal framing (LTB/RTB guidelines) but omits meaningful behavioral facts such as which years are supported, what happens for unsupported inputs, and that only three provinces are valid — the schema's pointer to 'this tool's supported years' hints at a constraint the description never states.

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

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

A single front-loaded sentence that names the computation, the three supported jurisdictions and the returned value with no filler. Nothing in it is redundant with the title or annotations.

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

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

With no output schema, the description correctly states the return value (maximum allowable increase and resulting new rent), which is what an agent needs. The one real gap is the unsupported-year/unsupported-province behavior, but for a stateless three-parameter calculator the definition is otherwise sufficient.

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

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

Schema coverage is 67%: currentRent and year carry descriptions, while province is an undocumented enum. The description compensates partially by expanding the enum values into their regulators (Ontario LTB, BC RTB, Manitoba RTB), but it adds no unit, format or range detail beyond the schema, so the baseline of 3 fits.

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 (calculate) and resource (maximum allowable annual rent increase) plus the scope (three named provinces, a given year) and the secondary output (resulting new rent). This clearly separates it from the mortgage, tax and cap-rate siblings, which compute entirely different quantities.

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

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

The domain context makes the intended use obvious, but there is no explicit when-to-use or when-not-to-use guidance and no alternative tool is named. An agent can infer it is the rent-guideline calculator, but nothing tells it what to do if the province or year falls outside the supported set.

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