UQUAL Loan Readiness

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and closed-world scope, so safety is covered. The description adds real behavioral value by naming the computed outputs (cash-to-close, program comparison, credit-gain scenarios), which matters since no output schema exists. However, it omits caveats that an agent should relay, e.g. that results are illustrative estimates not rate locks or lender commitments.

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 that front-loads the primary output (max purchase price) before the breakdown and sensitivity details. No filler or restated title, though the packed list of outputs makes it slightly harder to parse at a glance.

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 15-parameter tool with no output schema, the description is the sole source of return-value information, and it only sketches outputs as a prose list without structure or caveats. It is adequate to know what the tool produces but thin for a calculation this complex; a note on estimate assumptions and the shape of the 4-program comparison would close the gap.

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 all 15 parameters carry enum values, defaults, and ranges documented in-schema. The description mentions '+20/+40/+60 credit score gains or monthly debt reduction' but frames these as computed outputs rather than clarifying how creditScore or monthlyNonHousingDebt inputs drive them. With schema doing the heavy lifting, baseline 3 applies.

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 ('Computes') and a precise resource ('maximum affordable home purchase price'), then enumerates the outputs: 4-program comparison, PITI+MIP/PMI+HOA breakdown, cash-to-close, and credit/debt sensitivity. The purpose is unmistakable, though it never explicitly differentiates itself from siblings like compare_fha_vs_conventional despite overlapping 4-program comparison territory.

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 description says what it calculates but gives no when-to-use guidance, no prerequisites, and no exclusions. With siblings such as calculate_mortgage_dti, compare_fha_vs_conventional, and evaluate_loan_readiness_score in the same family, the absence of routing language leaves the agent to infer selection from names alone.

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 cover safety (readOnly, idempotent, non-destructive, closed-world), so the description's contribution is the computational behavior: it discloses the exact agency rule sets applied (FHA 31/43 and AUS 46.99/56.99, Conventional 28/36 to 45/50, VA 41, USDA 29/41) and that results are deterministic. That is meaningful added context an agent could not get 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?

Front-loaded with the verb and the primary outputs, with no filler wording. The downside is that it is a single dense mega-sentence whose long list of agency thresholds is hard to parse, but every clause carries substantive information.

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 19-parameter calculator with no output schema, the description never characterizes the returned payload — presumably a structured object with front-end/back-end ratios per agency, per-agency limits, and paydown deltas. An agent cannot anticipate the response shape or which fields map to which computed scenario.

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 documents all 19 parameters in detail, including the student-loan plan and agency enums. The description restates the agency imputation concept but adds no syntax, precedence, or interaction rules beyond what the schema says — the 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 ('Computes') plus the concrete artifacts produced: front-end and back-end DTI ratios, agency-specific student loan imputations, maximum allowable monthly debt per agency, and dollar debt reduction. It is clearly distinguishable from siblings like calculate_mortgage_affordability or compare_fha_vs_conventional, which do different jobs.

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 by the enumeration of outputs — an agent can infer 'call this when you need DTI math and agency caps.' There is no explicit when-to-use statement, no exclusions, and no pointer to the related siblings such as simulate_debt_payoff_and_readiness for the lump-sum tradeoff scenario.

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 readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered and the description carries a lower burden. Beyond that it usefully discloses the depth gradient (deep rules for five states, baseline elsewhere) and one concrete figure ($15,000 NC 1st Home Advantage). It does not state that amounts are estimates subject to lender/program approval, nor whether the result is a pass/fail plus award figure.

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 with the verb and scope front-loaded, and every clause (state list, national baseline, the NC dollar figure) adds informational value. The parenthetical program enumeration is heavy but not padded; nothing is repeated from 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?

With 9 parameters, no output schema, and a rules-engine behavior, the description should say more about what comes back (eligibility verdict, award amount, limiting factors) and about the authority/currency of the state rules it applies. It correctly covers geographic coverage and the baseline fallback, which is the biggest completeness risk, but leaves return-shape expectations entirely to inference.

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% with 3 enums fully documented, so the schema already explains state, homePrice, buyerStatus, creditScore, income, liquid cash, lien structure, first mortgage program, and non-housing debt. The description adds no parameter-level meaning — notably it never explains how secondLienStructure interacts with the state defaults, which is the one thing the schema leaves genuinely ambiguous.

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 names a specific verb+resource pair ('Evaluates eligibility and estimated assistance amounts for state HFA programs') and enumerates exactly which state programs are covered deeply (TX TSAHC/TDHCA, FL, CO CHFA, GA Dream, NC NCHFA) versus the national baseline fallback. That scope is far more precise than any sibling, though it never explicitly contrasts itself with calculate_mortgage_affordability or evaluate_loan_readiness_score, so an agent must infer the boundary.

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: the program list signals 'use this when a buyer wants down payment assistance in one of these states.' There is no explicit when-to-use statement, no prerequisites (e.g., income limits or first-time-buyer requirement checks), and no named alternative among the six sibling tools that handle affordability, DTI, or loan readiness.

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 readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description goes beyond them by disclosing the embedded business rules: 3.5% down at 580+, 1.75% UFMIP plus annual MIP, 3%/5% Conventional minimums at 620+, credit-tiered PMI, and PMI cancellation at 80%/78% LTV. That tells the agent what assumptions the output rests on, which is genuinely useful; it does not disclose response shape or units, but the annotations carry most of the remaining burden.

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?

It is a single front-loaded sentence that opens with the action and the two compared programs before the parenthetical detail, so the most important information comes first. The nested parentheses make it dense to parse, but no sentence is wasted.

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 analytical tool with no output schema, the description does state the key return values (5- and 10-year totals, exact crossover credit score), which is the main thing an agent needs. It stops short of noting the DTI comparison implied by grossMonthlyIncome or the role of holdingHorizonYears, leaving minor gaps in what the output will contain.

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 every parameter carries a description with defaults and bounds, so the schema does the heavy lifting and the 3 baseline applies. The description adds modest value by tying the 3.5%/3%/5% down-payment and 580/620 credit figures to the comparison logic, but it does not individually explain parameters such as holdingHorizonYears or downPaymentMode beyond what the schema already 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 opens with a specific verb (compares) and two named resources (FHA vs Conventional), then states exactly what is returned: 5-year and 10-year total cost plus the credit score crossover point. That is clearly distinct from the sibling tools (affordability, DTI, down-payment assistance, readiness score), none of which produce a side-by-side loan-program cost comparison.

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 narrow scope: an agent can infer this is for borrowers choosing between FHA and Conventional. However, there is no explicit when-to-use framing, no mention of when a sibling such as calculate_mortgage_affordability or calculate_mortgage_dti would be the better call, and no stated prerequisites (e.g. that a rate assumption is required).

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?

The annotations already establish that this is a read-only, idempotent, non-destructive operation, so the description does not need to repeat safety behavior. It adds useful context about the four scoring pillars, compensability cap diagnostics, program alignment, and counterfactual action steps, but does not disclose assumptions, limitations, or the exact return structure.

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?

The definition is a single front-loaded sentence that immediately states the score, scale, pillars, and advanced outputs. Every clause earns its place, and there is no repetition or 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 complex 17-parameter scoring engine with no output schema, the description gives a good high-level summary of what is produced. However, it lacks usage routing against sibling tools and does not clarify the exact shape or limits of the returned diagnostics, leaving some practical gaps.

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 input schema already defines each of the 17 parameters in detail. The description adds high-level domain framing by naming the four pillars, but it does not map specific inputs to pillars or add meaning 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?

The description names a specific verb and resource: computing UQUAL's 4-Pillar Loan Readiness Score on a 0-100 scale across four named pillars. It is clearly distinct from single-metric siblings like calculate_mortgage_dti or calculate_mortgage_affordability, though it never explicitly routes the agent away from those alternatives.

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 description explains what is computed but gives no explicit guidance on when to use this tool versus the sibling calculators or when not to use it. There are no prerequisites, exclusions, or comparative instructions beyond the tool name itself.

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 readOnlyHint=false, openWorldHint=true, non-idempotent and non-destructive, so the safety profile is pre-supplied. The description usefully adds that a live external POST to uqual.com/api/seo-leads is made and that consent is mandatory, but says nothing about what happens on failure, retries, or duplicate submissions despite idempotentHint=false.

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 sentence, front-loaded with the opt-in qualifier before the action and endpoint. No filler and nothing buried.

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 an 11-parameter, nested-object, externally-firing tool with no output schema, the description leaves the return value completely unspecified — an agent cannot tell whether a success confirmation, lead ID, or error shape comes back. The consent gate and endpoint are covered, but outcome expectations are not.

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 100% schema description coverage, the schema already documents all 11 parameters, including the conditional contact-field requirements and the dryRun flag. The description adds no parameter-level meaning beyond what the schema states, so the baseline 3 applies.

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 ('request a review'), a concrete resource ('1-on-1 UQUAL Loan Readiness Coach review'), and the destination endpoint (uqual.com/api/seo-leads). This is unmistakably distinct from the six sibling tools, all of which are local calculators rather than external lead handoffs.

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 description gives a hard gate: invoke ONLY when the user explicitly consents to share contact details, which is a clear when-to-use and implicitly a when-not. It does not name an alternative action (e.g., continue with the calculators if consent is withheld), so routing guidance is strong but not exhaustive.

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 readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds domain behavior beyond that: the agency exclusion rules for installment debts and utilization thresholds. It does not disclose what the simulation returns, time horizon assumed, or how ties between strategies are resolved.

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?

It is a single dense sentence with no filler, front-loading the three compared strategies. The clause about thresholds is somewhat compressed and jargon-heavy, which slightly hurts readability, but nothing is redundant.

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 simulation with 6 well-documented parameters but no output schema, the description should say more about what the simulation produces (comparison table, months-to-payoff, DTI trajectory). It covers inputs and strategy choice adequately but leaves the result shape entirely unstated.

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 every parameter is already documented including defaults and enums. The description restates the targeting logic tied to the debts array and alludes to utilization/DTI inputs, but adds no syntax or interpretation guidance beyond the schema, so baseline 3 applies.

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 names a specific verb (simulates) and three concrete strategies (Avalanche, Snowball, DTI-First), plus the targeting rule (installment debts near <=10 remaining payments, revolving cards above 30%/10% utilization). It does not explicitly distinguish itself from siblings like calculate_mortgage_dti or evaluate_loan_readiness_score, so it falls short of a 5.

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 strategy names and the mortgage-readiness framing, and the debt-targeting thresholds hint at the scenario the tool is for. However, there is no explicit when-to-use or when-not-to-use statement, and no pointer to the sibling tools (e.g. use calculate_mortgage_dti for a single DTI snapshot vs this for multi-strategy payoff comparison).

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