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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds genuinely useful behavioral substance beyond that: it discloses the qualifying-rate methodology (stress test rather than contract rate), the regulatory ratios and down payment tier rules applied, and it enumerates the returned fields (max price, max mortgage, CMHC premium, monthly payment, GDS/TDS), compensating for the absent output schema.

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 tightly packed sentences with zero filler. The primary output (maximum home price) is front-loaded, the rules that govern it follow, and the return payload closes the description — each clause earns its place despite the density.

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 12-parameter financial calculator with no output schema, the description does the heavy lifting well by listing return values and the regulatory framework used. It stops short of describing edge-case behavior — for example, what happens when the computed price exceeds the $1.5M insurability ceiling or when the down payment falls below a tier minimum — which an agent would want to know before interpreting results.

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 itself already explains every parameter, and the baseline of 3 applies. The description contributes one meaningful clarification beyond the schema: that qualification is evaluated at the OSFI stress-test rate rather than the 'contract mortgage rate' described on interestRatePct, but it adds no guidance on downPaymentMode interplay or the 25/30-year amortization constraint beyond what the schema states.

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 states a specific verb+resource: it computes the 'maximum home price a Canadian buyer qualifies for,' and it names the exact standards applied (GDS 39%, TDS 44%, OSFI stress-test rate, Dec-2024 down payment tiers, $1.5M CMHC ceiling). This clearly separates it from siblings like mortgage_payment or minimum_down_payment, but it never names those siblings explicitly, so the differentiation is inferential rather than stated.

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 only implied: an agent can infer this is the tool for 'how much house can I afford' questions rather than 'what is my payment on price X.' There is no explicit when-to-use/when-not-to-use guidance and no routing to mortgage_payment, minimum_down_payment, or land_transfer_tax, which are the obvious adjacent calculations.

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