HMDA Mortgage Data

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

With no annotations, the description must disclose behavioral traits. It states that the tool returns summary statistics, but it does not clarify important behaviors such as whether state and county_fips are mutually exclusive, how invalid inputs are handled, or what data source is used. The lack of detail beyond the immediate return format leaves the agent uncertain about edge cases and constraints.

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 efficiently structured: a one-line summary, a sentence on return values, and a compact args list. Every sentence provides necessary information without redundancy or fluff. The front-loaded summary immediately orients the agent.

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?

The description explains the purpose, return values, and parameter formats, which is decent for a retrieval tool. However, it lacks guidance on how state and county_fips interact (e.g., are they alternatives, or can both be provided?), and it does not mention any usage limitations. Since an output schema exists, return structure is covered, but the missing parameter relationship is a notable 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 0%, leaving the description to carry the full burden. The description provides meaningful parameter details: state is 'Two-letter US state abbreviation (e.g. 'CA', 'TX')', county_fips is 'Five-digit county FIPS code (e.g. '06037' for LA County)', and year has a default. This adds clear format and example information, though it does not explain parameter dependencies or whether at least one is required.

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 tool's function: 'Get aggregate mortgage lending statistics for a geographic area.' It specifies the resource (aggregate stats) and the verb (get), and mentions returns such as applications, originations, denials, and loan amounts. It does not explicitly differentiate from sibling tools like get_denial_reasons or get_lending_by_race, but the 'aggregate' scope provides implicit distinction.

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 a clear use case: 'Useful for understanding overall lending activity in a state or county.' This indicates when to use the tool but does not provide exclusions or references to alternatives like the sibling tools. No explicit when-not-to-use guidance is given, so it falls short of a 5.

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?

No annotations are provided, so the description carries the full burden. It clearly states that the tool returns a distribution of denial reasons, implying a read-only operation. It does not mention any side effects, permissions, or error behaviors, but for a 'Get' tool this is adequate. However, it omits details about parameter combinations (e.g., whether state and county_fips are both required), which could affect behavior.

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 concise and well-structured: three short sentences plus an Args list. The first sentence states the core function, the second explains the output, and the third provides context. Every sentence has clear value with no 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?

The description covers the tool's purpose, output type, use case, and all parameters with examples. An output schema exists, so return value details are not needed. However, it does not clarify whether state and county_fips are individually sufficient or must be used together, nor does it explain the implications of leaving all parameters optional. This is a minor but notable 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 0%, but the description's Args section fully compensates. Each parameter is explained with format and examples: state is 'two-letter US state abbreviation', county_fips is 'five-digit county FIPS code (e.g. 06037)', and year is 'data year (e.g. 2022)' with a default. This is exemplary parameter documentation.

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 tool's purpose: 'Get mortgage denial reasons breakdown for a geographic area.' This specifies a concrete action ('Get') and resource ('mortgage denial reasons breakdown') with a geographic scope, which distinguishes it from sibling tools like get_aggregate_stats or get_lending_by_race.

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 provides a clear use case: 'Useful for identifying barriers to homeownership in specific communities.' This gives context for when to apply the tool, though it does not explicitly contrast with sibling tools or state when not to use it. The guidance is sufficient but lacks direct exclusions or alternative recommendations.

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?

No annotations are provided, so the description must fully disclose behavioral traits. It mentions that it returns origination and denial data and that year defaults to 2022, but it omits critical details such as data source, geographic aggregation level, permission requirements, or what happens when only part of the arguments are supplied. This is a significant transparency gap.

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 concise and well-structured: a front-loaded purpose sentence, a brief return/use-case sentence, and a neatly formatted Args section. Every sentence earns its place with no redundancy or 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?

The presence of an output schema reduces the need to explain return values. However, the tool has three optional parameters with no stated interactions or minimum required combination, and there are no annotations for safety or side effects. The description covers the basics but leaves gaps about data scope and partial-argument behavior.

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 provides no parameter descriptions (0% coverage), but the description adds meaningful context for each parameter: state uses two-letter abbreviation examples, county_fips uses a five-digit example, and year includes a default. This compensates well, though the relationship between state and county_fips is not explained.

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 opens with 'Get mortgage lending patterns disaggregated by race and ethnicity' — a specific verb and resource with a clear modifier. This distinguishes it from siblings like get_aggregate_stats (aggregate) and get_denial_reasons (denial-focused), leaving no ambiguity about its purpose.

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 explicitly states 'Useful for fair lending analysis and identifying disparities in mortgage access,' providing a clear context for when to use this tool. It doesn't explicitly name alternative tools or exclusions, but the use case is sufficiently distinct from siblings.

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?

No annotations are provided, placing full burden on the description. It discloses that the tool 'Returns mortgage application and origination records', which is useful, but does not mention potential behaviors like pagination, rate limits, or error handling when no filter is supplied. The recommendation to limit results hints at data volume but doesn't go further.

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 front-loaded with the core purpose, followed by a concise second sentence on what it returns and a recommendation. The Args list is structured and each parameter explanation earns its place. No fluff or redundancy.

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 data retrieval tool with six parameters and no annotations, the description covers parameter semantics, defaults, and a usage recommendation. However, it lacks details about pagination, max limit enforcement, or behavior when no geographic filter is given. Since an output schema exists, return values are not needed here, but more operational context would make it fully 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?

The Args section thoroughly explains every parameter: state and county_fips formats, year default, action_taken codes with meanings, loan_type codes, and limit default/max. This adds substantial meaning beyond the bare schema, compensating fully for the 0% schema_description_coverage.

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 identifies the tool as retrieving 'Home Mortgage Disclosure Act (HMDA) loan-level data', distinguishing it from sibling tools like get_aggregate_stats by explicitly stating 'loan-level data'. The verb 'Get' and resource specificity make the purpose unambiguous.

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?

Provides explicit guidance that 'At least one geographic filter (state or county_fips) is recommended to limit results', which is a clear usage instruction. However, it does not explicitly mention alternatives or when to prefer this over sibling tools, though the loan-level vs aggregate distinction implies it.

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