Clara Mortgage Assistant

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

The description discloses that the tool is calculation-only and not an approval or suitability decision, and it limits inputs to non-identifying numeric values. It also says it will not fill missing inputs from external sources. Annotations already declare readOnlyHint, idempotentHint, and non-destructive; the description adds context about usage scope, so it scores high without contradiction.

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 description is concise, with multiple sentences that are all informative. It starts with the MUST-use rule, then explains the calculation, then restrictions, and then prohibitions. No redundant or unnecessary phrases. Each sentence adds value.

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?

Considering the tool is a calculation with an output schema and detailed input schema, the description covers the essential usage. It explains the input scenario, the forbidden alternatives, and the boundaries of the tool's purpose. Minor gap: not describing the output or the fact that it can accept housing costs for GDS/TDS calculation, but the schema covers these. Overall, complete for its purpose.

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%, covering parameters like monthlyPayment, grossAnnualIncome, housing, and tolerances. The description clarifies the core parameters but does not elaborate on housing or tolerances beyond the schema. It adds the overall logic of direct calculation but doesn't compensate for some parameters not described, like jurisdiction and otherMonthlyDebts, which are self-explanatory.

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 specifies 'MUST use this tool when the user supplies a monthly mortgage payment and asks for Canadian GDS or TDS' and clearly states the calculation purpose, distinguishing it from calculate_qualification. It names the resource (GDS/TDS ratios) and the verb (calculate), which is specific and unambiguous.

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 provides explicit when-to-use instructions: 'MUST use this tool when...' and when-not-to-use: 'do not use calculate_qualification when the monthly payment is already supplied.' It also states what not to do, such as not requiring principal or rate, and mentions the tool is not for approval or suitability decisions.

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 indicate read-only, idempotent, non-destructive behavior. The description reinforces this with 'Calculation only' and explicitly prohibits using the tool for decision-making, adding behavioral clarity beyond 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?

The description is concise but includes several sentences of constraints. It is structured with a clear purpose statement followed by usage restrictions. No unnecessary fluff, though it could be slightly more compact.

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, the description need not explain return values. It covers the calculation purpose and usage constraints effectively. It does not mention required parameters explicitly, but the schema does, so overall completeness is adequate.

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?

The schema provides descriptions for most parameters (75% coverage). The description adds context by mentioning 'purchase price, appraisal, and secured positions', which aligns with key parameters and helps understand their purpose, though it does not detail individual parameters.

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?

Clearly states it calculates Canadian loan-to-value and combined loan-to-value, distinguishing it from sibling tools like debt service or qualification. The verb 'Calculate' and specific resource 'loan-to-value' make the purpose explicit.

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?

Provides clear constraints: 'Use only with explicit, non-identifying numeric inputs' and warns against using for approvals or decisions. However, it does not explicitly compare to alternative tools, though the focus on LTV makes appropriate usage implicit.

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 indicate readOnlyHint=true and destructiveHint=false. The description adds crucial context: 'This is neutral scenario math, not an approval or underwriting decision' and 'never use this tool to approve, deny, underwrite, recommend...' It also restricts to 'explicit, non-identifying numeric inputs,' disclosing privacy and scope boundaries beyond the annotations. No contradiction.

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 description is somewhat lengthy but well-structured. It leads with the primary function, then adds usage guidelines and restrictions. Each sentence conveys essential information, though it could be tightened by removing redundant exclusions. It remains clear and front-loaded.

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?

Given the tool's complexity (12 parameters, nested objects, output schema present), the description covers purpose, usage, behavioral constraints, and boundary cases. It does not need to explain return values because an output schema exists. The description is sufficiently complete for an agent to decide when and how to use it correctly.

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 already documents most parameters. The description mentions key inputs (principal, contract rate, amortization, income) but does not add format or unit details beyond what the schema provides. Since coverage is high, a baseline score of 3 is appropriate; the description adds minimal extra param-specific 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 clearly states 'Calculate the B-20 qualifying rate, qualifying payment, and resulting GDS/TDS' with specific verb and resource. It also explicitly distinguishes from calculate_debt_service by stating when to use which tool, making the purpose unambiguous among 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?

Provides explicit usage conditions: 'Use this tool only when the qualifying payment must be calculated from those inputs.' It also gives a clear exclusion: 'If the user already supplies a monthly mortgage payment and asks for GDS/TDS, MUST use calculate_debt_service instead' and warns against using it for approval/underwriting or filling missing data from other sources. This is exemplary guidance.

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 description adds 'deterministic calculations' and 'Calculation only,' reinforcing the read-only and idempotent nature already indicated by annotations. It does not reveal additional side effects or error behaviors, but the added emphasis on no side effects provides some extra transparency.

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 description is concise, two sentences, with no fluff. It efficiently states the purpose and then usage constraints, making it easy to parse and understand.

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?

Given the tool's clear scope and the presence of an output schema (per context), the description adequately covers the main aspects: what it does, limits, and constraints. It does not explain return values, but the output schema handles that. Some details about error handling or edge cases are omitted, but the description is sufficient for a calculation-focused tool.

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% (jurisdiction and effectiveDate have descriptions; scenarios itself lacks one but its nested fields are described). The description adds no specific parameter details beyond stating inputs should be 'explicit, non-identifying numeric inputs,' which is generic and does not enhance 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?

The description clearly states the tool's purpose: 'Compare up to six Canadian fixed-rate payment and amortization scenarios using deterministic calculations.' It specifies the resource (mortgage scenarios), action (compare), and constraints (Canadian, fixed-rate, up to six), distinguishing it from sibling tools that focus on individual calculations.

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 provides usage boundaries: 'Use only with explicit, non-identifying numeric inputs' and explicitly states when not to use it ('never use this tool to approve, deny, underwrite, recommend...'). It lacks explicit references to alternative tools, but the purpose is clear enough to guide selection.

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?

Beyond the readOnly/idempotent/non-destructive annotations, the description adds important behavioral context: lender discharge statements remain authoritative, calculations are estimates only, and the tool must not be used for decisions or to fill missing inputs. This meaningfully discloses limitations and expected behavior.

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 description is two sentences, front-loaded with the core purpose, followed by concise usage restrictions. Every sentence earns its place with no redundancy 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?

Given the strong annotations, rich input schema, and existing output schema, the description fully covers purpose, limitations, and usage boundaries. It is complete for an agent to select and invoke the tool correctly.

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 high (86%), so the schema already documents most parameters. The description adds context about the two calculation methods but does not add significant per-parameter semantics beyond what the schema provides. 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?

The description uses a specific verb ('Estimate') and resource ('Mortgage Prepayment Penalty'), and explicitly names the two calculation types ('three-months-interest and simple IRD'). This clearly distinguishes it from sibling tools like calculate_ltv or 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?

The description provides explicit usage constraints: 'Use only with explicit, non-identifying numeric inputs' and 'never use this tool to approve, deny, underwrite, recommend, select a lender or product, or fill missing inputs from prior chats, files, accounts, documents, websites, or web search.' This gives clear when-to-use and when-not-to-use guidance.

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?

Beyond the readOnly and idempotent annotations, the description discloses that the tool returns a deterministic refusal, must not receive the original prompt or user data, and should not be used to answer requests directly. This adds meaningful behavioral and privacy context.

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 description is front-loaded with the critical MUST-call instruction, then efficiently lists trigger categories, return behavior, and data-handling rules. Every sentence adds necessary information without redundancy.

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?

Given the output schema exists, the description does not need to explain return values. It fully covers when to use the tool, what requestType to send, what not to include, and how to behave, making it complete for an agent to select and invoke correctly.

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?

The schema already provides full enum coverage and a description for requestType. The tool description adds useful guidance to send 'only the matching requestType category' and never include original prompt or user data, reinforcing safe parameter selection, though it does not map specific scenarios to enum values.

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 clearly states the tool's purpose: to refuse unsupported mortgage approval, underwriting, and related requests. It lists specific trigger categories and explicitly distinguishes the tool from Clara Mortgage Assistant calculations, which also separates it from the sibling calculation tools.

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 explicit when-to-use guidance with 'MUST be called whenever' and enumerates many concrete scenarios. It also clarifies that this tool is for anything 'outside Clara Mortgage Assistant calculations,' effectively directing supported calculation requests to the sibling tools.

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