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

The annotations already establish that this is a safe, read-only, closed-world calculation, and the description adds the enumerated comparison outputs and the balance-reducing effect of a lump sum. It does not disclose calculation conventions such as Canadian compounding, how the current-payment baseline is derived, or how accelerated payment frequencies affect the comparison.

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 compact sentences front-load the comparison, enumerate its principal results, and then cover the optional lump-sum behavior. There is no redundant or promotional wording.

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?

Together with the fully documented schema and safety annotations, the description supplies enough information to select and invoke the calculator, including its main outputs despite the absence of an output schema. Greater completeness would require key methodology assumptions and clearer routing away from related mortgage calculators.

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 seven inputs, their defaults, and their constraints. The description reinforces the roles of the rates, new term, and lump sum but adds little parameter-specific meaning beyond that documentation.

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

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

The description gives a specific action and scope: comparing a Canadian mortgage's payment and term interest between the current and renewal rates. Listing payment changes and extra term interest clearly distinguishes it from sibling tools such as mortgage_payment and mortgage_amortization.

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 renewal-rate comparison and payment-shock context make it clear when this tool is appropriate, including when modeling a lump sum at renewal. It does not explicitly exclude simpler payment calculations or name an alternative sibling for those cases.

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