Dominick Prevete: DSCR Lender Data

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=false, and destructiveHint=false, so the safety and determinism profile is fully covered. The description usefully adds a substantive domain fact (the entity is a brokerage that arranges financing and is not a lender; owner-occupied loans are excluded), but says nothing about caching, determinism, or how the answer is sourced.

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 that front-loads the entity and then lists the returned fields; no filler or repetition. It is long but every clause maps to a concrete piece of the answer.

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 effectively serves as the return contract by enumerating the fields the entity answer provides. For a zero-parameter, read-only lookup this is complete enough for an agent to decide and call 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?

The tool takes zero parameters, so the baseline is 4; there are no inputs whose semantics need explanation.

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 (the National Loan Provider entity) and enumerates exactly what the answer contains — legal name, business model, scope, address, phone, states with data, founder @id. This is clearly distinguishable from siblings like glossary_lookup, hmda_methodology, or rate_ranges without opening any schema.

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 guidance, no prerequisites, and no mention of alternatives among the six sibling tools. The agent must infer from the content list alone that this is the identity/background tool rather than a data or definition tool.

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). The description adds real behavioral context beyond them: case-insensitive matching, partial-match acceptance, the list-all fallback, and the boundary that entries are definitions and not program parameters.

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 sentences, zero waste: scope first, then invocation modes, then the boundary statement that prevents misfires. Well front-loaded and appropriately sized for a one-parameter lookup.

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?

Covers lookup semantics, the no-argument mode, and the content boundary of definitions. With no output schema, a brief note on the returned shape (term plus definition text) would help, but the description is otherwise sufficient for correct invocation.

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 single parameter is fully documented in the schema, so the baseline is 3. The description goes further by specifying case-insensitive and partial-match semantics, which the schema does not state, and restates the omit-to-list-all behavior as a semantic guarantee.

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 (look up / list) and resource (DSCR and investor-loan glossary, 26 terms), with explicit scope. The 'definitions describe what a term is' framing cleanly separates it from sibling tools like loan_programs and rate_ranges, which carry figures rather than definitions.

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?

Explains both invocation modes clearly — pass a term, or omit it to list all terms — so the agent knows when each path applies. The caveat that no entry states a program parameter implicitly routes numeric/parameter questions to loan_programs, but it never names a sibling alternative explicitly.

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 without description helping. The description adds significant value by enumerating exactly what information the tool discloses (filter definition, server-side vs local filtering split, vintage, retrieval date, covered states, limitations), giving the agent a clear picture of the response content.

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 a single, front-loaded sentence that immediately says what the tool provides and then lists its components. There is no filler or redundant text.

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 informational tool with no output schema, the description effectively serves as an output preview by enumerating all the methodology components an agent would receive. Nothing required to call or understand the tool is missing.

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?

There are zero parameters, so the baseline score of 4 applies. The schema description coverage is 100%, but no parameter semantics exist to document.

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 and its scope: it returns the methodology for how investor-lender HMDA data is built, listing the exact components (filter definition, filtering split, vintage, covered states, limitations). This clearly distinguishes it from sibling tools like investor_lenders_aggregate and investor_lenders_by_state, which return figures rather than methodology.

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 noting that the stated limitations should be attached to any figure the agent reports, but it does not explicitly say when to call this tool versus alternatives such as about_national_loan_provider or glossary_lookup. The guidance is inferable rather than directly stated.

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 real behavioral content beyond them: the aggregation grouping (LEI), the ranking criterion and year, the derived fields returned, and a reference rendering of the same computation for output expectations. No pagination or truncation behavior is stated, which keeps it from a 5.

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 compact sentences that front-load the computation and its scope before the URL reference. The final clause restates the 26-state scope already given, which is mild redundancy, though it works as deliberate routing emphasis. Little wasted text overall.

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 must carry return-value expectations, and it does: ranked rows grouped by LEI, per-filer state counts, universe totals, and a concentration share. An agent knows what comes back and on what basis it is sorted. Missing only edge behavior such as empty/short-universe handling or truncation semantics.

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?

Only one parameter with 100% schema description coverage, so the schema already documents range and default. The description's 'top-25 concentration share' echoes the default limit but does not explain how limit interacts with the concentration metric or whether rows are truncated, so it adds little parameter meaning 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?

The description names the specific resource (every HMDA filer), the grouping key (LEI), the ranking metric and vintage (2025 investor-property loan count), and the computed fields (states reported in, universe totals, top-25 concentration). It also distinguishes itself from siblings by pinning scope: 'A 26-state aggregate, not a national one,' which separates it from investor_lenders_by_state and about_national_loan_provider.

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?

Scope is stated clearly enough to route an agent: 26 covered states, cross-state aggregation, not national. The closing 'not a national one' functions as an implicit exclusion against the national-scope siblings, and 'cross-state aggregate' contrasts with the by-state sibling by naming convention. It stops short of an explicit 'use X instead when you want per-state rows,' so it is context rather than 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.

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

Annotations already carry readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely new context beyond those flags: the data vintage (2025 HMDA loan-level), the retrieval date in the payload, and the caveat that figures are the filing record rather than a recommendation. What it does not disclose is pagination or truncation behavior relative to the limit.

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 that front-loads the scope (top investment-property lenders, one state) before the data source and returned fields. Nothing is padded, though cramming the field list and the disclaimer into one sentence makes it slightly harder to scan than a short two-line split would.

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, and the description compensates by enumerating the returned fields (lender name, LEI, loan count, volume, average loan, purchase share, plus state totals and retrieval date). That is close to complete for a two-parameter read tool; only ranking basis and limit/truncation behavior are unspecified.

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%: 'state' enumerates the 26 valid codes and 'limit' documents its 1–50 range and default. The description adds no syntax or format detail beyond that, so the baseline 3 is correct when the schema does all the parameter work.

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: it returns top investment-property lenders for a single state, sourced from 2025 HMDA loan-level data. That is enough to separate it in spirit from investor_lenders_aggregate, but the description never names or contrasts the sibling, so the differentiation 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: 'in one of the 26 covered states' signals that this is the per-state slice, which hints at when to pick it over the aggregate sibling. There is no explicit when-to-use, when-not-to-use, or named alternative, so it stays at minimum-viable 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 readOnly, idempotent, and closed-world. The description adds a genuinely useful behavioral trait beyond them: the null-fidelity rule that absent figures are reported as absent rather than filled in. That directly informs how an agent should interpret returned 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?

Front-loaded and dense, but it redundantly re-enumerates all eight program keys that the schema already lists, which inflates a single sentence considerably. The fidelity clause earns its place; the enum restatement does not.

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 carries the return-value burden and does so reasonably: it names the fields returned (parameters, starting rate with as-of stamp, page URL) and the null-handling rule. Only the routing question of when to prefer this over rate_ranges or investor_lenders_* is left unaddressed.

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 single enum parameter and its 'omit for all' behavior are already fully documented. The description repeats the enum list in prose without adding format, defaulting, or filtering semantics beyond what the schema provides.

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 (the National Loan Provider program set) and enumerates exactly what each entry contains: published parameters, starting rate with as-of stamp, and page URL. This clearly distinguishes it from siblings like rate_ranges or about_national_loan_provider, though the description never uses an explicit verb such as 'returns' or 'lists'.

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 guidance and no named alternatives among the siblings. The only quasi-guidance is a data-fidelity rule ('where a page states no figure, the tool states no figure'), which describes output behavior rather than selection context. An agent must infer that omission of the program key returns all programs.

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 still adds real value beyond them: data provenance (single rate source), a staleness signal (as-of month, currently October 2026), and the semantic caveat that these are indicative published ranges, not quotes.

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, no filler, with the core capability front-loaded before the scope caveat. Every clause carries information the structured fields do not.

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, zero-required-parameter lookup with no output schema and full schema coverage, the description supplies the interpretive context an agent needs (provenance, as-of date, indicative vs. deal pricing). It stops short of describing the shape of the returned ranges, a minor gap given no output schema exists.

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% with a single enum parameter fully documented in the schema, so baseline 3 applies. The description's 'by program' phrase merely restates the filtering the schema already defines and adds no syntax or format detail.

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: returns indicative starting rates by program from a single rate source. The second sentence explicitly scopes out deal-specific pricing, which helps an agent distinguish this from any pricing tool. However it never names or contrasts itself against siblings like loan_programs, so differentiation is implicit rather than 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?

Usage is implied — an agent can infer you call this to look up published rate ranges. The caveat 'not pricing on any deal' functions as a scope guard rather than a when-to-use rule, and no alternative tool or condition is named. No explicit when/when-not guidance is present.

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