Clara Mortgage Assistant

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

Annotations already cover readOnly, idempotent, closed-world, non-destructive, so the bar is lower; the description still adds real context by clarifying that the output is ratios only and not an approval or suitability decision. It also discloses that no values are retrieved from chats, files, accounts, documents, or the web, going beyond the openWorldHint alone. Return shape is not described, but an output schema exists.

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 calculation and its input contract, which is the right ordering. The disclaimer about approval/underwriting/suitability is stated twice ('not an approval or suitability decision' and 'no approval, underwriting, or suitability decisions'), which is avoidable repetition.

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 rich annotations and a machine-readable output schema, the description need not explain return values, and it covers the key input contract and scope limits. Minor gaps remain around tolerances, effectiveDate semantics, and jurisdiction that only the schema handles.

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 71% (high), so the schema already documents payment, income, housing costs, and debts. The description adds meaningful framing on monthlyPayment (taken as given, no derivation needed), but says nothing about effectiveDate, tolerances, or jurisdiction beyond the schema's own descriptions.

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 (calculates) and precise resource (Canadian GDS and TDS ratios) and immediately scopes the input shape: a monthly payment that is already known, not derived. This cleanly separates it from siblings like calculate_ltv and calculate_qualification, which operate on different inputs.

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?

Explicitly states the prerequisite that the payment is given and that no principal, rate, or amortization is needed, which tells the agent when this tool applies versus a payment-derivation tool. It also constrains inputs to explicit non-identifying numbers, but never names a sibling by name as the alternative.

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 readOnly, idempotent, non-destructive, closed-world behavior, so the bar is lower; the description still adds meaningful context that it never reads from chats, files, accounts, documents, or the web and that outputs are ratios only. Nothing contradicts 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-loads the calculation, then the disclaimer, then the input-provenance constraint. Sentences are purposeful, though the repeated no-approval/no-recommendation framing is slightly 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?

With an output schema present and annotations covering safety, the description supplies the remaining needed context: scope (Canadian), input provenance, and the guarantee that only ratios are returned. An agent can call this correctly without further information.

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 75% and most parameters carry their own descriptions, so baseline 3 applies. The description only loosely hints at the value basis ('purchase price, an appraised value, or both') and does not explain lesser_of, effectiveDate semantics, or storedLtv, adding little 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?

States a specific verb and two named resources (LTV and CLTV) plus the exact inputs it operates on (loan amount, other secured positions, purchase/appraised value). That is clearly distinct from siblings like calculate_debt_service and calculate_qualification.

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?

Explicitly scopes usage to Canadian calculations driven by explicit, non-identifying numbers supplied in the request, and rules out approvals, underwriting, recommendations, and lookups. It does not name a sibling as the alternative path, so it stops short of a 5.

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 readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds genuinely new context: results are neutral scenario math rather than an approval, it operates only on explicit non-identifying numbers, and it performs no lookups from chats, files, accounts, documents, or the web. The openWorldHint=false annotation partially overlaps the last point, keeping this just below 5.

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 no-approval idea is stated twice in near-identical terms ('not an approval or underwriting decision' and 'no approval, underwriting, or suitability decisions'), and 'It computes the payment itself, so it needs those loan terms' is filler. The scope statement is front-loaded and the disclaimers are placed last, which helps.

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 values need not be explained. For a 12-parameter compute tool with nested housing and tolerances objects, the description conveys the domain, the conceptual inputs, and the strong scope boundaries. The only gap is that optional overrides like floorRate and bufferRate are never surfaced in prose.

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 75%, so the schema carries most parameter meaning, including detailed rate-as-decimal formatting and defaults. The description names only principal, contract rate, amortization, and income, leaving floorRate, bufferRate, tolerances, housing, otherMonthlyDebts, and straightSwitchExempt entirely to the schema. Baseline 3 is appropriate 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?

States a specific verb and resource: it computes the B-20 qualifying rate, qualifying payment, and resulting GDS/TDS from named inputs. An agent can tell this is a qualification math tool rather than a debt-service or LTV tool. It never names a sibling to differentiate against, so it stops 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 through the input prerequisites ('from a principal, contract rate, amortization, and income') and what it deliberately is not (no approval or underwriting decision). But it gives no explicit when-to-use versus calculate_debt_service, calculate_ltv, or compare_mortgage_scenarios, so routing must be inferred from the name.

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), yet the description adds substantive traits beyond them: calculations are deterministic, inputs must be explicit and non-identifying, no values are sourced from chats/files/accounts/documents/web, and the output excludes any decision or recommendation. These are exactly the behavioral boundaries an agent needs for routing and for deciding whether a request is in-scope.

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 core capability, then the input constraint, then the output boundary. No filler, no restatement of the title, and every clause carries decision-relevant 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?

With an output schema present, return values need no explanation, and the nested scenario schema documents its own fields and enums. The description covers purpose, input sourcing limits, and output boundaries, so nothing an agent needs to decide whether and how to call this tool is missing.

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 67%, so the baseline is around 3, but the description adds meaning the schema does not: scenarios are capped at six (matching maxItems), the product is fixed-rate (constraining how annualRate should be interpreted), and inputs must be explicit numbers. It does not clarify effectiveDate's relationship to the supplied rates or the scenario object's required fields 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 first sentence gives a specific verb+resource+scope: 'Compares up to six Canadian fixed-rate payment and amortization scenarios using deterministic calculations.' An agent immediately knows this is a multi-scenario calculator, not a single-metric one. It does not explicitly name or distinguish itself from siblings like calculate_qualification or estimate_prepayment_penalty, which keeps it below 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?

The description sets clear negative scope: 'Returns calculations only: no approval, underwriting, or suitability decisions, no lender or product recommendations,' and restricts inputs to 'explicit, non-identifying numbers in the request.' This tells the agent when this tool is the wrong choice, but it never names an alternative (e.g., refuse_unsupported_mortgage_request) or states the positive trigger conditions, so no explicit alternatives routing.

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 readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds meaningful behavioral context beyond that: the calculation is an estimate only, no approval/underwriting/suitability output, no recommendations, and no retrieval from chats, files, accounts, documents, or the web — a real data-sourcing constraint.

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-loads the core capability in the first sentence, then layers scope limits and disclaimers. The negative-clause list is somewhat long but each clause rules out a distinct class of misuse, so it mostly earns its place.

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 an output schema present, return values need no explanation, and the description covers method scope, data sourcing, and authoritative-source caveats. The remaining gap is guidance on method selection and conditional parameters, which an agent must infer from the schema alone.

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 86%, so the schema already documents principal, annualRate, comparisonRate and remainingTermMonths well. The description names the two penalty methods but does not clarify the method enum values, when comparisonRate is required, or how effectiveDate interacts with the calculation.

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 and resource — estimating three-months-interest and simplified interest-rate-differential prepayment penalties — which is unambiguous and clearly distinct from siblings like calculate_ltv or calculate_debt_service. An agent can identify the tool's domain 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?

Gives clear operating context: works only from explicit, non-identifying numbers in the request, and discharge statements remain authoritative. However, it never names or routes to an alternative tool, nor states when a different sibling (e.g. compare_mortgage_scenarios) should be preferred.

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 readOnly, idempotent, non-destructive, closed-world, so the bar is lower. The description still adds real value by disclosing the output nature (a fixed explanation plus a suggested alternative calculation) and a privacy constraint: no request text, names, identifiers, or document content are accepted. It doesn't mention determinism of the fixed text beyond idempotentHint, but the important behaviors are covered.

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 sentences, front-loaded with the core behavior, followed by the scope enumeration. No filler; every clause carries scope or constraint 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?

An output schema exists, so return values need no explanation. For a single-parameter refusal tool with full annotation coverage, the description supplies everything an agent needs: what it does, which categories qualify, and the no-PII input constraint.

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 the enum values are enumerated in the schema, so the baseline is 3. The description's restatement that only the category is accepted and never user/borrower/document data largely duplicates the schema's own parameter description rather than adding new semantic detail per enum value.

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 and outcome (returns a fixed explanation that the request is out of scope, plus an alternative calculation) and enumerates the exact categories it covers. That enumeration makes it trivially distinguishable from the calculate_* and compare_* siblings.

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 category list functions as an explicit when-to-use test: approval/underwriting, recommendations, borrower documents, rates/rules, external actions, other. It does not explicitly say 'use the calculate_* tools instead for supported requests', but the 'with a calculation it can do instead' clause implies the routing. Clear context, no explicit exclusions.

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