SNF Register: nursing home owners, CMS ratings and HUD 232 loans

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

Annotations already declare readOnly/idempotent/closed-world, so safety is covered. The description adds genuine value beyond that by disclosing the breadth of returned content, including matched FHA-insured HUD 232 loans with note rate, balance, maturity and servicer — context an agent can't infer from annotations. It does not mention behavior when no match is found or that owners may be truncated at max_owners.

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 identifies the lookup key first, then the payload. It is dense but every clause corresponds to real returned data; the loan-detail clause is slightly long but justified given no output 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 carries the burden of telling the agent what comes back, and it does so thoroughly across clinical, ownership and loan dimensions. The only gap is not noting the record's owner-list cap or empty-match behavior, which is minor for a read-only 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?

Schema description coverage is 100%, with both ccn and max_owners fully documented including format, range and how to obtain a CCN. The description adds no parameter-level meaning beyond the schema, 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 verb and resource ('One nursing home's SNF Register record by CCN') and then enumerates exactly what that record contains (beds, occupancy, star ratings, staffing, fines, ownership, HUD 232 loans). This clearly distinguishes it from search_nursing_homes and list_hud_232_nursing_home_loans, which operate over sets.

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 'by CCN' framing makes clear this is the single-record detail lookup in contrast to the search/list siblings, so implied usage is strong. It stops short of explicitly naming alternatives or exclusions (e.g. 'use search_nursing_homes first to obtain a CCN'), which the schema description supplies instead.

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 the safety profile is covered. The description adds value by enumerating exactly which metrics come back (occupancy, star spread, turnover, PE/REIT flags, HUD 232 activity), which tells the agent what data it gets. It says nothing about aggregation method, time window for "recent ownership changes," or result shape.

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?

One dense sentence that front-loads the scope (state or US) before the metric list. The metric enumeration is long but each item is distinct information an agent needs to judge coverage; nothing is redundant 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?

With one optional parameter, full schema coverage and annotations covering the safety profile, the main open question is what the tool returns – and the description answers that by listing the metric categories, since no output schema exists. Missing only minor detail on aggregation windows and response shape.

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 optional parameter is fully documented in the schema (pattern, examples, "Omit for the US"). The description only repeats the omit-for-US rule, adding no new syntax or format detail, so 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+resource: an aggregate "roll-up" of nursing homes for a state or the US. The word "roll-up" implicitly distinguishes it from get_nursing_home (single facility) and search_nursing_homes, but it never names those siblings or rank_states_nursing_homes, 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?

The only usage instruction is "Omit state for the US," which is a parameter rule rather than guidance on when to pick this tool. Nothing tells the agent when to use this roll-up versus rank_states_nursing_homes or get_nursing_home, so the routing is only implied by the word "roll-up."

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?

The annotations already establish that this is a non-destructive, idempotent, read-only operation. Beyond that, the description adds meaningful behavioral context: it says the loans are matched to CMS-certified nursing homes and lists the exact facility, loan, and servicer fields returned.

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 two dense sentences that front-load the resource and returned fields, then summarize filtering and sorting. It is efficient with no filler, though the second sentence is quite packed.

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 usefully enumerates the returned fields so the agent knows what to expect. Combined with complete parameter documentation and read-only annotations, it is nearly complete, though it could mention default status behavior or paging more explicitly.

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 all 11 parameters are already well documented in the schema. The description groups the filters and sort options but adds no syntax or behavioral detail beyond what the schema provides, making the baseline 3 appropriate.

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 resource as FHA-insured HUD Section 232 loans matched to CMS-certified nursing homes and enumerates the returned fields, so the agent knows exactly what data this tool exposes. However, it does not explicitly distinguish this listing tool from the related sibling size_hud_232_refinance, which likely also deals with HUD 232 loans.

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 useful implied usage guidance by listing the available filter and sort dimensions. It does not state when to use this tool instead of sibling tools such as size_hud_232_refinance, so an agent must infer routing from the tool name and parameter list.

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 description's contribution is the output shape — "Returns value, rank and state page" — which annotations can't express. It also pins the geographic universe (states, DC, PR, GU), consistent with the schema's maximum of 53. Minor gap: no note on tie-breaking or how missing measures are handled.

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 verb and scope, then a compact return-value sentence — nothing is wasted. The middle is a dense run of metric names without grouping, which reads more like an enum dump than prose, but it stays within one sentence.

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 3-parameter, single-output ranking tool with no output schema, the description covers scope, the metric dimension, and the returned fields (value, rank, state page). What an agent needs in order to call it correctly is present; only edge-case 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?

Schema description coverage is 100%, so the baseline is 3; every parameter including all 17 enum values is documented in the schema. The description's metric enumeration restates the enum rather than adding semantics such as whether PE/REIT flags are shares or counts, or how ordinal ranks are assigned.

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 ("Ranks the states... on one nursing home measure") and enumerates the metric families covered, so the agent knows this is a cross-state aggregate ranking rather than a facility-level lookup. This clearly separates it from siblings like get_state_nursing_homes (per-state facility lists) and search_nursing_homes.

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 "on one nursing home measure" — the tool returns a single-metric leaderboard — but there is no explicit when-to-use/when-not statement and no sibling is named as an alternative. An agent must infer that this is the comparison tool while the siblings are retrieval tools.

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, so the safety profile is covered. The description adds genuinely new context the annotations lack: the 14,000+ corpus size and an enumeration of returned fields including HUD 232 loan match status (active, past, none) and the SNF Register page. It omits paging behavior and what happens with zero filters, keeping it below 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 sentences, both front-loaded with the operation and then the handoff. The middle clause is a long comma-separated return-field list that reads as a run-on, but every element is substantive rather than 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?

With no output schema, the description carries the return contract itself and does so field by field, which is exactly what an agent needs. Combined with the 100%-covered input schema and annotations, nothing blocking a correct invocation is missing, aside from minor filter-combination nuance.

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 all eight parameters are self-documenting with examples, enums and defaults, making 3 the baseline. The description only echoes the name/city/state match axes and does not mention that min_stars or hud_loan act as filters (it presents loan status only as a result field), so it adds little beyond 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?

Names a specific verb and resource ('Searches the 14,000+ CMS-certified nursing homes') and pins down the three matching axes (name, city, state) plus the exact fields returned. It also routes the agent to get_nursing_home for detail lookup, so the boundary with that sibling is visible without opening a 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 final sentence 'Use the CCN with get_nursing_home' gives explicit downstream usage for the primary key returned. It does not, however, distinguish this search from get_state_nursing_homes or rank_states_nursing_homes, so the agent must infer when a broad listing or state ranking is preferable.

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, so the safety profile is covered; the description adds value by listing the outputs and disclosing the CCN auto-fill convenience behavior. It does not mention that rate is a user assumption rather than a HUD-set figure (that lives only in the schema), leaving a small 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?

Front-loaded with the operative verb and tightly packed — two sentences, no filler, and the return-value list is dense but useful. The first sentence is long and list-like, which costs a bit of scannability.

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 15 parameters and no output schema, the description carries the return-value burden itself and does so explicitly (max insurable loan, binding test, payment, MIP, DSCR, cash to close). Combined with the 100% schema coverage, an agent has everything needed to call it correctly.

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 every parameter carries its own default/range notes, so the schema does the heavy lifting. The description only restates the input categories (NOI, value, rate, payoff) and the CCN fill rule, which the schema already describes, so it adds little beyond the 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 and resource — runs the SNF Register sizer for HUD Section 232 loan tests — and enumerates the exact tests (1.45x/1.11x DSCR, 80/85% LTV, cost to refinance, 223(a)(7) original principal). No sibling tool does sizing, so the distinction is implicit but 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?

Gives conditional usage: 'Pass a CCN to fill in its active FHA loan,' and the program/track distinction is inferable from the enumerated test set. It does not name sibling alternatives (e.g. use search_nursing_homes to obtain the CCN in the first place) or state when-not to use it, 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.