Multifamily Today: HUD Fair Market Rents

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

Annotations already declare read-only, idempotent, closed-world behavior, so the safety profile is covered. The description adds context annotations cannot: the data vintage (FY 2027), the bedroom range covered, that output includes one- and five-year 2-bedroom change, and that results are sorted by the chosen bedroom count.

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 carries the operation, scope, and output shape, followed by one short usage sentence. No filler, and the most decision-relevant detail (counties compared, bedroom sorting) is front-loaded.

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 conveying what comes back: FMRs by bedroom count plus one- and five-year 2-bedroom changes, sorted. That is close to complete for a two-parameter read tool, though it could say more about error behavior for unknown counties.

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%, with minItems/maxItems and the bedroom sort semantics already documented in the schema. The description restates the 2–10 county bound and the studio-to-4-bedroom range but adds no format examples or edge-case behavior beyond that baseline.

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 (compare) and resource (HUD FY 2027 Fair Market Rents), plus the exact scope: 2 to 10 counties, studio to 4-bedroom. This scope naturally separates it from siblings like get_fmr_by_county, get_fmr_by_zip, and get_state_fmr_summary, which are single-place or aggregate lookups.

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 sentence gives concrete usage contexts — comparing rental markets or voucher rent ceilings — which tells an agent when this multi-county comparison is the right pick. It stops short of explicitly naming the sibling tools and when not to use this one, so it is clear context without full routing 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/non-destructive and closed-world, so the description rightly spends its words on substance the annotations cannot: dataset vintage (FY 2027, effective Oct 1, 2026), the FY 2026 carry-over flag, and the depth of historical data (back to FY 2017). It omits any note on error/not-found behavior for unresolvable counties, which is the main remaining 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?

A single dense sentence with zero filler, front-loaded with the dataset and geography before the field list. It is long but each clause carries distinct information; a slight structural cost is that the returned-field list is a comma run rather than a scannable breakdown.

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, so the description correctly takes on the burden of enumerating return contents (bedroom range, FMR area, carry-over flag, 1- and 5-year change, 2BR history). Missing is any mention of behavior when the county cannot be resolved or when FMR data is unavailable for a given area.

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 carry their own format guidance (two-letter state code; 'Travis' or 'Travis County'). The description adds no additional parameter meaning, 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?

States a specific verb+resource: retrieve HUD FY 2027 FMRs for a single county/parish/New England town, and enumerates the exact fields returned. Geographic scope ('one county') implicitly separates it from get_fmr_by_zip and get_state_fmr_summary, but 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 only implied by the scope of the data (single county lookup). There is no statement of when to choose this over get_fmr_by_zip or compare_fmr, nor any prerequisite or exclusion such as what to do if the county name is ambiguous or unmatched.

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 readOnly, idempotent and non-destructive, so the safety profile is handled. The description adds genuinely non-obvious behavior: a ZIP crossing HUD FMR areas returns one row per area, plus effective date (Oct 1, 2026) and the bedroom range returned. It does not describe formatting or empty/ZIP-not-found handling, but that 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?

Three tight sentences, front-loaded with vintage and scope, then return shape, then domain context. Efficient overall, though the mandatory-metro/voucher-payment sentence is background color rather than invocation-critical.

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 explaining returns: studio to 4-bedroom rents, one row per area, and the accompanying HUD FMR area. For a single-param read tool with rich annotations, that is close to sufficient; only error/empty-result behavior is unstated.

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 is a single parameter with 100% schema description coverage including a regex pattern and example, so the schema carries full burden. The description only restates 'for one ZIP code' and adds no format, normalization or edge-case detail 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?

States a specific verb and resource (get Small Area FMR) plus the exact scope: one ZIP code, ZIP-level, studio to 4-bedroom. The ZIP-granularity framing implicitly separates it from get_fmr_by_county and get_state_fmr_summary, so an agent can route without opening the 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 FY/vintage and the note that SAFMRs set voucher payment standards in 65 mandatory metros and are optional elsewhere gives useful applicability context. But it never explicitly says when to prefer this over get_fmr_by_county or compare_fmr, and there is no when-not guidance; usage is only implied by the ZIP-level framing.

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 closed-world, so safety is fully covered. The description adds the payoff: the exact set of metrics and extremes returned, plus the national fallback when state is omitted. It does not mention pagination or precision/rounding, but for a read-only aggregate that is minor.

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, zero waste: the metric inventory is front-loaded and the fallback rule trails immediately after. Every listed item earns its place because no output schema exists to carry that 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 no output schema, the description correctly takes on the burden of describing returns and does it thoroughly, and it explains the zero-required-parameter case. The remaining gap is sibling disambiguation, which matters given three adjacent FMR tools.

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's description already says 'Omit for the whole US.' The description's 'Omit state for the national summary' restates that, adding only the word 'national summary' framing rather than new semantics. Baseline 3 is appropriate for a one-parameter tool whose schema is fully documented.

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 (a state's FY 2027 Fair Market Rent picture) and enumerates exactly what the summary contains: county/town counts, median, low/high 2-bedroom FMR, one- and five-year change, and biggest movers. That aggregate framing implicitly separates it from the per-county and per-zip siblings, but 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 only usage instruction is 'Omit state for the national summary,' which is parameter guidance rather than tool-selection guidance. Nothing tells the agent when to pick this over compare_fmr, get_fmr_by_county, or get_fmr_by_zip, so the routing has to be inferred from the word 'summary.'

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