Motel Loans: hotel loan sizer and franchise costs

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds real context beyond that: the data source (motel.loans FDD database, 48 brands) and provenance fields (FDD year and page) that tell the agent results are citable and static, not live pricing.

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 what the table contains and immediately followed by the filter/sort affordances. The column inventory is dense but each item earns its place by telling the agent what comes back in the absence of an output schema.

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 correctly compensates by enumerating the returned columns and their provenance. All five parameters are optional and schema-documented, and the annotations cover safety; the only real gap is the unstated boundary with get_franchise_costs.

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%, so every parameter is already documented, which sets the baseline at 3. The description adds only light business framing ('lowest Item 7 cost' for item7_low, filter-by-parent/brand wording) and does not explain the fee definitions or what the Item 7 range means, so it stays at baseline.

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+resource: a ranked comparison table of hotel brands with named cost columns, drawn from a named FDD database of 48 brands. An agent can tell it produces a multi-brand ranked table, though it never explicitly contrasts itself with the sibling get_franchise_costs (single-brand lookup).

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 operational guidance for filtering (by parent company or specific brands) and sorting, but never states when to reach for this tool rather than get_franchise_costs. Usage is implied by the 'ranked table' framing rather than asserted against 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?

The annotations already cover read-only, idempotent, non-destructive behavior. The description adds useful context beyond annotations: the data source is a filed FDD, the return includes page references and a filing link, and rooms/revenue drive yearly fee estimates.

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 and front-loads the tool's scope before listing returned fields. The long field list is justified because there is no output schema, though the first sentence is dense.

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 properly enumerates the returned data and explains how optional inputs affect estimates. Annotations cover safety, and schema covers parameters; the main gap is explicit sibling selection guidance.

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%, so the schema already documents brand, rooms, and rooms_revenue including defaults. The description adds purpose for rooms and rooms revenue, explaining they produce yearly percent and per-room fees, but adds no syntax or constraints beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific resource—one hotel brand's franchise costs from its FDD—and enumerates the fee types and investment data returned. It implicitly distinguishes itself from compare_franchise_costs by scoping to one brand, but it does not name that sibling explicitly.

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 tells the agent to provide rooms and rooms revenue to obtain yearly fee estimates, which clarifies optional input usage. However, it gives no explicit guidance on when to use this tool versus compare_franchise_costs or when not to use it.

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 the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds genuinely useful behavioral context beyond that: every figure ships with its SBA or source link and an effective date, and FY 2027 fees are explicitly dated — telling the agent the data is versioned and citable, which matters for a rate/terms lookup. It does not describe pagination or response shape, but with no output schema the enumeration of returned fields largely compensates.

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 front-loads the scope ('SBA program terms for hotel and motel loans') before listing the covered data points. Every clause carries information, though the enumeration is long enough to read as a list of features rather than a prioritized summary.

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 and only one optional parameter, the description does the heavy lifting well by enumerating what comes back (7(a) rates, limits, equity, DSCR, maturity, FY 2027 fees; 504 structure, debenture limit, jobs rule, fees, 25-year rate) plus provenance. The main remaining gap is routing guidance relative to size_hotel_loan, which the description never addresses.

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 single enum parameter is already fully documented with its values and default in the schema. The description adds only implicit context (that 'both' yields both program families), so it neither extends nor undermines the schema. 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 names a specific resource (SBA 7(a) and 504 terms for hotels/motels) and enumerates the exact data points returned (rates, limits, equity, DSCR, maturity, guaranty fees, 504 structure). It is clear what the tool delivers, though it never states a verb like 'retrieve' or 'return' and does not differentiate itself from size_hotel_loan, which an agent might reasonably confuse it with.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied: the framing as 'the terms motel.loans publishes' suggests reference lookup rather than calculation, which distinguishes it in spirit from size_hotel_loan. However, there is no explicit when-to-use statement, no mention of the sibling sizing tool, and no guidance on when to pick program=both versus a single program beyond the schema default.

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 added value is the computation contract: defaults mirror the calculator example, brand/program act as fill-in presets, and explicit overrides win. It also warns that omitting insurance or property taxes overstates NOI, which is genuine behavioral guidance rather than restated annotation.

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 verb and the output list, then the preset/override mechanics. The output enumeration is long but every item is a distinct returned metric, so it earns its space; the sentence is dense but not padded.

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 19 parameters and no output schema, the description carries the return-value burden and does it well by naming NOI, DSCR, max supportable loan, the binding constraint, cap rate, price per key and breakeven occupancy. It does not state units or the failure mode for infeasible deals (e.g., negative DSCR), which is the only remaining gap for a tool of this complexity.

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%, so baseline is 3; the description earns more by explaining cross-parameter interaction the per-field descriptions cannot — brand fills franchise fees from its FDD, program fills rate/amortization/LTP, and the explicit override fields beat both. It also clarifies that loan defaults to price times max loan-to-price, tying the required and optional inputs 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?

Names a specific verb and resource ("Runs the motel.loans hotel loan sizer on your numbers") and enumerates the computed outputs, so the agent knows exactly what it gets back. It does not name its siblings (get_sba_hotel_loan_terms, get_franchise_costs, compare_franchise_costs) to say how it differs from them, 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 by the mechanics described — "Pick a brand to fill franchise fees from its FDD and a program ... to fill rate, amortization and loan-to-price" — which tells the agent how to drive the tool but not when to choose it over get_sba_hotel_loan_terms or compare_franchise_costs. No explicit when-not or prerequisite statement is given.

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