Loan / mortgage calculator

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

Annotations already cover safety (readOnly, idempotent, closed-world), and the description adds genuinely new behavioral facts: arithmetic is in whole cents, the final payment absorbs rounding so the balance hits exactly 0, and extra monthly payments report interest saved and payoff acceleration. That is real determinism/output context beyond the structured hints, though nothing is said about input validation failures or edge behavior at rate 0.

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 dense sentence front-loads the return values, then packs the extra-payment and schedule behavior, constraints, and a reference URL. Every clause carries information, though the 'Maths is in whole cents like the website' phrasing is slightly chatty and the trailing link is decorative rather than operational.

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 seven parameters, no output schema, and a computational tool, the description enumerates the return payload (payment, total interest, total paid, payoff month, interest saved, amortization schedule) and bounds the inputs. An agent has everything needed to call it and to know what comes back.

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 earns an increment by adding constraints the schema omits — the 0–100% rate band, the 1-month-to-100-year term band, and the fact that extraMonthly yields interest-saved/payoff-shortening output, and that schedule can be yearly, monthly, or none.

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 opens with the exact outputs (monthly payment, total interest, total paid, payoff month) for a fixed-rate loan or mortgage, plus the optional extras. A verb+resource+scope statement this specific lets an agent distinguish it from neighboring calculators like calc_compound_interest or calc_salary 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 the domain ('fixed-rate loan or mortgage') and bounded by stated ranges (rate 0–100%, term 1 month to 100 years), but there is no explicit when-to-use/when-not-to-use guidance or named alternative. An agent must infer that this is the right tool when a loan amortization is wanted rather than, say, compounding.

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