Commercial.Mortgage: programs, rates and loan sizer

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

Annotations already establish read-only, idempotent, non-destructive, closed-world behavior. The description adds useful behavioral context beyond that: rates are 'today's indicative' figures, each figure is 'dated and sourced,' and a head-to-head comparison page is included 'when one 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?

The description is a single dense sentence that front-loads the core comparison action and then lists return details. Every element earns its place, though the packed enumeration makes it slightly less scannable than an ideal front-loaded 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?

With no output schema, the description does most of the work by listing the compared metrics and noting sourcing and comparison-page inclusion. It is complete enough for invocation, though it does not describe output ordering or behavior when fewer comparison dimensions are available.

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 100%, and the schema already documents the programs array, allowed enum values, and min/max items. The description reinforces the 'two or three programs' constraint but adds no slug-level semantics beyond what the schema provides, so 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 clearly states that the tool compares two or three commercial mortgage programs side by side and enumerates the metrics returned. It does not explicitly distinguish itself from siblings such as match_programs or program_rules, but the verb+resource is clear enough for an agent to identify the tool's role.

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 phrase 'Two or three commercial mortgage programs side by side' implies this is for comparing selected programs, but the description gives no explicit when-to-use guidance or alternatives. It never mentions match_programs, get_rates, or program_rules, so the agent must infer the selection context.

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 a closed-world scope, so safety is covered. The description adds real value beyond that: it discloses that values are 'latest' (freshness caveat), that each carries an observation date, and that it includes a week-earlier value and basis-point change — a per-record shape the agent otherwise could not know since there is no 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?

A single dense sentence with no filler; every clause enumerates a distinct returned field. It is front-loaded with the instruments themselves, though it reads as a noun phrase rather than stating an action, which slightly weakens the opening.

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 zero-parameter, read-only, annotation-covered tool with no output schema, the description effectively serves as the return-value contract, enumerating every field plus the accompanying metadata (observation date, prior week, bps change, publisher). An agent can decide and call correctly without anything further.

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 tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline is 4. The description correctly implies a parameter-free snapshot call rather than inviting arguments.

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 specific resources returned (5/7/10-year Treasury yields, overnight and 30-day average SOFR, bank prime rate), so an agent knows exactly what data this tool surfaces. However, it never distinguishes itself from close siblings like get_rates or get_rates_by_lender_type, which an agent could plausibly confuse with this one.

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 statement of when to use this tool, when not to, or which sibling to prefer for which rate question. With get_rates and get_rates_by_lender_type in the same namespace, the absence of routing guidance forces the agent to infer the boundary 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 declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely new behavior: freshness ('Today's'), provenance ('named, dated source'), sort order ('lowest first'), and explicit handling of missing spreads ('listed as such instead of guessed'). That last point is a meaningful honesty guarantee not derivable from structured fields.

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 tight sentences: what the response contains first, then filtering, then edge-case handling. No filler and no repetition of the title or annotations.

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 must convey return shape, and it does: index type plus date, spread range, source, ordering, and the null-spread case. It stops short of saying how many programs are returned or whether results are exhaustive across families, a minor gap for a bounded read.

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 three parameters are enums with documented values, so the schema carries the semantics. The description only restates the filter dimensions without adding matching logic or combination behavior (e.g., whether filters AND together).

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 ('Today's indicative rate for every commercial mortgage program') and even decomposes the returned value into index + spread range. It does not name or distinguish itself from near-neighbors like get_index_rates or get_spreads_by_property_type, so an agent must infer the boundary from the other tools' names.

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?

'Filter by property type, purpose or program family' describes how to narrow results but never says when this tool is preferred over compare_programs, get_index_rates or get_spreads_by_property_type. Usage is implied by the data it returns rather than stated as a condition.

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, so the safety profile is covered. The description adds genuine behavioral context beyond that: data provenance (named, dated public source), that each index carries its own date, and the important quirk that banks return no spread range because no public source exists — preventing an agent from misreading a null as an error.

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, no filler. The resource and scope come first, and the bank caveat is placed last where it reads as an exception rather than burying the main purpose.

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 one optional enum parameter and no output schema, the description carries the return-value burden and does it reasonably well by naming the returned components (index with date, spread range with source). Minor gap: no mention of units (bps vs percent) or how ranges are formatted.

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 100% and the enum's own description already says 'one lender type; omit for all five.' The description's enumeration of the five types and the bank exception reinforce but do not add new syntax or semantics for the parameter. 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 resource (commercial mortgage rate ranges) with explicit scope: broken out by the five named lender types, returning an index plus a spread range. An agent can tell it is not the raw index tool or a program comparison tool, though it never names a sibling to contrast against.

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 scope: use it when you want rate ranges segmented by lender type. There is no explicit 'use this instead of get_rates / get_index_rates when...' routing, and no statement of prerequisites or when-not-to-use.

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 value-add: the vintage of the data (as of March 31, 2026), the upstream source, and the fact that an indicative rate at today's 10-year yield is appended. It also discloses that four of the eight enum values have no public source and 'say so', which pre-empts an agent mistaking an empty result for a failure.

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 tight sentences with the core resource statement front-loaded and the coverage caveat trailing. The LTV band and as-of date are dense but each earns its place; nothing is redundant padding.

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 single optional enum parameter with full schema coverage and no output schema, the description supplies source, vintage, derived-rate behavior, and coverage gaps. The only shortfall is that the shape of the returned spread figures (units, basis points vs percent) is not stated, leaving some ambiguity about output format.

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 100% and the enum is self-documenting, so the baseline is 3; the description earns above that by splitting the enum into the four types with real data and the four (hotel, self storage, medical office, mixed use) that will return an explicit no-source response. That is behavior the schema alone cannot convey.

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 (permanent-loan spreads over the 10-year Treasury) broken out by property type, with the LTV band (60–65%) and data source (CRED iQ). This is clearly distinguishable from siblings like get_rates and get_index_rates, which return base/index rates rather than property-type spreads.

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 makes the subject matter obvious enough to imply when to call it, but never explicitly says when to prefer it over get_rates, get_rates_by_lender_type, or get_index_rates, nor does it state prerequisites. A one-line routing hint would have pushed this higher.

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 a read-only, idempotent, non-destructive operation, and the description adds useful behavior beyond them: ranked fits with reasons and cautions, indicative rate composition, max-loan estimates from LTV/LTC/DSCR/debt-yield limits, and inclusion of non-fitting programs with reasons. It does not spell out the ranking algorithm or exact output field structure, but it is substantially more transparent than annotations alone.

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 three sentences and front-loads the core action of ranking programs that fit a deal. The long parenthetical program list is useful for scope, though the final external '/find-your-loan/' reference is less useful to an agent and could be trimmed.

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, read-only matcher with no output schema, the description explains the returned content and the handling of non-fitting programs, while the schema fully documents parameters. It is complete enough to call correctly, though output structure and ranking details remain implicit.

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 input schema has 100% description coverage, including enum meanings, defaults, and conditional notes for parameters like existing_loan and noi. The description adds no parameter-level meaning beyond general references to a deal and published program spreads/limits, so the schema carries the parameter semantics.

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 has a specific verb and resource: it ranks commercial mortgage programs that fit a deal, enumerates program categories, and states the outputs. It is distinguishable from rate or sizing tools by its fit-ranking focus, but it does not explicitly differentiate itself from siblings such as compare_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?

Use is implied by 'programs ... that fit a deal' and by the note that non-fitting programs are returned with reasons. However, the description gives no explicit when-to-use/when-not-to-use guidance and never names compare_programs, program_rules, or size_loan as alternatives.

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 read-only, idempotent, closed-world, so the safety profile is covered elsewhere. The description adds real value by disclosing the default Treasury interpolation behavior and that schedules/minimums come from verified loan-document facts rather than free-form input.

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 purpose, then the method list, then the defaults and provenance notes. The six-method enumeration partially repeats the enum but is justified as scope signaling; no filler sentences.

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 calculator with no output schema, the description covers methodology, defaults and data provenance well. It stops short of saying what the response contains (a single premium figure, a breakdown by year, minimums applied), which is the main remaining 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 every parameter is already documented at the field level. The description only reinforces the Treasury default and the loan-document provenance of schedules, adding little beyond the schema; 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 ('Estimate') and resource ('prepayment premium on a commercial mortgage'), then enumerates the six supported methodologies. This makes it instantly distinguishable from the sibling rate/program tools, which do not compute penalties.

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?

Names the six methods and ties each to the note's prepayment provision, which effectively tells the agent which case to pick. It doesn't state exclusions (e.g. when to defer to size_loan or program_rules for the underlying loan terms), but the usage context is clear.

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 read-only, idempotent, closed-world behavior, so the description correctly spends its words elsewhere: it discloses that every figure carries an as-of date and primary source, and that unpublished limits are explicitly marked as such — valuable trust/freshness context an agent cannot get from structured fields.

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: the content inventory leads, then the sourcing/freshness caveat. The long enumeration of metrics is dense but each item tells the agent what it can retrieve; no 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?

With no output schema, the description has to convey what comes back and does so thoroughly — metrics, fit commentary, comparable programs, provenance, and the 'not published' case. Only gap is how the result relates to sibling tools for downstream comparison or matching.

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 100% and the single enum parameter is fully documented in the schema; the description adds nothing about the program slug or how to choose among the 27 enumerated values. 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?

The description clearly states the resource: everything published about one commercial mortgage program, itemized across eligibility, sizing, leverage, coverage, term, recourse, prepayment, and pricing. It is distinguishable from sizing/rate siblings by that breadth, though it never names a sibling tool to contrast against (the phrase 'programs to compare it with' refers to returned content, not the compare_programs tool).

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 statement of when to call this versus match_programs, compare_programs, or get_rates — the agent must infer routing from the itemized content list. The 'who it fits and who should look elsewhere' phrase implies use for program-fit research but is not framed as 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 the safe read-only, idempotent profile, and the description adds real context beyond them: it discloses that default rate/amortization come from the lender type's index plus mid-spread and that the math matches the site's loan sizer, so results are predictable. It stops short of noting limits or that missing lender_type widens output fivefold beyond the earlier hint.

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 with no filler; the core computation and its outputs are front-loaded before the lender_type routing note. The first sentence is long and dense with output names, but every clause carries 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 nine-parameter, no-output-schema computation tool, the description explicitly enumerates what comes back (binding test, monthly payment, LTV, DSCR, debt yield, cap rate), so an agent knows the return shape and default behavior without an output schema.

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 nine parameters, including defaults and the 0-means-interest-only and 0-turns-off-debt-yield semantics, are already documented in the schema. The description adds only the modeling context that requested_loan yields a fits/doesn't-fit verdict, which is marginal over 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 states a specific computation ('largest commercial mortgage a property supports under a lender type's LTV, DSCR and debt-yield limits') and enumerates the outputs, which cleanly separates it from siblings like match_programs and compare_programs that match or compare rather than size.

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?

It gives a concrete routing rule — 'omit lender_type to size the deal under all five lender types' — which tells an agent how to use the tool for comparison. It does not explicitly say when to prefer this over match_programs or compare_programs, so it falls short of full when/when-not guidance.

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