Mortgage Tools by Jenny

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds genuinely useful behavior: it incorporates the lender-quoted penalty (IRD or three months' interest), separates cashflow payback from borrowing-cost crossover, and explains that an unknown penalty blocks an unconditional ranking. This is real context beyond annotations, though it doesn't cover the assumed/known vs unknown data-state handling that drives the 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?

Four tight sentences, front-loaded with the usage trigger, then mechanism, then exclusions. No filler and nothing repeated from name/title.

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

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

Given a rich schema and an output schema, the description needn't explain return values. It covers when to use, what it compares, and the penalty dependency. It could say more about the known/assumed/unknown fact model that governs inputs, but for a 10-param tool with heavy schema documentation this is close to 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 60% and the schema itself is extremely rich with per-field descriptions (facts, penalty states, funding, atPeriod). The description mentions the penalty's role and the replacement offer but adds no parameter format or semantics beyond what the schema already documents. Baseline 3 is appropriate given the schema carries most of the burden.

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

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

States a precise verb+resource (compare breaking vs staying on a Canadian mortgage) and bounds it to a user partway through a term. It names the sub-cases (refinance same debt, switch lender, lower rate) and distinguishes itself from penalty calculation and cash-out/rate-search tools.

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

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

Gives explicit trigger conditions ('user is partway through a Canadian mortgage term and asks whether to break... or stay') and explicit exclusions ('Do not use to calculate or estimate a penalty', 'No cash-out or rate search'), naming the failure mode (unknown penalty prevents an unconditional ranking).

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

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

Annotations already declare a safe, closed-world read, so the description's value is the extra behavior it discloses: three fixed scenarios compared over a common horizon, outputs covering interest/debt left/fees/limits, a monthly-payments-only restriction, and the 1-10 debt bound. It does not discuss runtime errors or result volume, but this is well above the annotation baseline for a pure computation tool.

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

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

Front-loaded with the trigger condition, then scenarios, then output summary, then constraints and exclusions - a logical order with no filler. The sentences are dense but each carries distinct information; sizing is appropriate for a comparison tool with this much surface area.

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 itemized, yet the description helpfully summarizes what is reported. Given the nested mortgage/replacementOffer/penalty structure and the split-of-responsibility for facts (known/assumed/unknown), the description covers scope, limits and exclusions adequately, though it leaves the fact-wrapping contract entirely 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 45%, so the description must carry weight, and it does add real meaning for the central `debts` parameter (1-10 items, each fixed_monthly or interest_only) and the monthly-payments-only constraint. However, it says nothing about mortgage, replacementOffer, penalty, penaltyFunding, horizonMonths, monthlyBudget, contractCaps or scheduleWindow, leaving a meaningful portion of the 11 parameters undocumented in both places.

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 resource (debt consolidation into a Canadian mortgage), and enumerates the debt types it can model (credit-card, car-loan, LOC/HELOC balances). The scope is narrow and distinct from planning or renewal tools, but it never references any sibling by name, so disambiguation still relies on the caller knowing the sibling set.

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?

Opens with an explicit trigger ("Use this when a user asks about rolling other debts...") and closes with explicit exclusions ("Do not use for a new HELOC, additional cash-out or qualification: none is modeled"). It gives clear when/when-not but does not point to an alternative tool for those excluded cases, which would have lifted it to 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 annotations already covering the safety profile (readOnlyHint, destructiveHint=false, openWorldHint=false), the description adds real modeling behavior: what is computed over a common horizon and the rule 'An unknown cost is never treated as zero.' It doesn't describe pagination or output shape, but with an output schema present that gap is minor.

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

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

Front-loaded with the selection condition, then scope, then the return summary, then exclusions - each sentence carries distinct information. No filler or repetition of the title.

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

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

For a complex nested 5-parameter tool with an output schema, the description supplies everything an agent needs to decide to call it and what to expect: eligibility, the required user-supplied facts, the alternative for a different scenario, and the treatment of unknown values. Return values are covered by the output schema and only summarized here.

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 nested offer schema is very rich, so much of the meaning is already structured. The description enumerates the input domain (rates, terms, amortizations, cashback, switching costs) and implies the horizon parameter via 'over a common horizon', which is useful framing but adds little syntax or format detail beyond the schema.

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

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

States a specific verb (compare) and resource (Canadian mortgage renewal offers for the same balance), including the concrete artifacts (renewal letter vs. switch quote). It also names the sibling it is not - compare_break_or_stay - so an agent can route without opening either schema.

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

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

Explicit when-to-use (two or three offers for the same balance at renewal) and an explicit when-not with the alternative tool named ('Do not use for leaving a mortgage before the term ends (use compare_break_or_stay)'). It also carves out non-goals: no rate search/prediction, no qualification, no lender recommendation.

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

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

Annotations already declare readOnly/non-destructive/closed-world, so the bar is lower, yet the description still adds real behavior: it returns facts in priority order, asks at most three questions, and flags cash-out refinance as unsupported. It also declares scope exclusions ('Does not calculate, rank, check qualification or search rates'), which prevents misuse. It stops short of describing response shape or pagination, but the output schema covers return values.

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

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

Four tight sentences, front-loaded with the selection rule ('Use this first...') and the exclusion immediately after. Every clause carries actionable routing or behavioral 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?

For a diagnostic tool with an output schema, this covers trigger, exclusion, output content (missing facts + questions), unsupported cases, and explicit non-capabilities. An agent has everything needed to invoke it correctly and to know when not to.

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 only 50% schema description coverage and nested fact objects, the description names the six required facts (balance, rate, remaining amortization, term, switching costs, lender-quoted penalty) and adds the priority ordering that the schema does not encode. It also calls out the cashOutRequested behavior. It does not explain the boolean flags (financedCostsPresent, amortizationExtended) or the known/assumed/unknown state machine, which remain schema-only.

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

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

States a precise verb and resource ('returns the missing ones in priority order and up to three questions to ask') and enumerates the covered scenarios (renewal, extra-payment, break-or-stay, debt-consolidation). It explicitly contrasts itself with the sibling calculators ('call the matching calculator'), so an agent can select it correctly without reading either schema.

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

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

Gives an explicit trigger ('Use this first when ... has not yet given the key figures') and an explicit exclusion ('Do not use when the figures are already supplied: call the matching calculator'), effectively routing to the compare_* siblings. The boundary between this and get_mortgage_guide is implicit but the calculator split is unambiguous.

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

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

Annotations already declare readOnly=true, openWorld=false and destructive=false, so the safety profile is covered. The description adds genuine behavioral context beyond that – the guide is dated, Ontario-specific, reviewed by an Ontario mortgage agent, and ships with a public source, review status and follow-up questions. Some of this overlaps the output schema, which caps it below a 5.

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

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

Two dense sentences: the usage condition first, then return characteristics, then exclusions. No filler, and the front-loaded 'use this when' clause makes scanning easy. The long topic list is verbose but functional rather than wasteful.

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, closed-world, 2-enum-param tool with an output schema, this is complete. Usage boundaries, topic scope, provenance, and explicit exclusions are all present; return-value detail is largely delegated to the output schema as expected.

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

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

Schema description coverage is 100% and both parameters are enums already documented in the schema. The description re-enumerates the nine topics in prose and implies 'short' maps to the brief detail mode, but adds no syntax or meaning 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 (read/retrieve) and resource (a short, dated Ontario mortgage preparation guide), and enumerates the nine supported topics. The 'not a calculation' qualifier cleanly distinguishes it from calculation-oriented siblings like compare_break_or_stay and plan_mortgage_prepayments.

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 ('user asks how to prepare for or understand a supported Canadian mortgage topic and is not asking for a calculation') and gives a detailed when-not-to-use list: general financial/legal/tax advice, current rates, arbitrary URLs, live web search.

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 mark this as a read-only, non-open-world computation, but the description adds substantial behavior: it is a with/without comparison returning interest, remaining debt and modeled payoff; prepayment-privilege limits are checked only when supplied and otherwise reported as not checked; and post-term results require explicit monthly continuation assumptions. That conditional-reporting and assumption behavior is not derivable from the annotations.

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

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

Five dense sentences, front-loaded with the trigger and scope, then comparison output, then the conditional limit check, then the exclusion. Every sentence earns its place, though the trailing continuation-assumptions sentence reads as an abrupt addendum rather than a structured caveat.

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

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

With an output schema present, return values needn't be enumerated, and the description still summarizes the comparison outputs. It covers the conditional limit checking and the penalty exclusion well; remaining specifics (datedEvents requiring startDate, contract-cap bases) live in the schema, which is acceptable given the tool's complexity.

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

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

Schema coverage is only 45% on an 11-parameter, deeply nested schema, so the description must carry weight. It maps its three prepayment modes onto the core inputs (recurring extras, lump sums, payment changes) and flags the limit and continuation-assumption inputs, but adds no syntax, format or fact-state detail beyond what the schema already documents.

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 ('model extra payments on one Canadian mortgage') with concrete scope: higher regular payment, recurring extras, or up to 50 lump sums. It also distinguishes itself from the break/penalty territory covered by siblings such as compare_break_or_stay, so an agent can route correctly without opening schemas.

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

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

Gives an explicit trigger ('when a user asks what paying extra ... would do') and a clear when-not ('Do not use to find a prepayment penalty or the cost of breaking a mortgage'). It stops short of naming the sibling tool that would handle those cases, so the agent must infer the alternative rather than being routed to it.

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