HUD Housing Data

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly states the tool requires a HUD User API token and 'returns registration guidance if token is not configured', which is a valuable behavioral trait. It also explains the county_fips default behavior (statewide data when omitted). However, it does not cover error handling, rate limits, or response details, warranting a 4 rather than 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?

The description is front-loaded with the core action, then provides a brief usage context, token requirement, and a structured Args section. It is appropriately sized for a three-parameter tool, though the opening two sentences overlap slightly and could be condensed.

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?

Given the tool's moderate complexity (3 parameters, output schema exists), the description covers purpose, token auth, parameter semantics, and scoping behavior. The output schema handles return-value documentation, so the description is sufficiently complete for selection and invocation. The only minor gap is explicit comparison to sibling tools, which is covered under usage guidelines.

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 input schema has zero description coverage, so the description must fully compensate. It thoroughly explains each parameter: state as a two-letter abbreviation with examples, county_fips as an optional 5-digit code with LA County example and statewide fallback, and year as fiscal year with default 2024. This adds substantial meaning beyond the raw property names.

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 HUD Fair Market Rent (FMR) values for 0-4 bedroom units', a specific verb and resource that clearly distinguishes it from sibling tools like get_income_limits or get_housing_vouchers. It also explains the programmatic purpose (Housing Choice Voucher payment standards), reinforcing the tool's identity.

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 clear context for when to use this tool via 'used to determine Housing Choice Voucher payment standards and other HUD program parameters'. It also discloses the API token prerequisite and fallback behavior, but it does not explicitly name alternatives or exclusion criteria, so it stops 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 transparency burden. It discloses the data source (HUD Exchange via ArcGIS), the fact that no API key is required, and the annual PIT count nature. While it does not mention rate limits or pagination, the read-only nature is clear from the verb 'Get' and the context, making the description genuinely informative.

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 moderately detailed but well-organized, with a clear summary followed by an Args section. Each sentence adds value (source, auth, parameter details), though it could be tightened by moving some examples to the schema if it had better coverage. Still, it is efficient and readable.

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?

Given the output schema exists, the description need not explain return values. It covers what data is returned, source, authentication, and parameter constraints. It does not specify default behavior for omitted year or interaction when both state and coc_code are given, but these are minor gaps for a data retrieval tool.

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?

With 0% schema coverage, the description fully compensates by explaining every parameter: state with example format, coc_code with example, and year as optional. It also adds critical constraint information, stating that at least one of state or coc_code must be provided, which is absent from 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 clearly states the tool gets Point-in-Time homeless count data, with a specific resource (PIT counts by CoC region) and explicit breakdowns (sheltered/unsheltered, sub-populations). It is unambiguous and distinct from sibling tools that deal with rents, vouchers, income limits, and public housing.

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 for obtaining homeless count data but does not explicitly contrast with sibling tools or state when to avoid using it. It provides no direct alternatives or exclusions, relying on the distinct resource name to signal appropriate use.

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 discloses the data source (HUD ArcGIS open data), the auth requirement (none), and the specific return content (total vouchers, utilization rates, spending), conveying a safe read-only retrieval. It doesn't mention rate limits or error behavior, but for a GET-style tool with an output schema, this is a minor 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 compact and front-loaded with a clear one-liner, followed by a brief parameter list. Every sentence earns its place with no filler or repetition of schema details beyond what is helpful.

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?

An output schema exists, so return-value details are covered elsewhere. The description adds the essential data source, auth status, filtering dimension (state), and limit behavior, making it complete for a simple two-parameter retrieval tool.

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%, and the description fully compensates. It explains 'state' as a two-letter US abbreviation with examples, and 'limit' as the maximum number of records with default and max values, adding a max constraint (500) not present in 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 opens with a specific verb+resource: 'Get Housing Choice Voucher (Section 8) program data by Public Housing Agency.' It clearly differentiates from sibling tools by naming the exact HUD program and the type of data returned (vouchers, utilization, spending).

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 makes the tool's scope obvious ('by Public Housing Agency', 'in the specified state') and notes 'no auth required,' which is useful for when it can be invoked. It doesn't explicitly state 'use this vs. sibling X,' but sibling names are distinct enough that the intended use is clear.

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 discloses the API token requirement and the fallback behavior for missing county_fips, but does not mention read-only nature, error handling, rate limits, or response format details. While 'Get' implies a safe read, more behavioral specificity would be ideal.

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 well-structured with a purpose sentence followed by an Args block. The first two sentences have slight redundancy ('Get HUD income limits' and 'Returns income limit data'), but overall it is concise and front-loaded. Every sentence adds useful 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?

With an output schema present, return values are covered. The description covers the essential parameters, auth, and fallback behavior. It does not clarify what 'by family size' means in relation to the absence of a family_size parameter, which is a minor gap, but overall it is complete enough for a straightforward data retrieval tool.

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?

Despite 0% schema description coverage, the Args section explains all three parameters: state with examples, county_fips with optionality and behavior, and year with default. This adds meaning beyond the bare schema, making it easy to invoke correctly.

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 'Get HUD income limits (very low, low, median) by family size', which identifies the specific resource and action. This distinguishes it from sibling tools like get_fair_market_rents or get_homeless_data by naming HUD income limits directly.

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 provides context about the data being used for HUD eligibility, requires an API token, and explains the behavior when county_fips is omitted (returns all areas in the state). It does not explicitly mention alternative tools or exclusions, but the usage context is clear enough for a data lookup 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?

No annotations are provided, but the description carries the burden well. It discloses that the tool 'Queries HUD's open ArcGIS data' (read-only behavior), 'No API key required' (auth requirements), and lists the return content. This goes beyond the schema and gives the agent confidence that nothing is modified.

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 efficient and front-loaded. The first sentence gives the primary purpose. Each subsequent sentence adds essential detail (data source, auth, return content, parameter explanations) without any redundancy or fluff.

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?

Given the tool's simplicity and the presence of an output schema, the description covers all necessary aspects: data source, auth requirements, parameter semantics, and return content. Nothing critical is missing for an agent to correctly select and invoke the tool.

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 compensates fully. It explains state as a two-letter abbreviation with examples, city as an optional filter, and limit with default and max values. This adds critical meaning that the bare schema properties lack.

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 explicitly states 'Get public housing buildings and developments in a state,' which is a specific verb+resource with scope. It further elaborates that it queries HUD's open ArcGIS data and returns building names, addresses, unit counts, and PHA info, clearly distinguishing it from siblings like get_fair_market_rents.

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 clear context for when to use the tool: when public housing inventory data is needed for a state, with optional city and limit filters. It does not explicitly name alternatives or exclusions, but the focus on public housing buildings and developments makes its use case unambiguous among the housing-related siblings.

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