apartment.loans: apartment loan sizing

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and closed-world behavior, so the description does not need to repeat safety details. It adds useful behavioral context by specifying that the tool returns surplus/shortfall, required NOI, and the highest workable rate, though it does not state modeling assumptions such as amortization treatment.

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 one front-loaded sentence that states the scenario and the returned results without filler. It is appropriately sized for a focused calculation tool.

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 calculation tool with full schema coverage and annotations, the description is nearly complete: it explains the scenario being tested and summarizes the output. It could be stronger if it noted key modeling assumptions or how optional constraints like max_ltv and min_dscr shape the 'highest workable rate' 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 the parameter meanings are already well documented in the input schema. The description does not add syntax, defaults, or interpretation guidance beyond what the schema provides, making the baseline 3 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 states a specific test — whether a bridge loan can refinance into permanent debt at stabilization — and previews the outputs. It is clear enough to distinguish from siblings like refinance_break_even or size_loan in practice, but it does not explicitly contrast itself with 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 use case is implied by 'bridge loan refinances into permanent debt at stabilization,' so an agent can infer when this applies. However, there is no explicit when-not guidance, no named alternative for nearby scenarios, and no mention of prerequisites such as stabilized NOI being available.

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, closed-world and non-destructive, so the safety profile is covered. The description adds the deduction logic (what is subtracted to reach net cash), which is genuine behavioral context, but says nothing about how the new loan is sized under max_ltv/min_dscr or whether the result can be zero or negative.

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 tight sentence with the key quantity front-loaded and no filler. It reads as a noun phrase rather than a complete directive, which slightly weakens the lead.

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 10-parameter financial calculation with no output schema, the description does state what is returned, which is the most important piece. It omits the loan-sizing mechanics implied by value/max_ltv/noi/min_dscr/rate/amort and any handling of constraint-binding or negative proceeds.

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 in the schema; the description only echoes four of the ten (payoff, prepayment, closing costs, reserves) and adds no unit or format detail. Baseline 3 applies when the schema carries the semantic load.

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 the exact quantity computed — net cash to the borrower from a cash-out refinance — and enumerates the deduction components (payoff, prepayment, closing costs, reserves). That is specific enough to separate it from siblings like size_loan or refinance_break_even, though it never uses an explicit verb such as 'computes' and does not name those 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?

There is no guidance on when to call this versus size_loan, refinance_break_even, or compare_programs. The agent must infer from the description alone that this is the proceeds-calc tool, with no stated preconditions or exclusions.

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 establish this is a read-only, idempotent, closed-world, non-destructive check, so the safety profile needs no restating. The description adds the substantive point that eligibility is judged against published agency criteria, but it omits key behavioral facts: what happens when the optional liquidity/net_worth/occupancy inputs are omitted, and whether the screen fails soft or reports insufficient data.

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 front-loaded sentence with no filler, naming the resource and the three criteria sets first. It is efficient, though borderline terse for a screening tool whose result interpretation matters.

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 eight parameters, no output schema, and no explanation of what the screen returns (per-program pass/fail, failing thresholds, or a list of shortfalls), the description leaves an agent unable to anticipate the response. It also never clarifies that four parameters are optional or what omitting them means for the verdict.

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 eight parameters are already documented and the baseline of 3 applies. The description adds no domain nuance — neither what 'units' vs 'occupancy_months' drive in the criteria, nor how the optional sponsor metrics change the outcome when absent.

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?

Specific verb ("screen") plus the exact criteria sources (Fannie Mae Small Loans, Freddie Mac Conventional Small, HUD 223(f)), which tells an agent precisely what decision is being evaluated. It does not, however, say how this differs from siblings like match_programs or compare_programs, so the boundary is left to inference.

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: 'screen a deal' suggests a pre-application eligibility check, but there is no explicit when-to-use, when-not-to-use, or routing to match_programs/compare_programs. An agent can guess the context but cannot rule out calling the wrong sibling.

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=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful scope by naming the agency programs and the bank case, but it does not disclose calculation assumptions, output format, or limitations.

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 a single compact sentence fragment that front-loads the key scope and lists the relevant programs efficiently. It is concise, though the lack of a clear verb makes it slightly less structured than an ideal definition.

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?

There is no output schema, so the description should carry more of the burden for explaining what the comparison returns and how it is calculated. It does state the high-level output (maximum loan under each program plus a bank case), but it omits assumptions, output structure, and interpretation of the bank case.

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 five parameters are already documented in the input schema. The description adds no parameter-level meaning beyond the refinance context, so the baseline score of 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 identifies the resource and scope: maximum refinance loan amounts under three named agency programs plus a bank case. This is more specific than the tool name alone, though it does not explicitly distinguish the tool from siblings such as match_programs or size_loan.

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 states what the tool computes but gives no explicit guidance on when to use it versus alternatives like match_programs or size_loan. The refinance context is implied, but there are no conditions, exclusions, or prerequisite 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?

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is fully covered by structured data. The description adds one useful behavioral fact — that results are ranked and carry fit/fail reasons — but says nothing about scoring methodology, determinism of ordering, or how many programs are returned.

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 action and the output shape front-loaded and zero filler. Nothing could be removed without losing content.

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?

There is no output schema, so the description is the only place the return shape can be described, and it only gestures at it ("ranked programs with reasons"). With six parameters and a close-named sibling (compare_programs), the definition should do more to say what comes back and how it differs from a plain comparison.

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 (units, occupancy, loan, hold, reno, recourse) are documented in the schema itself. The description adds no meaning beyond the schema, 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?

The description pairs a specific verb ("Rank") with a specific resource ("loan programs") and scope ("for a deal"), plus an output hint ("reasons each fits or fails"). It is clear what the tool does, but it never distinguishes itself from the sibling compare_programs, which a reader could easily mistake for the same operation.

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 "for a deal" — the agent can infer this is the deal-time matching step, but there is no statement of when to prefer it over compare_programs or check_eligibility. No prerequisites, no exclusions, no explicit alternative 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 readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds little beyond restating the title: it does not say what milestones are produced, how close_days or target affect the schedule, or whether default anchor points are applied.

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 front-loaded sentence with no filler or redundancy. It is efficient, though the brevity is partly under-specification rather than disciplined editing.

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?

This is a computation tool with no output schema, so the description is the only place an agent could learn what the returned milestone list looks like — and it says nothing about that. For a tool whose whole value is the generated schedule, that is a material 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%, so all three parameters are already documented, including the agency|bank|hud|cmbs|bridge enumeration for target and the YYYY-MM-DD format for maturity. The description only reinforces that maturity is the anchor from which dates are derived; baseline 3 applies 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 resource (dated refinance milestones) and the computation rule (working back from a loan maturity date), which is more informative than the title alone. It does not differentiate itself from siblings such as refinance_break_even or size_loan, so an agent cannot route between them on the strength of this text.

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?

There is no guidance on when to use this versus refinance_break_even, bridge_takeout, or the other refinance-adjacent siblings, and no stated prerequisites or exclusions. The agent must infer the use case entirely from the one-line purpose.

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 closed-world, so the safety profile is covered. The description adds nothing beyond that: no indication of whether the result is a month count, a dollar delta, or a recommendation, and no note on assumptions (e.g., that prepay_pct applies to today's balance).

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 short sentence with no wasted words, but the brevity comes from omission rather than efficiency; there is no front-loaded statement of what the tool returns or how to interpret its output.

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 five-required-parameter financial computation with no output schema, the description should tell the agent what the result represents (break-even months, cost difference, or a recommendation). It supplies none of that, so the caller cannot interpret the response without trial and error.

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?

All five parameters are fully documented in the schema (100% coverage), so the schema carries the semantics and a baseline of 3 applies. The description adds nothing new — it doesn't clarify how months interacts with new_rate, or that prepay_pct is the cost incurred only in the 'now' branch.

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 frames the decision the tool models (refinance now with prepayment cost vs. wait for the open window), which hints at a break-even comparison, but it never states that the tool *computes* a break-even point or what quantity it produces. It is a scenario restatement rather than a specific verb+resource, leaving the actual function inferable only from the name.

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?

There is no guidance on when to choose this tool over siblings such as check_eligibility, compare_programs, or size_loan, nor any preconditions (e.g., loan must still be in its lock period, rate must be lower). The agent is left to guess the applicable situation entirely.

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 this as a safe, read-only, idempotent calculation. The description adds real behavioral context by explaining the lender-style method—taking the minimum of LTV, DSCR, and debt-yield constraints. It still doesn't mention defaults for optional parameters or what happens if they are omitted.

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, front-loaded sentence with no wasted words. It communicates the tool's purpose and calculation logic efficiently.

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 full schema coverage and safe-operation annotations, the description is nearly complete. The only gaps are that it does not state the return value explicitly or explain how optional parameters are defaulted.

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 seven parameters are already documented. The description adds no parameter-specific meaning beyond confirming the three constraint types correspond to max_ltv, min_dscr, and min_debt_yield.

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 resource ('Size an apartment loan') and clarifies the calculation method: the lowest of LTV, DSCR, and debt-yield limits. It is easy to distinguish from sibling tools like refinance_break_even or cash_out, though it doesn't explicitly name 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 implies when to use it (when you need a lender-style loan sizing), but there are no explicit when-to-use/when-not conditions or comparisons to sibling tools. Usage is inferable but not guided.

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