Dominick Prevete: DSCR Lender Data

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds useful semantic context - that the entity is a mortgage brokerage arranging financing and 'not a lender', plus the owner-occupied exclusion - which shapes how results should be interpreted. It does not discuss return format or any constraints, which is acceptable for a static fact tool.

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 a single front-loaded sentence that opens with the purpose ('the entity answer') before the field list. The enumeration is long but each item corresponds to a distinct fact an agent would query for, so it mostly earns its place.

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 burden of describing what is returned, and it enumerates the returned content thoroughly. The only gap is the structural shape of the response (flat fields vs. linked entities), which is a minor omission for a zero-argument lookup.

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 to disambiguate and the baseline of 4 applies. The description adds no parameter guidance, but none is needed.

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 resource (the entity answer about National Loan Provider) and enumerates the specific facts returned: legal name, business model, address, phone, covered states, and the founder's canonical Person @id. It is concrete enough that an agent knows this is the identity/background card. It stops short of explicitly distinguishing itself from siblings like glossary_lookup or hmda_methodology, so it is clear but not sibling-differentiated.

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 listing what questions it answers (legal name, address, broker-vs-lender status), it signals that identity/context questions belong here. There is no explicit when-to-use, no exclusions, and no mention of the sibling tools that cover terminology, methodology, or lender aggregates.

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-open-world), so the description's job is to add context — it does so with case-insensitivity, partial matching, and the explicit warning that definitions describe concepts and never state a program parameter, which prevents misuse.

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 short sentences, front-loaded with what it is, then how to call it, then the scope caveat. 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?

For a single-parameter, fully annotated, read-only lookup with no output schema, the description covers identification, both call modes, matching rules, and the notable limitation that no definition contains program parameters. Nothing needed to call it correctly 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?

Schema coverage is 100% and already documents the single optional 'term' parameter, so the baseline is 3; the description adds matching semantics (case-insensitive, partial matches accepted) that the schema does not specify.

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), which is immediately distinguishable from sibling tools like loan_programs or rate_ranges that return program data 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?

Clearly describes both invocation modes (pass a term vs. omit to list all) and matching behavior, giving an agent enough to pick the right call. It stops short of naming an alternative tool for program parameters, though the final sentence implies that boundary.

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 bar is met. The description adds substantive content disclosure — that the response contains a filter definition, a server-side vs local filtering split, vintage and retrieval date, covered states, and limitations — which tells the agent what it will actually receive beyond the annotation profile.

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 announces the topic and then enumerates the returned components with no filler. It is dense but every clause maps to a distinct piece of 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?

For a zero-parameter, read-only reference tool with no output schema, the description enumerates the returned content well enough that an agent knows what to expect. It could be marginally stronger by noting the tool returns no query parameters or that it is a static reference, but nothing essential for correct invocation 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?

The schema is an empty object with zero parameters, so there are no parameter semantics to convey; per the 0-param baseline this scores 4. The description correctly avoids inventing 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?

States a specific, non-tautological purpose: it returns the build methodology behind the investor-lender data, enumerated as filter definition, filtering split, vintage/retrieval date, covered states and limitations. An agent can tell this is the reference/lineage tool rather than a data-returning sibling like investor_lenders_aggregate or investor_lenders_by_state, though no sibling is named 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?

The closing clause ('the stated limitations an agent should attach to any figure it reports') gives actionable context for when to consult it — alongside reporting of any figure. It stops short of explicitly contrasting with the sibling data tools or stating prerequisites, but the usage context is clear rather than merely implied.

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 non-destructive, so safety is covered. The description goes further by disclosing the output shape (LEI grouping, loan-count ranking, per-filer state counts, universe totals, top-25 concentration) and pinning the data vintage to 2025 — context the annotations do not carry.

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, front-loaded with the computation, then the reference URL, then the scope caveat. The URL sentence is slightly extraneous but does give a verifiable reference for the computation; overall tight.

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 describe returns, and it does enumerate the aggregate's components (LEI groups, ranking, state counts, universe totals, top-25 share). Only the exact field naming/format is left implicit, which is a minor gap for a read-only aggregate.

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 'limit' parameter (1–50, default 25) is fully documented in the schema. The description adds nothing about the parameter, so the baseline 3 is correct.

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 operation (aggregate HMDA filers grouped by LEI, ranked by 2025 investor-property loan count) over a specific scope (15 covered states). The closing clause 'A 15-state aggregate, not a national one' lets an agent separate it from the sibling investor_lenders_by_state 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?

The scope note ('15-state aggregate, not a national one') implicitly tells the agent when this tool is appropriate versus a national rollup. However, no sibling is named explicitly and there is no explicit when-not guidance, so the routing signal is only implied.

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, so the safety profile is covered (and 'Read-only' in the text is mostly redundant). The description earns credit for adding genuine context the annotations do not: the data source and vintage (2025 HMDA loan-level data), the retrieval date, and the 'filing record, not a recommendation' caveat.

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 core purpose, then the returned fields, then the caveat. Two sentences with almost no waste, though the field enumeration makes the first sentence 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 compensates by enumerating the return fields and the data provenance, and the safety profile is carried by annotations. Complete enough to invoke correctly; only the sibling differentiation against investor_lenders_aggregate is left 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?

Schema description coverage is 100% – both parameters (state enum list and limit range) are fully documented in the schema. The description adds nothing beyond confirming the state scoping, 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?

States a specific resource (top investment-property lenders) with a clear scope (one of 15 covered states) and enumerates the returned fields (lender name, LEI, loan count, volume, average loan, purchase share, state totals, retrieval date). The 'by state' scoping implicitly separates it from the investor_lenders_aggregate sibling, but it never names that sibling to make the distinction 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?

Context is implied – the state-scoped dataset signals when this is the right tool – but there is no explicit when-to-use/when-not and no pointed reference to investor_lenders_aggregate for national or aggregate views. The agent must infer the routing from the name and scope 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, closed-world behavior. The description adds genuine context beyond that: rates come from a single site rate source with an as-of stamp, and the honesty clause ('where a page states no figure, the tool states no figure') tells the agent to expect nulls rather than fabricated values.

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 enumerations and provenance details are front-loaded in a dense but waste-free pair of sentences. Slightly heavy for a read tool, but every clause (rate source, as-of stamp, URL, null policy) earns its place.

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 the work of describing the return shape (per-program parameters, starting rate, page URL) and the null-handling policy, which is enough for an agent to call it correctly. It stops short of specifying the response envelope or whether rates are numeric or strings.

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 program parameter is fully documented there, so the description's re-listing of the same keys adds no new syntax or semantics. 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 names the specific resource (the National Loan Provider program set) and enumerates exactly what each record contains: program parameters, starting rate with as-of stamp, and page URL. The purpose is unmistakable, though it does not explicitly contrast itself with siblings like rate_ranges or investor_lenders_aggregate.

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 content (fetch published loan-program specs and starting rates), but the description offers no when-to-use guidance and never names an alternative tool such as rate_ranges for rate-only queries. The optional program filter is the only routing signal an agent gets.

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, closed-world), so the description focuses on value-add: the single rate source, the as-of month stamp, and the current vintage (September 2026). Calling out that these are published ranges rather than deal pricing is genuinely useful disclosure beyond 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 tight sentences, front-loaded with what the tool returns and immediately qualified by scope and currency. Every clause earns its place; nothing is repeated from the 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 does the work of sketching the return shape (ranges by program, month-stamped) and the freshness caveat. Only missing element is what happens when 'program' is omitted, which the schema's optionality leaves ambiguous.

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 'program' parameter already lists all seven accepted values, so the schema carries the burden. The description only echoes 'by program' without adding format, default-behavior, or multi-value 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?

States a specific resource (indicative starting rates) and scope (by program, from the site's single rate source). An agent can distinguish it from loan_programs or investor_lenders_aggregate by the 'rates' framing, though no sibling is named 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?

Usage is implied rather than stated — the reader infers 'call this to see rate ranges.' The 'not pricing on any deal' caveat usefully sets expectations about what the tool is not, but gives no explicit when-to-use or alternative-tool routing.

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