Yacht.Loans: boat loan calculator, sales tax and lender terms

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

Annotations already declare a safe, read-only, idempotent, closed-world calculation, so the safety bar is met elsewhere. The description earns credit by disclosing the computation model beyond annotations: balloon arises when payments are amortized over more years than the term, sales tax comes either from a state rule or a user rate and cap, and per-year balances are returned. No contradiction with 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?

A single front-loaded sentence that leads with the verb and resource before enumerating outputs. Dense but every clause names a distinct returned value. The output enumeration runs long and could be tightened, but nothing is 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?

No output schema exists, so the description must describe the return values — and it does, listing payment, payment with insurance, amount financed, balloon, total interest, sales tax, cash at closing and annual balances. Combined with a fully documented 12-parameter schema and clear read-only annotations, an agent has everything needed to invoke and interpret it.

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 each of the 12 parameters already carries a full description including defaults, ranges, mutually exclusive pairs and the balloon mechanic. The tool description adds no parameter-level guidance beyond what the schema states, so the baseline of 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?

Specific verb+resource: "Runs the yacht.loans boat loan calculator on your numbers," then enumerates exactly which figures come back (payment, balloon, tax, cash at closing, year-end balance). An agent knows precisely what the tool computes. It never names or contrasts with siblings like get_boat_sales_tax or list_boat_lender_terms, so sibling differentiation is left to the tool 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?

No when-to-use, when-not-to-use, or alternative routing appears in the description. A reader must infer that this is the arithmetic-only path and that get_boat_sales_tax or list_boat_lender_terms supply inputs. Nothing signals prerequisites such as supplying your own APR quote versus looking one up.

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 openWorld false, so the safety profile is covered. The description adds useful behavioral context by naming the included fee components and citing 46 CFR 67.550, though it does not explain return format or calculation assumptions beyond what the parameter schema provides.

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 front-loaded sentence with no filler, and it efficiently lists the relevant fee categories. It is dense but appropriately sized for the tool's scope.

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 fee calculator with four optional, fully documented parameters and no output schema, the description gives enough domain context to call the tool correctly. It could be stronger by explicitly stating what the return value contains, such as a total and fee breakdown.

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 schema already documents the meaning, rates, defaults, and constraints of all four parameters in detail. The description enumerates some corresponding fee components but adds little parameter-level meaning 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 calculation verb and resource: summing Coast Guard NVDC documentation fees for a financed recreational boat, with a legal citation and enumerated fee components. This is clearly distinguishable from the sibling tools for loans, sales tax, and lender terms.

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 usage by specifying a financed recreational boat and USCG documentation fees, but it does not explicitly say when to choose this tool over alternatives or when not to use it. The context is clear but 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 readOnlyHint, idempotentHint, and closed-world scope, so the safety profile is covered. The description adds meaningful provenance (confirmed from statute or tax agency, with the date it was read) and signals a bounded dataset, but says nothing about freshness limits beyond the read date or whether missing states are possible.

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?

Effectively one front-loaded sentence that leads with the resource and then the return fields, with the enumeration case at the end. The parenthetical examples (California's 12-month test, Florida's $18,000 cap) are slightly verbose but genuinely illustrate the exemption field.

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?

No output schema exists, but the description compensates by listing the returned fields (rate, cap, exemptions, citation, source URL, read date) and the multi-record mode when state is omitted. An agent knows exactly what to expect back.

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 parameter is fully documented with both code and name formats. The description's "Omit state to list every state covered" repeats the schema's own wording rather than adding new semantics, so 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 and resource (the boat sales/use tax rule for a state) and immediately enumerates what it returns: rate, cap, exemptions or special tests, citation, source URL, read date. This is clearly distinct from the sibling tools, which cover loan math, documentation fees, and lender terms.

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 context for the no-argument case ("Omit state to list every state covered"), which tells an agent how to enumerate coverage. It does not name when to prefer a sibling or any exclusion, but the siblings are different domains, so there is little ambiguity.

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, non-destructive, closed-world behavior. The description adds meaningful context beyond them: the data is read from lender pages by yacht.loans, rate ranges carry dates, and results are neither offers nor rankings. It does not discuss pagination or rate limits, but those are minor given 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?

Two sentences, front-loaded with the resource and followed by filtering/exclusion guidance. Dense but every clause contributes useful scope or field 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 two-optional-parameter read-only list with rich annotations and full schema coverage, the description supplies the source, returned fields, and exclusions. It could mention result ordering or pagination, but no output schema exists and the core call context is complete.

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 both parameters are fully described in the schema, including the kind enum. The description only restates 'filter by lender type or name' without adding format or edge-case guidance, so it meets the baseline but adds little.

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 resource—boat loan terms published by banks, credit unions, marine lenders, and brokers—and enumerates the fields returned, so the agent knows this is a lookup of lender-published terms rather than a calculator. The closing 'not offers and not a ranking' further distinguishes it from adjacent financial 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?

It tells the agent to filter by lender type or name and explicitly excludes offers/rankings, giving clear usage context. It does not name calculate_boat_loan or state when to prefer that sibling, so it stops short of full alternative routing.

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