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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so safety is covered structurally. The description adds genuine non-annotation context: what the tool returns (break-even month, lifetime savings) and a mandatory behavior — displaying the calculator_url as a clickable markdown link. It does not discuss assumptions such as whether closing costs are optional or how the new term interacts with years_left, but with annotations carrying the safety profile 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?

Three sentences, front-loaded with the purpose before the routing and the link requirement. There is mild redundancy: 'it returns the break-even month and lifetime savings' restates the opening sentence's output claim verbatim, costing a few words, but the structure is otherwise tight and each remaining sentence adds routing or behavior.

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-value details need not be spelled out, and annotations cover the safety profile. Purpose, disambiguation from siblings, required-input scenario, and the calculator_url rendering obligation are all present. Minor gap: nothing hints at defaulting behavior for the optional new_term_years or closing_costs despite them materially changing the break-even 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%, so all six parameters (balance, years_left, new_rate_pct, optional closing_costs and new_term_years with default 30, current_rate_pct) are already documented in the schema. The description adds no unit, format, or default information beyond that, which is the expected baseline 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?

The first sentence names a specific computation (break-even month and lifetime savings) on a specific resource (refinancing a loan), and the description explicitly carves out the sibling tools calculate_loan and calculate_mortgage for a different scenario. An agent can distinguish this from the other ~65 calculate_* tools 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?

It states the trigger condition ('user already has a loan and is weighing a refinance offer') and names the concrete alternatives to use otherwise ('For a brand-new loan payment use calculate_loan or calculate_mortgage'). It also gives an explicit post-call instruction to surface the calculator_url as a markdown link, which is actionable usage guidance.

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